Start a cloud run

Part of Runs, 7 operations. The overview covers keys, scopes and errors.

POST /v1/runs

Queue a cloud agent run on a project. Refusals: 400 invalid_mode, invalid_landing, invalid_prompt, missing_space, invalid_webhook_url; 429 run_concurrency_limit (the account) or key_run_limit (this key, default 5 queued or running), with Retry-After. Asks the run raises are answered deny, since a key cannot answer them.

A caller key holding runs:write (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id createRun in Runs.

Request body

application/json, required.

project string required
The project to run on.
prompt string required
What the agent should do.
mode string
One of agent, plan, debug. Default agent.
landing string
One of main, pr. Default main.
budget object
Caps for this run. Absent fields fall back to your saved defaults.
3 fields
- minutes number
- usd number
- legs integer
webhook_url string
A public https URL that receives a signed run.settled POST when the run settles.

Response 201

The queued run.

application/json: CreatedRun.

id string required
object string required
One of run.
status string required
queued, running, then one of done, failed, needs_merge (the work is on branch and waits for a merge) or cancelled. One of queued, running, done, failed, needs_merge, cancelled.
source string required
What started the run. Runs started here are api. One of app, api, cli, routine, slack, linear, jira, github.
project string required
The project the run works on.
prompt string | null required
The prompt, which is also the run’s title: show this to name the run. Null under zero data retention.
mode string required
One of agent, plan, debug.
landing string required
main lands the work on the default branch; pr opens a pull request. One of main, pr.
budget RunBudget required
What the run may spend: wall time, USD and legs.
4 fields
- max_wall_ms integer required
- max_usd number required
- max_legs integer required
- leg_ms integer required
usd_spent number | null required
served_model string | null
The model that served the run, as the runner reported it when the run settled (the same served_model the swarm reports). Null until then, and on a run that settled before this field existed.
served_lane string | null
Who served the run’s model calls (the same served_lane the swarm reports). Every cloud run is platform: Superbot’s own model key, charged in credits to the account. Null on a run that predates this field. One of platform, null.
branch string | null required
The branch the work sits on, when it did not land directly.
landed_commit string | null required
summary string | null required
The runner’s end-of-run diagnostic once it settles, a machine-readable line for debugging and for telling a failed run from a finished one (for example done — sandbox fence-only, 127 tool call(s), local space sp_…), and it can name internal ids. It is not a title and not the run’s answer: name the run by prompt, and do not show this text to end users. Null under zero data retention.
pr_url string | null required
url string | null required
A deep link that opens the run’s project in the Superbot app (superbot://project/<id>), when the project id is linkable.
created_at string required
updated_at string required
webhook_secret string
The signing secret for webhook_url, returned ONCE, here. Verify each delivery: X-Superbot-Signature: t=<unix>,v1=<hex> where v1 is HMAC-SHA256(secret, t + "." + body).

Errors

Status	Code	What to change
400	`invalid_request`	A parameter or body field is invalid; `param` names it and `issues` lists every problem.
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`. No key yet: create one at /account/api, or sign a user in at /auth.md.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
429	`rate_limited`	Over the per-key request bucket; retry after `x-ratelimit-reset`.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/runs" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"project":"prj_7f3a","prompt":"Fix the flaky login test."}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/runs`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"project":"prj_7f3a","prompt":"Fix the flaky login test."}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://superbot.gg/v1/runs",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"project":"prj_7f3a","prompt":"Fix the flaky login test."},
)
print(res.status_code, res.json())

Response

201 The queued run.

{
  "id": "run_3k9x0q2m1v",
  "object": "run",
  "status": "queued",
  "source": "app",
  "project": "your-project",
  "prompt": "your-prompt",
  "mode": "agent",
  "landing": "main",
  "budget": {
    "max_wall_ms": 0,
    "max_usd": 0,
    "max_legs": 0,
    "leg_ms": 0
  },
  "usd_spent": 0,
  "served_model": "your-served-model",
  "served_lane": "platform",
  "branch": "your-branch",
  "landed_commit": "your-landed-commit",
  "summary": "your-summary",
  "pr_url": "https://example.com",
  "url": "https://example.com",
  "created_at": "your-created-at",
  "updated_at": "your-updated-at",
  "webhook_secret": "your-webhook-secret"
}

400 The request is malformed or a parameter is invalid; `param` names the field.

{
  "error": "invalid_request",
  "message": "A parameter or body field is invalid; param names it and issues lists every problem.",
  "doc_url": "https://superbot.gg/developers#errors-invalid_request",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

429 Over the per-key request bucket; retry after x-ratelimit-reset.

{
  "error": "rate_limited",
  "message": "Over the per-key request bucket; retry after x-ratelimit-reset.",
  "doc_url": "https://superbot.gg/developers#errors-rate_limited",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}