Customers · API reference

Runs

Start a run of a workflow or an agent, then read its status and output — by polling, or by a webhook when it finishes.

Run a workflow — POST /workflows/{id}/runs
Run an agent — POST /agents/{id}/runs
Get a run — GET /runs/{jobId}
Get a deferred run — GET /deferred-runs/{id}
Run finished — Webhook

POSTRun a workflow#

POST https://app.sushibelt.ai/api/v1/workflows/{id}/runs

Starts a run of one workflow. The cost is estimated and held from your team's credits before anything runs. Use the returned jobId to read the run, or pass callbackUrl to be told when it finishes. A workflow can have one run in progress at a time.

Needs an API key with the runs:create scope. See Scopes.

Parameters#

Run a workflow: parameters
Name	Description
`id`string (uuid) · in path · Required	The workflow to run.

Request body#

Every field is optional. An empty or missing body runs the workflow as it was built.

Run a workflow: request body fields
Name	Description
`inputs`object (key → string) · Optional	Values that replace a step's value for this run, keyed by the step's API input key. A key that matches no step is refused with 422.
`mode`string · Optional	`draft` runs a cheaper pass for trying a workflow out: one variation, fewer sampling steps, short text answers. It is not a discount — a model priced per run costs the same. `preview` behaves like `production`. One of: `production`, `draft`, `preview`.Default: `"production"`
`defer`boolean · Optional	Queue the run to start later instead of now. The answer is 202 with a `deferredJobId`. A deferred run that has not started within 24 hours expires. Follow it with Get a deferred run; a `callbackUrl` passed with it is kept for the run it becomes.Default: `false`
`maxMultiplier`number · Optional	Used only with `defer`: the price multiplier the deferred run waits for.Default: `0.7`
`callbackUrl`string (uri) · Optional	An https URL to send the Run finished webhook to. Anything other than https is refused with 422.
`callbackSecret`string · Optional	A secret of your choosing. When set, each webhook is signed with it in `X-Sushibelt-Signature`.

Example request#

Set SUSHIBELT_API_KEY to your key first, and replace each YOUR_… value.

Run a workflow: request

WORKFLOW_ID="YOUR_WORKFLOW_ID"

curl -X POST "https://app.sushibelt.ai/api/v1/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "subject": "a red fox in snow"
    }
  }'

Responses#

200 OK — The run started.
202 Accepted — With defer: true: the run is queued to start later.
401 Unauthorized — The key is missing, malformed, unknown, revoked or expired. Message: Unauthorized.
402 Payment required — The run would spend more than you allow: the team's balance is below the estimate, the project's hard cap would be passed, one step would pass the team's per-step credit limit, or this key has reached its monthly credit cap. Messages: Insufficient credits, Monthly credit cap reached.
403 Forbidden — The key does not have the runs:create scope, or it is limited to other workflows. Messages: Scope not permitted for this key, Workflow not permitted for this key.
404 Not found — Nothing with this id exists in your team, or the workflow has no canvas. Messages: Workflow not found, Canvas not found.
409 Conflict — This workflow already has a run in progress.
422 Unprocessable content — An inputs key matches no step, callbackUrl is not https, the workflow failed validation, or a step can only run on providers whose integration level bars this run (providers names them, level says why): app_only ("In app · own key on API") runs through the API only on your team’s own key, byok_only only on it, and not_allowed / region_restricted not at all. Add your key under Team → Connections, run the workflow from the app, or pick another provider on that step. Messages: Unknown input key(s): foo, callbackUrl must be a valid https:// URL, DiffusionWorker runs on Fal, which is not available through the API without your own key. Add your key under Connections, run this workflow from the app, or pick another provider on that step..
429 Too many requests — Too many requests with this key. By default a key may make 60 requests a minute. Wait for the number of seconds in Retry-After. Message: Rate limit exceeded. Headers: Retry-After.
500 Server error — Something failed on our side. Message: Server error: ….
503 Service unavailable — The key has a monthly credit cap and it could not be checked just now, so the run was refused rather than started unmetered. Retry after Retry-After seconds. Message: Unable to verify monthly credit cap; try again shortly. Headers: Retry-After.

