Builds

X builds: tag @superbot_gg on X and a live app is built, audited and published at <slug>.superbot.sh.

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

view .md openapi

List your X builds jobslink to List your X builds jobs

GET /v1/x-builds

Newest first, cursored by job id. Only the calling account’s jobs are ever listed.

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

Operation id listXBuilds in Builds.

Query parameters

status string optional
Only jobs in this status: one of queued, screening, building, auditing, publishing, verifying, fixing, drafting, done, refused, failed, cancelled. Anything else is a 400. One of queued, screening, building, auditing, publishing, verifying, fixing, drafting, done, refused, failed, cancelled.
author_id string optional
Only jobs for this X author id.
platform string optional
Which intake: x (the default: tagged posts only), api (plain prompts from API callers) or all. Anything else is a 400. One of x, api, all.
limit integer optional
Rows to return, 1-200; default 50.
cursor string optional
The next_cursor of the previous page.

Response 200

One page of jobs.

application/json: object.

object string required
One of list.
data array of XbJobView required
3 fields
- id string required
- status string required
- lane string required
has_more boolean required
next_cursor string | null required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

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

JavaScript

const res = await fetch(`https://superbot.gg/v1/x-builds`, {
  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/x-builds",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 One page of jobs.

{
  "object": "list",
  "data": [
    {
      "id": "your-id",
      "status": "your-status",
      "lane": "your-lane"
    }
  ],
  "has_more": true,
  "next_cursor": "your-next-cursor"
}

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

Submit an X post for a buildlink to Submit an X post for a build

POST /v1/x-builds

Queue one build for a tagged X post. Idempotent on source.post_id (and on Idempotency-Key): a repeat returns the existing job with 200. Refusals — 403 author_blocked, 409 author_active_job, 409 conversation_active_job, 429 author_daily_limit (with Retry-After), 503 queue_full / daily_cap / intake_paused / app_capacity / xbuilds_not_configured — are intake decisions, never a partially created job.

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

Operation id createXBuild in Builds.

Header parameters

idempotency-key string optional
Optional. A repeat with the same key returns the first job with 200 instead of creating a second.

Request body

application/json, required.

source XbSource | XbApiSource required

Response 200

This post already has a job; the existing one is returned.

application/json: object.

id string required
status string required
position number required
eta_s number required
existing boolean required
One of true.

Response 201

The job was queued.

application/json: object.

id string required
status string required
position number required
eta_s number required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
409	`conflict`	The resource is not in a state that allows this change.
429	`rate_limited`	Over the per-key request bucket; retry after `x-ratelimit-reset`.
503		Intake is closed: the queue is full, the daily cap is spent, intake is paused, the app cap is reached or the lane is not configured.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source":"your-source"}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/x-builds`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"source":"your-source"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "POST",
    "https://superbot.gg/v1/x-builds",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"source":"your-source"},
)
print(res.status_code, res.json())

Response

200 This post already has a job; the existing one is returned.

{
  "id": "your-id",
  "status": "your-status",
  "position": 0,
  "eta_s": 0,
  "existing": true
}

201 The job was queued.

{
  "id": "your-id",
  "status": "your-status",
  "position": 0,
  "eta_s": 0
}

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

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

503 Intake is closed: the queue is full, the daily cap is spent, intake is paused, the app cap is reached or the lane is not configured.

{
  "error": "insufficient_scope",
  "message": "your-message",
  "doc_url": "https://example.com",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d",
  "param": "your-param"
}

Read X builds statslink to Read X builds stats

GET /v1/x-builds/stats

Counts by status, lane and refusal category, p50/p90 of total_s and of every stage, SLO misses, masq backoffs, in-flight Opus legs, live apps against the cap, and the queue state.

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

Operation id getXBuildStats in Builds.

Query parameters

window string optional
Window as Nh hours; default 24h.

Response 200

The window’s numbers.

application/json: XbStats.

window string required
accepted number required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

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

JavaScript

