API reference
SMELT Studio is a hosted product, and everything it does it does over this API. The routes below are the ones your own software can build on. They are served under /v1, and they are the only part of the API we promise to keep working.
Base URL and authentication
Every call goes to https://api.smelt.gimzware.ai/v1 with a SMELT API key as a bearer token. Keys are minted in Studio under Settings, API keys, and are shown once. See the Studio guide for a worked example from a new key to a finished run.
curl https://api.smelt.gimzware.ai/v1/projects \
-H "Authorization: Bearer $SMELT_TOKEN"Every response carries a SMELT-API-Version header naming the contract that served it, so a client can check what it is talking to without parsing a URL.
What we promise
- A route published under
/v1keeps its path, its method and the meaning of its response. It is never renamed or withdrawn without a sunset date recorded in advance, and a build gate stops us doing it by accident. - Responses gain fields over time and never silently lose them. Read the fields you need and ignore the rest.
- New routes and new optional request fields can appear inside
v1. Anything that would break a working client goes in a new version instead.
What is deliberately not in v1
The service serves far more routes than these, and an API key can reach most of them. That is not the same as a promise. The rest exist for the Studio app and change whenever it does, so building on them means picking up the pieces yourself.
- Authoring. Creating and saving workflows means sending a canvas definition, and that format moves with the builder. Build workflows in Studio and run them from here.
- Billing, keys and account settings. These are decisions taken by the person who owns the account, and they are completed in a browser. An API key is refused on all of them.
- Connections and credentials. Provider keys and OAuth connections are set up in Studio, where they can be checked before anything is stored.
- Webhooks and hosted forms. These are not versioned because you do not call them. Studio hands you the whole URL, and the shape of what arrives is decided by whoever is sending it.
Operations
Generated from the running service, so this list is the API rather than a description of it. The full machine-readable specification is at /openapi.json.
Projects and workflows
| Method | Path | What it does |
|---|---|---|
GET | /v1/projects | List projects |
GET | /v1/projects/{id} | Get project |
GET | /v1/projects/{project_id}/workflows | List workflows |
Runs
| Method | Path | What it does |
|---|---|---|
GET | /v1/runs/{id} | Get run |
POST | /v1/runs/{id}/approve | Approve |
POST | /v1/runs/{id}/cancel | Cancel run |
POST | /v1/runs/{id}/reject | Reject |
GET | /v1/runs/{run_id}/events | Execution events |
GET | /v1/runs/{run_id}/steps | Get run steps |
POST | /v1/workflows/{id}/run | Trigger run |
GET | /v1/workflows/{id}/runs | List runs |
Knowledge
| Method | Path | What it does |
|---|---|---|
GET | /v1/knowledge/collections | List collections |
POST | /v1/knowledge/collections | Create collection |
DELETE | /v1/knowledge/collections/{id} | Delete collection |
GET | /v1/knowledge/collections/{id} | Get collection |
PATCH | /v1/knowledge/collections/{id} | Update collection |
GET | /v1/knowledge/collections/{id}/documents | List documents |
POST | /v1/knowledge/collections/{id}/documents | Create document |
DELETE | /v1/knowledge/documents/{id} | Delete document |
Errors and rate limits
A key that is unknown, revoked or expired answers 401. A read-only key sending a write answers 403. Every error carries a code you can branch on rather than a message you have to match.
Requests are limited to 100 a minute per caller, and every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get 429 and a Retry-After in seconds.