200 OK: response fields
Name	Description
`jobId`string (uuid) · Required	The run. Pass it to Get a run.
`workflowId`string (uuid) · Required	The workflow that is running.
`status`string · Required	Always `queued`.
`estimatedCredits`number · Required	The estimated cost in credits (1 credit = $0.01). You are charged per step as each finishes.
`stepsCount`integer · Required	No description.

200 OK: example responseJSON

{
  "jobId": "00000000-0000-0000-0000-000000000000",
  "workflowId": "00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "estimatedCredits": 1,
  "stepsCount": 1
}

202 Accepted: response fields
Name	Description
`deferred`boolean · Required	Always `true`.
`deferredJobId`string (uuid) · Required	No description.
`workflowId`string (uuid) · Required	No description.

202 Accepted: example responseJSON

{
  "deferred": true,
  "deferredJobId": "00000000-0000-0000-0000-000000000000",
  "workflowId": "00000000-0000-0000-0000-000000000000"
}

402 Payment required: InsufficientCredits body
Name	Description
`error`string · Required	Always `Insufficient credits`.
`required`number · Required	The credits the run needs held.

402 Payment required: ProjectCapExceeded body
Name	Description
`error`string · Required	Always `Project hard cap exceeded`.
`hardCap`number · Required	No description.
`spent`number · Required	No description.
`estimate`number · Required	No description.

402 Payment required: StepCeilingExceeded body
Name	Description
`error`string · Required	No description.
`nodeType`string · Required	No description.
`estimatedCharge`number · Required	No description.
`ceiling`number · Required	No description.

402 Payment required: MonthlyCapReached body
Name	Description
`error`string · Required	Always `Monthly credit cap reached`.
`monthlyCreditCap`number · Required	No description.
`spentThisMonth`number · Required	No description.
`resets`string · Required	No description.

422 Unprocessable content: UnknownInputKey body
Name	Description
`error`string · Required	No description.
`validKeys`array of string · Required	No description.

422 Unprocessable content: Error body
Name	Description
`error`string · Required	What went wrong, in plain words.

422 Unprocessable content: RunValidationFailed body
Name	Description
`success`boolean · Required	Always `false`.
`errors`array of any · Required	No description.

POSTRun an agent#

POST https://app.sushibelt.ai/api/v1/agents/{id}/runs

Runs an agent's active workflow. If the agent has no active workflow, its newest workflow runs. The response names the workflow that ran in workflowId. The request body and responses are the same as Run a workflow.

Needs an API key with the runs:create scope. See Scopes.

Parameters#

Run an agent: parameters
Name	Description
`id`string (uuid) · in path · Required	The agent to run.

Request body#

Every field is optional. An empty or missing body runs the workflow as it was built.

Run an agent: request body fields
Name	Description
`inputs`object (key → string) · Optional	Values that replace a step's value for this run, keyed by the step's API input key. A key that matches no step is refused with 422.
`mode`string · Optional	`draft` runs a cheaper pass for trying a workflow out: one variation, fewer sampling steps, short text answers. It is not a discount — a model priced per run costs the same. `preview` behaves like `production`. One of: `production`, `draft`, `preview`.Default: `"production"`
`defer`boolean · Optional	Queue the run to start later instead of now. The answer is 202 with a `deferredJobId`. A deferred run that has not started within 24 hours expires. Follow it with Get a deferred run; a `callbackUrl` passed with it is kept for the run it becomes.Default: `false`
`maxMultiplier`number · Optional	Used only with `defer`: the price multiplier the deferred run waits for.Default: `0.7`
`callbackUrl`string (uri) · Optional	An https URL to send the Run finished webhook to. Anything other than https is refused with 422.
`callbackSecret`string · Optional	A secret of your choosing. When set, each webhook is signed with it in `X-Sushibelt-Signature`.