const res = await fetch(`https://superbot.gg/v1/x-builds/stats`, {
  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/x-builds/stats",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The window’s numbers.

{
  "window": "your-window",
  "accepted": 0
}

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

Read the X builds queuelink to Read the X builds queue

GET /v1/x-builds/queue

The queue in dispatch order, with the concurrency the dispatcher is actually using (which drops to 2 while masq is backing off).

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

Operation id getXBuildQueue in Builds.

Response 200

The queue.

application/json: XbQueueView.

paused boolean required
max_concurrent number required
max_queue number required
queued number required
running number required

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

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

JavaScript

const res = await fetch(`https://superbot.gg/v1/x-builds/queue`, {
  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/x-builds/queue",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The queue.

{
  "paused": true,
  "max_concurrent": 0,
  "max_queue": 0,
  "queued": 0,
  "running": 0
}

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

Change the queue configlink to Change the queue config

PATCH /v1/x-builds/queue

max_concurrent, max_queue and paused are persisted in <dataDir>/x-builds/config.json; paused: true is the operator kill switch the poller flips on an account-wide X refusal.

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

Operation id updateXBuildQueue in Builds.

Request body

application/json, required.

max_concurrent integer
max_queue integer
paused boolean

Response 200

The queue, after the change.

application/json: XbQueueView.

paused boolean required
max_concurrent number required
max_queue number required
queued number required
running number required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

curl -sS -X PATCH "https://superbot.gg/v1/x-builds/queue" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"max_concurrent":1,"max_queue":1,"paused":true}'

JavaScript

const res = await fetch(`https://superbot.gg/v1/x-builds/queue`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"max_concurrent":1,"max_queue":1,"paused":true}),
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "PATCH",
    "https://superbot.gg/v1/x-builds/queue",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"max_concurrent":1,"max_queue":1,"paused":True},
)
print(res.status_code, res.json())

Response

200 The queue, after the change.

{
  "paused": true,
  "max_concurrent": 0,
  "max_queue": 0,
  "queued": 0,
  "running": 0
}

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

List blocked X authorslink to List blocked X authors

GET /v1/x-builds/blocklist

Every author the lane will not build for, with the reason it was recorded.

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

Operation id listXBuildBlocklist in Builds.

Response 200

The blocklist.

application/json: object.

object string required
One of list.
data array of XbBlock required
3 fields
- author_id string required
- reason string required
  One of operator, optout, blocked_us.
- created_at string required

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

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

JavaScript

const res = await fetch(`https://superbot.gg/v1/x-builds/blocklist`, {
  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/x-builds/blocklist",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The blocklist.

{
  "object": "list",
  "data": [
    {
      "author_id": "your-author-id",
      "reason": "operator",
      "created_at": "your-created-at"
    }
  ]
}

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

Block an X authorlink to Block an X author

PUT /v1/x-builds/blocklist/{author_id}

reason is operator, optout or blocked_us (the last one is what the poller records when X refuses a reply).

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

Operation id blockXAuthor in Builds.

Path parameters

author_id string required
The X author’s numeric id.

Request body

application/json, required.

reason string required
One of operator, optout, blocked_us.

Response 201

The row as stored.

application/json: XbBlock.

author_id string required
reason string required
One of operator, optout, blocked_us.
created_at string required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.

view .md openapi

Request

curl

curl -sS -X PUT "https://superbot.gg/v1/x-builds/blocklist/$AUTHOR_ID" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"reason":"operator"}'

JavaScript

const authorId = 'AUTHOR_ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/blocklist/${authorId}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"reason":"operator"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

author_id = "AUTHOR_ID"
res = requests.request(
    "PUT",
    f"https://superbot.gg/v1/x-builds/blocklist/{author_id}",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"reason":"operator"},
)
print(res.status_code, res.json())

Response

201 The row as stored.

{
  "author_id": "your-author-id",
  "reason": "operator",
  "created_at": "your-created-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"
}

Unblock an X authorlink to Unblock an X author

DELETE /v1/x-builds/blocklist/{author_id}

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

Operation id unblockXAuthor in Builds.

Path parameters

author_id string required

Response 200

The author is no longer blocked.

application/json: object.

ok boolean required
One of true.

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.

view .md openapi

Request

curl

curl -sS -X DELETE "https://superbot.gg/v1/x-builds/blocklist/$AUTHOR_ID" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const authorId = 'AUTHOR_ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/blocklist/${authorId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

