# Sushibelt API

> Create and run Sushibelt workflows from your own code.

Every endpoint is under https://app.sushibelt.ai/api/v1 and takes a team API key as a Bearer token (`Authorization: Bearer sk_live_…`); a key carries scopes, and each endpoint names the one it needs. The full machine-readable description is the OpenAPI 3.1 document at https://app.sushibelt.ai/api/v1/openapi.json.

## API reference

- [OpenAPI document](https://app.sushibelt.ai/api/v1/openapi.json): This API description itself, as OpenAPI 3.1, for code generators and agents.
- [List workflows](https://app.sushibelt.ai/docs/api/workflows#list-workflows): `GET /workflows`. Lists the workflows this key can run, newest change first.
- [Create a workflow](https://app.sushibelt.ai/docs/api/workflows#create-workflow): `POST /workflows`. Creates a workflow from a list of steps.
- [Run a workflow](https://app.sushibelt.ai/docs/api/runs#run-workflow): `POST /workflows/{id}/runs`. Starts a run of one workflow.
- [Run an agent](https://app.sushibelt.ai/docs/api/runs#run-agent): `POST /agents/{id}/runs`. Runs an agent's active workflow.
- [Get a run](https://app.sushibelt.ai/docs/api/runs#get-run): `GET /runs/{jobId}`. Returns a run's status, each step's status, and — once the last steps finish — the output.
- [Get a deferred run](https://app.sushibelt.ai/docs/api/runs#get-deferred-run): `GET /deferred-runs/{id}`. Returns a run you started with `defer: true`: whether it is still waiting, has started, expired or was cancelled.
- [Run finished](https://app.sushibelt.ai/docs/api/runs#run-finished): `webhook runFinished`. Sent to the `callbackUrl` you passed when you started a run, once the run completes or fails.
- [Get this API description](https://app.sushibelt.ai/docs/api/specification#get-open-api-document): `GET /openapi.json`. Returns this document: the whole API as OpenAPI 3.1.

## Get started

- [Sushibelt docs](https://app.sushibelt.ai/docs): Run Sushibelt workflows from your own code, or sell your model API through Sushibelt.

## Customers

- [Quickstart](https://app.sushibelt.ai/docs/quickstart): Create an API key, run a workflow and download what it made, in five minutes, with curl, TypeScript or Python.
- [Concepts](https://app.sushibelt.ai/docs/concepts): Workflows, runs, steps, credits, outputs, models and licences: what each word means for your code.
- [Run a workflow from code](https://app.sushibelt.ai/docs/guides/run-from-code): Turn the quickstart into code you can leave running: a reusable client with retries, time limits and step errors.
- [Pass inputs to a run](https://app.sushibelt.ai/docs/guides/inputs): Name a workflow's text on the canvas, then replace it for each run from your code.
- [Poll or get a webhook](https://app.sushibelt.ai/docs/guides/polling-and-webhooks): Learn that a run has ended: read it every few seconds, or have Sushibelt call your HTTPS endpoint and verify its signature.
- [Deliver to GitHub, GitLab, Plastic SCM or Unity](https://app.sushibelt.ai/docs/guides/delivery): End a workflow with a commit: each run's files land in your repository, with an optional manifest of what they are.
- [Bring your own provider key](https://app.sushibelt.ai/docs/guides/byok): Run models on your own provider account: the provider bills you, and Sushibelt charges a small fee per step.
- [Cap your spend](https://app.sushibelt.ai/docs/guides/spend-limits): Every limit on what runs may cost: the team balance, a key's monthly cap, the per-step ceiling, a project's hard cap and draft runs.
- [Handle errors and retries](https://app.sushibelt.ai/docs/guides/errors-and-retries): Every status the API answers with and what to do about it, which requests are safe to repeat, and how to resume a failed run.
- [Use a model's licence in your product](https://app.sushibelt.ai/docs/guides/licences): Read the licence each output was made under, what commercial_use means, and how to credit a model.
- [API overview](https://app.sushibelt.ai/docs/api): The base URL, how to authenticate, what each scope unlocks, rate limits, and every error the API returns.
- [Workflow format](https://app.sushibelt.ai/docs/workflow-format): The workflow definition you send to create a workflow: steps, handles, port types, what may connect to what, and every node type.
- [Agents](https://app.sushibelt.ai/docs/agents): Drive Sushibelt from your own AI agent with the API as it is today, safely, and what the assistant in the app does.
- [Connect your AI agent (MCP)](https://app.sushibelt.ai/docs/agents/mcp): Connect Claude Code, Cursor or any MCP client to Sushibelt with a team API key: the endpoint, the config, the tools and resources.
- [Changelog](https://app.sushibelt.ai/docs/changelog): Every change to the API and these docs that affects your code, newest first.

## Providers

- [Sell on Sushibelt](https://app.sushibelt.ai/docs/providers): What selling your model API through Sushibelt means: a storefront, listings sold under your name, your price plus Sushibelt's markup, and payouts.
- [Quickstart](https://app.sushibelt.ai/docs/providers/quickstart): Ask for a storefront, link Stripe so you can be paid, get approved, and put your first listing live.
- [Price a listing](https://app.sushibelt.ai/docs/providers/pricing): Pricing units, declaring a price, the notice a rise needs, and what customers pay.
- [Get paid](https://app.sushibelt.ai/docs/providers/payouts): What you earn, the minimum payout, how to request one, when it arrives, and what a reversal does.
- [Claim your provider](https://app.sushibelt.ai/docs/providers/claim): Take over the provider Sushibelt runs for your API: prove your domain, declare your endpoint and price, pass a probe, and get handed over.
- [Run your own endpoint](https://app.sushibelt.ai/docs/providers/your-endpoint): What Sushibelt sends your API in each of the three families, what it expects back, and how it counts usage.
- [Keep your listing healthy](https://app.sushibelt.ai/docs/providers/health): Probes, success rate, whose failures count, what hands a provider back to Sushibelt, and replacing your key.
- [Transport declarations](https://app.sushibelt.ai/docs/providers/reference/transports): Every field of the openai-compatible, sync-rest and submit-poll declarations, with a complete example of each.
- [Capability descriptors](https://app.sushibelt.ai/docs/providers/reference/descriptors): How a model's request body is described: params, inputs, constants, enum maps, derivations and omissions.
- [Probe results and errors](https://app.sushibelt.ai/docs/providers/reference/probe): What a probe sends, each outcome and what it means, and every problem a declaration can be refused for.