Example request#

Set SUSHIBELT_API_KEY to your key first, and replace each YOUR_… value.

Run an agent: request

AGENT_ID="YOUR_AGENT_ID"

curl -X POST "https://app.sushibelt.ai/api/v1/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "subject": "a red fox in snow"
    }
  }'

Responses#

200 OK — The run started.
202 Accepted — With defer: true: the run is queued to start later.
401 Unauthorized — The key is missing, malformed, unknown, revoked or expired. Message: Unauthorized.
402 Payment required — The run would spend more than you allow: the team's balance is below the estimate, the project's hard cap would be passed, one step would pass the team's per-step credit limit, or this key has reached its monthly credit cap. Messages: Insufficient credits, Monthly credit cap reached.
403 Forbidden — The key does not have the runs:create scope, or it is limited to other workflows. Messages: Scope not permitted for this key, Workflow not permitted for this key.
404 Not found — Nothing with this id exists in your team, or the workflow has no canvas. Messages: Agent not found, No workflow found for this agent, Workflow not found, Canvas not found.
409 Conflict — This workflow already has a run in progress.
422 Unprocessable content — An inputs key matches no step, callbackUrl is not https, the workflow failed validation, or a step can only run on providers whose integration level bars this run (providers names them, level says why): app_only ("In app · own key on API") runs through the API only on your team’s own key, byok_only only on it, and not_allowed / region_restricted not at all. Add your key under Team → Connections, run the workflow from the app, or pick another provider on that step. Messages: Unknown input key(s): foo, callbackUrl must be a valid https:// URL, DiffusionWorker runs on Fal, which is not available through the API without your own key. Add your key under Connections, run this workflow from the app, or pick another provider on that step..
429 Too many requests — Too many requests with this key. By default a key may make 60 requests a minute. Wait for the number of seconds in Retry-After. Message: Rate limit exceeded. Headers: Retry-After.
500 Server error — Something failed on our side. Message: Server error: ….
503 Service unavailable — The key has a monthly credit cap and it could not be checked just now, so the run was refused rather than started unmetered. Retry after Retry-After seconds. Message: Unable to verify monthly credit cap; try again shortly. Headers: Retry-After.

200 OK: response fields
Name	Description
`jobId`string (uuid) · Required	The run. Pass it to Get a run.
`workflowId`string (uuid) · Required	The workflow that is running.
`status`string · Required	Always `queued`.
`estimatedCredits`number · Required	The estimated cost in credits (1 credit = $0.01). You are charged per step as each finishes.
`stepsCount`integer · Required	No description.

200 OK: example responseJSON

{
  "jobId": "00000000-0000-0000-0000-000000000000",
  "workflowId": "00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "estimatedCredits": 1,
  "stepsCount": 1
}

202 Accepted: response fields
Name	Description
`deferred`boolean · Required	Always `true`.
`deferredJobId`string (uuid) · Required	No description.
`workflowId`string (uuid) · Required	No description.

202 Accepted: example responseJSON

{
  "deferred": true,
  "deferredJobId": "00000000-0000-0000-0000-000000000000",
  "workflowId": "00000000-0000-0000-0000-000000000000"
}

402 Payment required: InsufficientCredits body
Name	Description
`error`string · Required	Always `Insufficient credits`.
`required`number · Required	The credits the run needs held.

402 Payment required: ProjectCapExceeded body
Name	Description
`error`string · Required	Always `Project hard cap exceeded`.
`hardCap`number · Required	No description.
`spent`number · Required	No description.
`estimate`number · Required	No description.

402 Payment required: StepCeilingExceeded body
Name	Description
`error`string · Required	No description.
`nodeType`string · Required	No description.
`estimatedCharge`number · Required	No description.
`ceiling`number · Required	No description.