author_id = "AUTHOR_ID"
res = requests.request(
    "DELETE",
    f"https://superbot.gg/v1/x-builds/blocklist/{author_id}",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The author is no longer blocked.

{
  "ok": true
}

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

Read one X builds joblink to Read one X builds job

GET /v1/x-builds/{id}

The job without its owning account, plus queue_position and result (live url, slug, a signed screenshot link, reply, verify, project id).

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

Operation id getXBuild in Builds.

Path parameters

id string required
The job id (xb_…).

Response 200

The job.

application/json: XbJobView.

id string required
status string required
lane string required

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.

view .md openapi

Request

curl

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

JavaScript

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

Python

import os
import requests

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

Response

200 The job.

{
  "id": "your-id",
  "status": "your-status",
  "lane": "your-lane"
}

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

Read a build screenshotlink to Read a build screenshot

GET /v1/x-builds/{id}/screenshot

The 1600×900 hero PNG, read in-process from the artifact store. 404 until the reply stage staged it.

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

Operation id getXBuildScreenshot in Builds.

Path parameters

id string required

Response 200

The PNG bytes.

image/png: string (binary).

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.

view .md openapi

Request

curl

curl -sS -X GET "https://superbot.gg/v1/x-builds/$ID/screenshot" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

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

Python

import os
import requests

id = "ID"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/x-builds/{id}/screenshot",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The PNG bytes.

image/png: string (binary)

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

Read a build motion cliplink to Read a build motion clip

GET /v1/x-builds/{id}/clip

The motion clip as video/mp4, read in-process from the artifact store, with byte ranges (Range: bytes=… answers 206 with Content-Range; an unsatisfiable range 416). 404 whenever the job has no servable clip: none, not ok or degraded, withheld, or expired.

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

Operation id getXBuildClip in Builds.

Path parameters

id string required

Response 200

The whole clip.

video/mp4: string (binary).

Response 206

The requested byte range.

video/mp4: string (binary).

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.

view .md openapi

Request

curl

curl -sS -X GET "https://superbot.gg/v1/x-builds/$ID/clip" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

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

Python

import os
import requests

id = "ID"
res = requests.request(
    "GET",
    f"https://superbot.gg/v1/x-builds/{id}/clip",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The whole clip.

video/mp4: string (binary)

206 The requested byte range.

video/mp4: string (binary)

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

Cancel an X builds joblink to Cancel an X builds job

POST /v1/x-builds/{id}/cancel

Stops the job and releases its author slot. A cancel never counts against the author’s daily budget.

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

Operation id cancelXBuild in Builds.

Path parameters

id string required

Response 200

The job is cancelled.

application/json: object.

ok boolean required
One of true.
id string required

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.

view .md openapi

Request

curl

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

JavaScript

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

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The job is cancelled.

{
  "ok": true,
  "id": "your-id"
}

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

Redraft a build’s replylink to Redraft a build’s reply

POST /v1/x-builds/{id}/reply-draft

Re-run the reply bot for a published job (after a reply was refused or the operator wanted different wording) and return the new sentence.

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

Operation id redraftXBuildReply in Builds.

Path parameters

id string required

Response 200

The new reply draft.

application/json: object.

reply any

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.
502		The drafter could not be reached.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds/$ID/reply-draft" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/reply-draft`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/reply-draft",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The new reply draft.

{
  "reply": "your-reply"
}

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

502 The drafter could not be reached.

{
  "error": "insufficient_scope",
  "message": "your-message",
  "doc_url": "https://example.com",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d",
  "param": "your-param"
}

Move a job in the queuelink to Move a job in the queue

POST /v1/x-builds/{id}/move

Places the job at position (1 = next) by rewriting its deadline_at into the gap, so the earliest-deadline-first order survives a restart.

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

Operation id moveXBuild in Builds.

Path parameters

id string required

Request body

application/json, required.

position integer required

Response 200

Done.

application/json: object.

ok boolean required
One of true.
id string required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds/$ID/move" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"position":1}'

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/move`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"position":1}),
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/move",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"position":1},
)
print(res.status_code, res.json())

Response

200 Done.

{
  "ok": true,
  "id": "your-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"
}

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

Requeue a job at the frontlink to Requeue a job at the front

POST /v1/x-builds/{id}/requeue

Puts an active job back in the queue keeping its deadline_at, which puts it ahead of anything admitted later.

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

Operation id requeueXBuild in Builds.

Path parameters

id string required

Response 200

Done.

application/json: object.

ok boolean required
One of true.
id string required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds/$ID/requeue" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/requeue`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/requeue",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 Done.

{
  "ok": true,
  "id": "your-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"
}

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

Resume a bundled job at the audit gatelink to Resume a bundled job at the audit gate

POST /v1/x-builds/{id}/resume

Re-enters a job that built and bundled but failed at the gate AT THE GATE, over its stored artifact: the audit and acceptance stages run again and, if they pass, the ordinary publish and verify path follows. No plan or build runs. Refused with 409 and the named reason when the job has no bundle, is not terminal, is already published, has no spec, or its artifact is gone or no longer matches the bundle sha256.

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

Operation id resumeXBuild in Builds.

Path parameters

id string required

Response 200

Done.

application/json: object.

ok boolean required
One of true.
id string required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds/$ID/resume" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/resume`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/resume",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 Done.

{
  "ok": true,
  "id": "your-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"
}

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

Pin a job to the frontlink to Pin a job to the front

POST /v1/x-builds/{id}/pin

Marks the job pinned and floats it to the front of the queue.

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

Operation id pinXBuild in Builds.

Path parameters

id string required

Response 200

Done.

application/json: object.

ok boolean required
One of true.
id string required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds/$ID/pin" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/pin`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/pin",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 Done.

{
  "ok": true,
  "id": "your-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"
}

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

Unpin a joblink to Unpin a job

POST /v1/x-builds/{id}/unpin

Clears the pinned flag (the deadline_at already written stays).

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

Operation id unpinXBuild in Builds.

Path parameters

id string required

Response 200

Done.

application/json: object.

ok boolean required
One of true.
id string required

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`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.

view .md openapi

Request

curl

curl -sS -X POST "https://superbot.gg/v1/x-builds/$ID/unpin" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/unpin`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "POST",
    f"https://superbot.gg/v1/x-builds/{id}/unpin",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 Done.

{
  "ok": true,
  "id": "your-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"
}

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

Take down a published applink to Take down a published app

DELETE /v1/x-builds/{id}/publish

Deletes the worker, its assets and the hostname binding for a published job. Irreversible.

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

Operation id takedownXBuild in Builds.

Path parameters

id string required

Response 200

The app is gone.

application/json: object.

ok boolean required
One of true.
id string required

Errors

Status	Code	What to change
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
409	`conflict`	The resource is not in a state that allows this change.
502		Cloudflare refused the takedown.

view .md openapi

Request

curl

curl -sS -X DELETE "https://superbot.gg/v1/x-builds/$ID/publish" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const id = 'ID';
const res = await fetch(`https://superbot.gg/v1/x-builds/${id}/publish`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

id = "ID"
res = requests.request(
    "DELETE",
    f"https://superbot.gg/v1/x-builds/{id}/publish",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 The app is gone.

{
  "ok": true,
  "id": "your-id"
}

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

502 Cloudflare refused the takedown.

{
  "error": "insufficient_scope",
  "message": "your-message",
  "doc_url": "https://example.com",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d",
  "param": "your-param"
}

List your X builds jobs#link to List your X builds jobs

Query parameters

Response 200

Errors

Submit an X post for a build#link to Submit an X post for a build

Header parameters

Request body

Response 200

Response 201

Errors

Read X builds stats#link to Read X builds stats

Query parameters

Response 200

Errors

Read the X builds queue#link to Read the X builds queue

Response 200

Errors

Change the queue config#link to Change the queue config

Request body

Response 200

Errors

List blocked X authors#link to List blocked X authors

Response 200

Errors

Block an X author#link to Block an X author

Path parameters

Request body

Response 201

Errors

Unblock an X author#link to Unblock an X author

Path parameters

Response 200

Errors

Read one X builds job#link to Read one X builds job

Path parameters

Response 200

Errors

Read a build screenshot#link to Read a build screenshot

Path parameters

Response 200

Errors

Read a build motion clip#link to Read a build motion clip

Path parameters

Response 200

Response 206

Errors

Cancel an X builds job#link to Cancel an X builds job

Path parameters

Response 200

Errors

Redraft a build’s reply#link to Redraft a build’s reply

Path parameters

Response 200

Errors

Move a job in the queue#link to Move a job in the queue

Path parameters

Request body

Response 200

Errors

Requeue a job at the front#link to Requeue a job at the front

Path parameters

Response 200

Errors

Resume a bundled job at the audit gate#link to Resume a bundled job at the audit gate

Path parameters

Response 200

Errors

Pin a job to the front#link to Pin a job to the front

Path parameters

Response 200

Errors

Unpin a job#link to Unpin a job

Path parameters

Response 200

Errors

Take down a published app#link to Take down a published app

Path parameters

Response 200

Errors

List your X builds jobslink to List your X builds jobs

Submit an X post for a buildlink to Submit an X post for a build

Read X builds statslink to Read X builds stats

Read the X builds queuelink to Read the X builds queue

Change the queue configlink to Change the queue config

List blocked X authorslink to List blocked X authors

Block an X authorlink to Block an X author

Unblock an X authorlink to Unblock an X author

Read one X builds joblink to Read one X builds job

Read a build screenshotlink to Read a build screenshot

Read a build motion cliplink to Read a build motion clip

Cancel an X builds joblink to Cancel an X builds job

Redraft a build’s replylink to Redraft a build’s reply

Move a job in the queuelink to Move a job in the queue

Requeue a job at the frontlink to Requeue a job at the front

Resume a bundled job at the audit gatelink to Resume a bundled job at the audit gate

Pin a job to the frontlink to Pin a job to the front

Unpin a joblink to Unpin a job

Take down a published applink to Take down a published app