skip to content
superbot.gg

Runs

Cloud agent runs: start one on a project, follow its events, cancel it, and get a signed webhook when it settles.

7 operations. Errors link to their row on the overview.

view .mdopenapi

List cloud runslink to List cloud runs

GET /v1/runs

This account’s cloud runs from every source, oldest first, paged by run id.

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

Operation id listRuns in Runs.

Query parameters

  • limit integer optional

    Items per page, 1-100.

  • after_id string optional

    Return the page after this resource id (the previous page’s last_id).

  • before_id string optional

    Return the page before this resource id (the next page’s first_id).

  • status string optional

    Only runs in this status. One of queued, running, done, failed, needs_merge, cancelled.

  • source string optional

    Only runs started by this source. One of app, api, cli, routine, slack, linear, jira, github.

Response 200

A page of runs.

application/json: RunList.

  • object string required

    One of list.

  • data array of Run required
    17 fields
    • 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
    • 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
  • has_more boolean required
  • first_id string | null required

    Id of the first item on this page; pass as before_id for the previous page.

  • last_id string | null required

    Id of the last item on this page; pass as after_id for the next page.

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

429rate_limited

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

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/runs" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const res = await fetch(`https://superbot.gg/v1/runs`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "GET",
    "https://superbot.gg/v1/runs",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 A page of runs.

{
  "object": "list",
  "data": [
    {
      "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,
      "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"
    }
  ],
  "has_more": true,
  "first_id": "your-first-id",
  "last_id": "your-last-id"
}

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.",
  "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"
}

Start a cloud runlink to Start a cloud run

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
  • 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

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

429rate_limited

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

view .mdopenapi
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,
  "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.",
  "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"
}

Find the project for a repositorylink to Find the project for a repository

GET /v1/runs/projects

Your projects whose linked repository is repo, compared after normalising the URL (scheme, git@host: form, a trailing .git and case do not matter). Pass a returned id as project to createRun. Only id and name are returned. An empty list means no project is linked to that repository. Refusal: 400 invalid_repo.

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

Operation id listRunProjects in Runs.

Query parameters

Response 200

The matching projects, possibly none.

application/json: RunProjectList.

  • projects array of object required
    2 fields
    • id string required

      The project id to pass as project to createRun.

    • name string required

      The project’s name in the Superbot app.

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

429rate_limited

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

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/runs/projects?repo=https%3A%2F%2Fgithub.com%2Facme%2Fapp" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const res = await fetch(`https://superbot.gg/v1/runs/projects?repo=https%3A%2F%2Fgithub.com%2Facme%2Fapp`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "GET",
    "https://superbot.gg/v1/runs/projects?repo=https%3A%2F%2Fgithub.com%2Facme%2Fapp",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 The matching projects, possibly none.

{
  "projects": [
    {
      "id": "prj_7f3a",
      "name": "your-name"
    }
  ]
}

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.",
  "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"
}

Get a cloud runlink to Get a cloud run

GET /v1/runs/{run_id}

One run as it stands now.

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

Operation id getRun in Runs.

Path parameters

  • run_id string required

    The run id (a Run id).

Response 200

The run.

application/json: Run.

  • 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
  • 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

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

404not_found

No such resource on this account; check the id.

429rate_limited

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

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const runId = 'RUN_ID';
const res = await fetch(`https://superbot.gg/v1/runs/${runId}`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

run_id = "RUN_ID"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/runs/{run_id}",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 The 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,
  "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"
}

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.",
  "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"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "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"
}

Follow a run’s eventslink to Follow a run’s events

GET /v1/runs/{run_id}/events

With Accept: text/event-stream, server-sent events (id is the event seq; reconnect with Last-Event-ID to resume); the stream ends once the run is final. Otherwise JSON: the events after after, long-polled up to wait seconds.

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

Operation id listRunEvents in Runs.

Path parameters

  • run_id string required

    The run id (a Run id).

Query parameters

  • after string optional

    Only events with a greater seq. Last-Event-ID wins when both are sent.

  • wait string optional

    Long-poll: hold the request up to this many seconds (max 25) for a new event. JSON replies only.

Response 200

The events.

application/json: RunEventList.