402 Payment required: MonthlyCapReached body
Name	Description
`error`string · Required	Always `Monthly credit cap reached`.
`monthlyCreditCap`number · Required	No description.
`spentThisMonth`number · Required	No description.
`resets`string · Required	No description.

422 Unprocessable content: UnknownInputKey body
Name	Description
`error`string · Required	No description.
`validKeys`array of string · Required	No description.

422 Unprocessable content: Error body
Name	Description
`error`string · Required	What went wrong, in plain words.

422 Unprocessable content: RunValidationFailed body
Name	Description
`success`boolean · Required	Always `false`.
`errors`array of any · Required	No description.

GETGet a run#

GET https://app.sushibelt.ai/api/v1/runs/{jobId}

Returns a run's status, each step's status, and — once the last steps finish — the output. Poll until status is completed or failed; a few seconds between reads is enough. Reading a run never spends credits, so a key over its monthly cap can still read the runs it started.

Needs an API key with the runs:read scope. See Scopes.

Parameters#

Get a run: parameters
Name	Description
`jobId`string (uuid) · in path · Required	The `jobId` returned when the run started.

Example request#

Set SUSHIBELT_API_KEY to your key first, and replace each YOUR_… value.

Get a run: request

JOB_ID="YOUR_JOB_ID"

curl "https://app.sushibelt.ai/api/v1/runs/$JOB_ID" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY"

Responses#

200 OK — The run.
401 Unauthorized — The key is missing, malformed, unknown, revoked or expired. Message: Unauthorized.
403 Forbidden — The key does not have the runs:read scope. Message: Scope not permitted for this key.
404 Not found — No run with this id exists in your team. A run in another team reads the same way. Message: Run not found.
429 Too many requests — Too many requests with this key. By default a key may make 60 requests a minute. Wait for the number of seconds in Retry-After. Message: Rate limit exceeded. Headers: Retry-After.

200 OK: response fields
Name	Description
`jobId`string (uuid) · Required	No description.
`status`string · Required	Once steps exist: `processing`, then `completed` or `failed` (any failed step fails the run). Before that, the run's own state. One of: `queued`, `claimed`, `processing`, `completed`, `failed`, `cancelled`, `stopped`.
`progress`integer · Required	Completed steps as a percentage.
`steps`array of RunStep · Required	No description.
`steps[].node_id`string · Required	No description.
`steps[].step_type`string · Required	No description.
`steps[].status`string · Required	One of: `queued`, `processing`, `completed`, `failed`, `skipped`, `unknown`.
`steps[].error`string · Optional	Why the step failed. Present only on a failed step.
`output`array of RunOutput · Required	What the last steps of the workflow produced — the steps nothing else reads from. Empty until they finish.
`output[].node_id`string · Required	No description.
`output[].step_type`string · Required	No description.
`output[].result`any · Required	What the step produced — for an image step, the image URLs. The shape depends on the node type. Every file URL is Sushibelt's own copy, marked as AI-generated in its metadata (EU AI Act Art. 50(2)) and signed for two hours; a provider's link is never returned. Each file object carries `availability`: `ready` (the `url` is set), `processing` (the copy is still being made — poll again) or `unavailable` (the file could not be stored and marked; `url` is null).
`output[].licence`object · Optional	The licence this output ships under: as strict as the strictest model it comes from. Absent when no model step is involved. Not legal advice.
`output[].licence.commercial_use`string · Required	One of: `yes`, `provider_terms`, `unchecked`, `no`.
`output[].licence.models`array of LicenceModel · Required	No description.
`output[].ai_generated`boolean · Required	True when this output, or any step it comes from, was made by an AI model — the machine-readable marking the EU AI Act (Art. 50) asks for. Images and audio are also marked inside the file.
`output[].generated_by`array of object · Optional	The AI model steps this output comes from. Absent when none.
`output[].generated_by[].node_id`string · Required	No description.
`output[].generated_by[].provider`string · Required	No description.
`output[].generated_by[].model`string or null · Required	No description.

