Customers · API reference

API overview

The base URL, how to authenticate, what each scope unlocks, rate limits, and every error the API returns.

Before you start: A Sushibelt team you belong to, with access to its API keys.
You'll end with: A key that works, and a map of every endpoint and error.

The Sushibelt API lets you list and create workflows, start runs, and read their status and output. A run started through the API is the same as a run started from the canvas: it is estimated first, credits are held, each step is charged when it finishes, and outputs land in your team's library.

Requests and responses are JSON. Every request except the one that fetches this document needs a team API key.

Base URL#

Every path in this reference is relative to https://app.sushibelt.ai/api/v1.

Authentication#

A team API key, sent as Authorization: Bearer sk_live_…. Create one in the app under Team settings → API keys; the full key is shown once, when you create it. A key belongs to one team and reaches only that team's workflows and runs. A key can be limited to certain workflows, to certain scopes, and to a monthly credit cap; with no scopes set, it has all of them. A missing, unknown, revoked or expired key is refused with 401.

Warning: keep your key secret

A key can spend your team's credits. Keep it on a server or in a secret store, never in a browser or an app you ship. If a key leaks, revoke it under Team settings → API keys; it stops working at once.

An authenticated request

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

Scopes#

A scope limits what a key can call. A key with no scopes set has every scope. Calling an endpoint outside a key's scopes answers 403.

Scopes and the endpoints each unlocks
Scope	Description
`workflows:read`	List the workflows a key can run. Unlocks `GET /workflows`.
`workflows:write`	Create a workflow from a step list. Unlocks `POST /workflows`.
`runs:create`	Start a run of a workflow or an agent. The only scope that spends credits, and the only one a monthly credit cap can refuse. Unlocks `POST /workflows/{id}/runs`, `POST /agents/{id}/runs`.
`runs:read`	Read a run's status, steps and output. Unlocks `GET /runs/{jobId}`, `GET /deferred-runs/{id}`.

Rate limits#

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.

Errors#

An error answers with a status code and a JSON body. Most bodies have an error field with a message, and some add fields that explain it — the credits a run needs, or the input keys a workflow accepts. One does not: a workflow that fails validation when you run it answers 422 with success and errors instead.

400 Bad request#

Create a workflow: The request is missing something: a name, at least one step, or exactly one of agentId and projectId.

401 Unauthorized#

List workflows: The key is missing, malformed, unknown, revoked or expired.
Create a workflow: The key is missing, malformed, unknown, revoked or expired.
Run a workflow: The key is missing, malformed, unknown, revoked or expired.
Run an agent: The key is missing, malformed, unknown, revoked or expired.
Get a run: The key is missing, malformed, unknown, revoked or expired.
Get a deferred run: The key is missing, malformed, unknown, revoked or expired.

402 Payment required#

Run a workflow: 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.
Run an agent: 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.

403 Forbidden#

List workflows: The key does not have the workflows:read scope.
Create a workflow: The key does not have the workflows:write scope, or it is limited to certain workflows.
Run a workflow: The key does not have the runs:create scope, or it is limited to other workflows.
Run an agent: The key does not have the runs:create scope, or it is limited to other workflows.
Get a run: The key does not have the runs:read scope.
Get a deferred run: The key does not have the runs:read scope.

404 Not found#

Create a workflow: The agent or project does not exist in your team.
Run a workflow: Nothing with this id exists in your team, or the workflow has no canvas.
Run an agent: Nothing with this id exists in your team, or the workflow has no canvas.
Get a run: No run with this id exists in your team. A run in another team reads the same way.
Get a deferred run: No deferred run with this id exists in your team. One in another team reads the same way.

409 Conflict#

Run a workflow: This workflow already has a run in progress.
Run an agent: This workflow already has a run in progress.

422 Unprocessable content#

Create a workflow: The steps do not make a valid workflow: an unknown node type, a repeated step key, an input that names no step, or a graph that fails validation (the reasons are listed in errors).
Run a workflow: 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.
Run an agent: 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.

429 Too many requests#

List workflows: 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.
Create a workflow: 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.
Run a workflow: 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.
Run an agent: 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.
Get a run: 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.
Get a deferred run: 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.

500 Server error#

Create a workflow: Something failed on our side.
Run a workflow: Something failed on our side.
Run an agent: Something failed on our side.

503 Service unavailable#

Run a workflow: 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.
Run an agent: 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.

Endpoints#

Workflows#

List workflows — GET /workflows
Create a workflow — POST /workflows

Runs#

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

Specification#

Get this API description — GET /openapi.json

The OpenAPI document#

This reference is generated from one OpenAPI 3.1.0 document. Fetch it at /api/v1/openapi.json — no key needed — to generate a client or to describe the API to an agent.