text/event-stream: string.

  • object string required

    One of list.

  • data array of RunEvent required
    16 fields
    • object string required

      One of run.event.

    • run_id string required
    • seq integer required

      Per-run sequence number; the SSE id, and what after / Last-Event-ID resume from.

    • type string required

      One of status, result, pr, note_queued, note_delivered.

    • created_at string required
    • note_id string

      On note_queued / note_delivered: the note’s id (never its text).

    • length integer

      On note_queued / note_delivered: the note’s length in characters.

    • status string

      One of queued, running, done, failed, needs_merge, cancelled.

    • branch string
    • landed_commit string
    • usd_spent number
    • summary string | null

      On result only: the runner’s end-of-run diagnostic, as summary on the run (not a title or an answer). Null under zero data retention.

    • pr_url string
    • pr_number integer
    • pr_state string
    • publish_error string
  • next_after integer required

    Pass as after on the next poll.

  • done boolean required

    True once nothing more will happen to the run.

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

404not_found

No such resource on this account; check the id.

429rate_limited

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

view .mdopenapi
Request

curl

curl -sS -X GET "https://superbot.gg/v1/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const runId = 'RUN_ID';
const res = await fetch(`https://superbot.gg/v1/runs/${runId}/events`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

run_id = "RUN_ID"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/runs/{run_id}/events",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 The events.

{
  "object": "list",
  "data": [
    {
      "object": "run.event",
      "run_id": "your-run-id",
      "seq": 0,
      "type": "status",
      "created_at": "your-created-at",
      "note_id": "your-note-id",
      "length": 0,
      "status": "queued",
      "branch": "your-branch",
      "landed_commit": "your-landed-commit",
      "usd_spent": 0,
      "summary": "your-summary",
      "pr_url": "https://example.com",
      "pr_number": 0,
      "pr_state": "your-pr-state",
      "publish_error": "your-publish-error"
    }
  ],
  "next_after": 0,
  "done": true
}

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.",
  "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"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "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"
}

Cancel a cloud runlink to Cancel a cloud run

POST /v1/runs/{run_id}/cancel

Stop the run. A run that already settled is returned as it is.

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

Operation id cancelRun in Runs.

Path parameters

  • run_id string required

    The run id (a Run id).

Response 200

The run after the cancel.

application/json: Run.

  • 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
  • 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

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

404not_found

No such resource on this account; check the id.

429rate_limited

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

view .mdopenapi
Request

curl

curl -sS -X POST "https://superbot.gg/v1/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const runId = 'RUN_ID';
const res = await fetch(`https://superbot.gg/v1/runs/${runId}/cancel`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

run_id = "RUN_ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/runs/{run_id}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())
Response

200 The run after the cancel.

{
  "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,
  "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"
}

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.",
  "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"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "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"
}

Steer a running cloud runlink to Steer a running cloud run

POST /v1/runs/{run_id}/messages

Add a note to a run that is queued or running. The run is not restarted: it reads the note at its next step boundary (never mid-step) and carries on with it as a note from you. Notes are applied oldest first. Refusals: 409 run_not_active (the run settled); 400 invalid_note or note_too_long (over 8192 bytes); 429 too_many_notes (20 notes already waiting), with Retry-After. The run's events record note_queued and note_delivered with the note id and length, never its text.

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

Operation id sendRunMessage in Runs.

Path parameters

  • run_id string required

    The run id (a Run id).

Request body

application/json, required.

  • text string required

    The note, up to 8192 bytes of UTF-8.

Response 202

The note, queued.

application/json: RunNote.

  • id string required
  • object string required

    One of run.note.

  • run_id string required
  • queued_at string required

Errors

StatusCodeWhat to change
400invalid_request

A parameter or body field is invalid; param names it and issues lists every problem.

401unauthorized

Send a live caller key or session as Authorization: Bearer … or x-api-key.

403insufficient_scope

The key lacks the scope in required_scopes; mint a key that holds it.

404not_found

No such resource on this account; check the id.

409conflict

The resource is not in a state that allows this change.

429rate_limited

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

view .mdopenapi
Request

curl

curl -sS -X POST "https://superbot.gg/v1/runs/$RUN_ID/messages" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"Skip the migration for now and focus on the failing test."}'

JavaScript

const runId = 'RUN_ID';
const res = await fetch(`https://superbot.gg/v1/runs/${runId}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"text":"Skip the migration for now and focus on the failing test."}),
});
console.log(res.status, await res.json());

Python

import os
import requests

run_id = "RUN_ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/runs/{run_id}/messages",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"text":"Skip the migration for now and focus on the failing test."},
)
print(res.status_code, res.json())
Response

202 The note, queued.

{
  "id": "note_4f1c9a0b2e7d6c3a18",
  "object": "run.note",
  "run_id": "your-run-id",
  "queued_at": "your-queued-at"
}

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.",
  "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"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

409 The resource is not in a state that allows this change.

{
  "error": "conflict",
  "message": "The resource is not in a state that allows this change.",
  "doc_url": "https://superbot.gg/developers#errors-conflict",
  "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"
}