200 OK: example responseJSON

{
  "jobId": "00000000-0000-0000-0000-000000000000",
  "status": "queued",
  "progress": 1,
  "steps": [
    {
      "node_id": "string",
      "step_type": "string",
      "status": "queued",
      "error": "string"
    }
  ],
  "output": [
    {
      "node_id": "string",
      "step_type": "string",
      "result": null,
      "licence": {
        "commercial_use": "yes",
        "models": [
          {
            "node_id": "string",
            "provider_key": "string",
            "model": "string",
            "licence": "string",
            "licence_url": "string",
            "commercial_use": "yes",
            "terms_url": "string",
            "stamped_at": "2026-09-29T12:00:00Z"
          }
        ]
      },
      "ai_generated": true,
      "generated_by": [
        {
          "node_id": "string",
          "provider": "string",
          "model": "string"
        }
      ]
    }
  ]
}

GETGet a deferred run#

GET https://app.sushibelt.ai/api/v1/deferred-runs/{id}

Returns a run you started with defer: true: whether it is still waiting, has started, expired or was cancelled. Once it has started, jobId is the run it became — read that with Get a run.

Needs an API key with the runs:read scope. See Scopes.

Parameters#

Get a deferred run: parameters
Name	Description
`id`string (uuid) · in path · Required	The `deferredJobId` returned when the run was deferred.

Example request#

Set SUSHIBELT_API_KEY to your key first, and replace each YOUR_… value.

Get a deferred run: request

DEFERRED-RUN_ID="YOUR_DEFERRED-RUN_ID"

curl "https://app.sushibelt.ai/api/v1/deferred-runs/$DEFERRED-RUN_ID" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY"

Responses#

200 OK — The deferred run.
401 Unauthorized — The key is missing, malformed, unknown, revoked or expired. Message: Unauthorized.
403 Forbidden — The key does not have the runs:read scope. Message: Scope not permitted for this key.
404 Not found — No deferred run with this id exists in your team. One in another team reads the same way. Message: Deferred run not found.
429 Too many requests — Too many requests with this key. By default a key may make 60 requests a minute. Wait for the number of seconds in Retry-After. Message: Rate limit exceeded. Headers: Retry-After.

200 OK: response fields
Name	Description
`deferredJobId`string (uuid) · Required	No description.
`workflowId`string (uuid) · Required	No description.
`status`string · Required	`waiting` until the price multiplier reaches `maxMultiplier`; `dispatched` once the run has started (see `jobId`); `expired` if it did not start within 24 hours, or could not be paid for or allowed when its turn came; `cancelled` if its key was revoked or expired, or you cancelled it. One of: `waiting`, `dispatched`, `expired`, `cancelled`.
`maxMultiplier`number · Required	No description.
`createdAt`string (date-time) · Required	No description.
`expiresAt`string or null (date-time) · Required	No description.
`dispatchedAt`string or null (date-time) · Required	No description.
`jobId`string or null (uuid) · Required	The run it became, once `dispatched`. Pass it to Get a run.

200 OK: example responseJSON

{
  "deferredJobId": "00000000-0000-0000-0000-000000000000",
  "workflowId": "00000000-0000-0000-0000-000000000000",
  "status": "waiting",
  "maxMultiplier": 1,
  "createdAt": "2026-09-29T12:00:00Z",
  "expiresAt": "2026-09-29T12:00:00Z",
  "dispatchedAt": "2026-09-29T12:00:00Z",
  "jobId": "00000000-0000-0000-0000-000000000000"
}

WebhookRun finished#

We send POST to the callbackUrl you passed when you started the run.

Sent to the callbackUrl you passed when you started a run, once the run completes or fails. The body is the same as Get a run, plus event. Reply with any 2xx status within 8 seconds. Anything else is retried: after 2 minutes, then twice as long each time, at most an hour apart, for 5 attempts in all. Because a delivery can arrive twice, treat jobId and event together as an idempotency key. When you passed callbackSecret, check X-Sushibelt-Signature: compute HMAC-SHA256 of the raw body with your secret, hex-encode it, and compare it to the value after sha256= in constant time.

Headers#

Run finished: headers
Name	Description
`X-Sushibelt-Event`string · in header · Required	What happened: `run.completed`, `run.failed`, `run.stopped` (someone stopped it) or `run.cancelled` (someone cancelled it).
`X-Sushibelt-Signature`string · in header · Optional	Sent only when you passed `callbackSecret`: `sha256=` followed by the hex HMAC-SHA256 of the raw body.

Body#

The same fields as Get a run, plus event.

Run finished: body fields
Name	Description
`event`string · Required	One of: `run.completed`, `run.failed`, `run.stopped`, `run.cancelled`.
`jobId`string (uuid) · Required	No description.
`status`string · Required	No description.
`progress`integer · Optional	No description.
`steps`array of RunStep · Optional	No description.
`steps[].node_id`string · Required	No description.
`steps[].step_type`string · Required	No description.
`steps[].status`string · Required	One of: `queued`, `processing`, `completed`, `failed`, `skipped`, `unknown`.
`steps[].error`string · Optional	Why the step failed. Present only on a failed step.
`output`array of RunOutput · Optional	No description.
`output[].node_id`string · Required	No description.
`output[].step_type`string · Required	No description.
`output[].result`any · Required	What the step produced — for an image step, the image URLs. The shape depends on the node type. Every file URL is Sushibelt's own copy, marked as AI-generated in its metadata (EU AI Act Art. 50(2)) and signed for two hours; a provider's link is never returned. Each file object carries `availability`: `ready` (the `url` is set), `processing` (the copy is still being made — poll again) or `unavailable` (the file could not be stored and marked; `url` is null).
`output[].licence`object · Optional	The licence this output ships under: as strict as the strictest model it comes from. Absent when no model step is involved. Not legal advice.
`output[].licence.commercial_use`string · Required	One of: `yes`, `provider_terms`, `unchecked`, `no`.
`output[].licence.models`array of LicenceModel · Required	No description.
`output[].ai_generated`boolean · Required	True when this output, or any step it comes from, was made by an AI model — the machine-readable marking the EU AI Act (Art. 50) asks for. Images and audio are also marked inside the file.
`output[].generated_by`array of object · Optional	The AI model steps this output comes from. Absent when none.
`output[].generated_by[].node_id`string · Required	No description.
`output[].generated_by[].provider`string · Required	No description.
`output[].generated_by[].model`string or null · Required	No description.

Example delivery#

Example delivery bodyJSON

{
  "event": "run.completed",
  "jobId": "00000000-0000-0000-0000-000000000000",
  "status": "string",
  "progress": 1,
  "steps": [
    {
      "node_id": "string",
      "step_type": "string",
      "status": "queued",
      "error": "string"
    }
  ],
  "output": [
    {
      "node_id": "string",
      "step_type": "string",
      "result": null,
      "licence": {
        "commercial_use": "yes",
        "models": [
          {
            "node_id": "string",
            "provider_key": "string",
            "model": "string",
            "licence": "string",
            "licence_url": "string",
            "commercial_use": "yes",
            "terms_url": "string",
            "stamped_at": "2026-09-29T12:00:00Z"
          }
        ]
      },
      "ai_generated": true,
      "generated_by": [
        {
          "node_id": "string",
          "provider": "string",
          "model": "string"
        }
      ]
    }
  ]
}

Your response#

2XX Success — You received the delivery. Nothing is retried.

Runs

POSTRun a workflow#

Parameters#

Request body#

Example request#

Responses#

POSTRun an agent#

Parameters#

Request body#

Example request#

Responses#

GETGet a run#

Parameters#

Example request#

Responses#

GETGet a deferred run#

Parameters#

Example request#

Responses#

WebhookRun finished#

Headers#

Body#

Example delivery#

Your response#

Next steps