---
title: "Builds – Superbot API"
canonical_url: "https://superbot.gg/developers/builds"
last_updated: "2026-10-01"
summary: "X builds: tag @superbot_gg on X and a live app is built, audited and published at <slug>.superbot.sh."
---

> Markdown twin of https://superbot.gg/developers/builds (the HTML page is canonical).
> The site index for agents is /llms.txt; every content page has a twin at its path plus `.md`.

# Builds

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

Base URL: `https://superbot.gg`. Errors: [https://superbot.gg/developers#errors](https://superbot.gg/developers#errors). Spec: [https://superbot.gg/docs/openapi.json](https://superbot.gg/docs/openapi.json).

## Operations

- [List your X builds jobs](https://superbot.gg/developers/builds/listXBuilds.md): `GET /v1/x-builds`
- [Submit an X post for a build](https://superbot.gg/developers/builds/createXBuild.md): `POST /v1/x-builds`
- [Read X builds stats](https://superbot.gg/developers/builds/getXBuildStats.md): `GET /v1/x-builds/stats`
- [Read the X builds queue](https://superbot.gg/developers/builds/getXBuildQueue.md): `GET /v1/x-builds/queue`
- [Change the queue config](https://superbot.gg/developers/builds/updateXBuildQueue.md): `PATCH /v1/x-builds/queue`
- [List blocked X authors](https://superbot.gg/developers/builds/listXBuildBlocklist.md): `GET /v1/x-builds/blocklist`
- [Block an X author](https://superbot.gg/developers/builds/blockXAuthor.md): `PUT /v1/x-builds/blocklist/{author_id}`
- [Unblock an X author](https://superbot.gg/developers/builds/unblockXAuthor.md): `DELETE /v1/x-builds/blocklist/{author_id}`
- [Read one X builds job](https://superbot.gg/developers/builds/getXBuild.md): `GET /v1/x-builds/{id}`
- [Read a build screenshot](https://superbot.gg/developers/builds/getXBuildScreenshot.md): `GET /v1/x-builds/{id}/screenshot`
- [Read a build motion clip](https://superbot.gg/developers/builds/getXBuildClip.md): `GET /v1/x-builds/{id}/clip`
- [Cancel an X builds job](https://superbot.gg/developers/builds/cancelXBuild.md): `POST /v1/x-builds/{id}/cancel`
- [Redraft a build’s reply](https://superbot.gg/developers/builds/redraftXBuildReply.md): `POST /v1/x-builds/{id}/reply-draft`
- [Move a job in the queue](https://superbot.gg/developers/builds/moveXBuild.md): `POST /v1/x-builds/{id}/move`
- [Requeue a job at the front](https://superbot.gg/developers/builds/requeueXBuild.md): `POST /v1/x-builds/{id}/requeue`
- [Resume a bundled job at the audit gate](https://superbot.gg/developers/builds/resumeXBuild.md): `POST /v1/x-builds/{id}/resume`
- [Pin a job to the front](https://superbot.gg/developers/builds/pinXBuild.md): `POST /v1/x-builds/{id}/pin`
- [Unpin a job](https://superbot.gg/developers/builds/unpinXBuild.md): `POST /v1/x-builds/{id}/unpin`
- [Take down a published app](https://superbot.gg/developers/builds/takedownXBuild.md): `DELETE /v1/x-builds/{id}/publish`

## List your X builds jobs

`GET /v1/x-builds`

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

- Operation id: `listXBuilds`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:read` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:read`

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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)
  - `id` (string, required)
  - `status` (string, required)
  - `lane` (string, required)
- `has_more` (boolean, required)
- `next_cursor` (string | null, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `createXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:write` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:write`

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |
| 429 | [`rate_limited`](https://superbot.gg/developers#errors-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. |

### Examples

```sh
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"}'
```

```js
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())
```

## 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.

- Operation id: `getXBuildStats`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:read` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:read`

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |

### Examples

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

```js
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())
```

## 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).

- Operation id: `getXBuildQueue`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

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

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `updateXBuildQueue`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

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

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |

### Examples

```sh
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}'
```

```js
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())
```

## List blocked X authors

`GET /v1/x-builds/blocklist`

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

- Operation id: `listXBuildBlocklist`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Response 200

The blocklist.

`application/json`: object.

- `object` (string, required): One of `list`.
- `data` (array of XbBlock, required)
  - `author_id` (string, required)
  - `reason` (string, required): One of `operator`, `optout`, `blocked_us`.
  - `created_at` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |

### Examples

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

```js
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())
```

## 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).

- Operation id: `blockXAuthor`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |

### Examples

```sh
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"}'
```

```js
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())
```

## Unblock an X author

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

- Operation id: `unblockXAuthor`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `author_id` | string | required |  |

### Response 200

The author is no longer blocked.

`application/json`: object.

- `ok` (boolean, required): One of `true`.

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |

### Examples

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

```js
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())
```

## 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).

- Operation id: `getXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:read` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:read`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required | The job id (`xb_…`). |

### Response 200

The job.

`application/json`: XbJobView.

- `id` (string, required)
- `status` (string, required)
- `lane` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `getXBuildScreenshot`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:read` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:read`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

The PNG bytes.

`image/png`: string (binary).

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `getXBuildClip`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:read` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:read`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

The whole clip.

`video/mp4`: string (binary).

### Response 206

The requested byte range.

`video/mp4`: string (binary).

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `cancelXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:write` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:write`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

The job is cancelled.

`application/json`: object.

- `ok` (boolean, required): One of `true`.
- `id` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `redraftXBuildReply`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:write` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:write`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

The new reply draft.

`application/json`: object.

- `reply` (any)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |
| 502 | — | The drafter could not be reached. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `moveXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |

### Examples

```sh
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}'
```

```js
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())
```

## 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.

- Operation id: `requeueXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

Done.

`application/json`: object.

- `ok` (boolean, required): One of `true`.
- `id` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `resumeXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

Done.

`application/json`: object.

- `ok` (boolean, required): One of `true`.
- `id` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `pinXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

Done.

`application/json`: object.

- `ok` (boolean, required): One of `true`.
- `id` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |

### Examples

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

```js
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())
```

## Unpin a job

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

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

- Operation id: `unpinXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

Done.

`application/json`: object.

- `ok` (boolean, required): One of `true`.
- `id` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://superbot.gg/developers#errors-invalid_request) | The request is malformed or a parameter is invalid; `param` names the field. |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |

### Examples

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

```js
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())
```

## 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.

- Operation id: `takedownXBuild`
- Group: [Builds](https://superbot.gg/developers/builds.md)
- Auth: A caller key holding `builds:admin` (`Authorization: Bearer sbc_…` or `x-api-key: sbc_…`), or a signed-in session.
- Scopes: `builds:admin`

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | required |  |

### Response 200

The app is gone.

`application/json`: object.

- `ok` (boolean, required): One of `true`.
- `id` (string, required)

### Errors

Every refusal carries `error`, `message`, `doc_url` and `request_id`; the gateway routes answer in the dialect you dialed.

| Status | Codes | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://superbot.gg/developers#errors-unauthorized) | The bearer is missing, malformed or unknown. |
| 403 | [`insufficient_scope`](https://superbot.gg/developers#errors-insufficient_scope) | The key lacks a scope (insufficient_scope), is revoked, or may not call this route. |
| 404 | [`not_found`](https://superbot.gg/developers#errors-not_found) | No such resource on this account. |
| 409 | [`conflict`](https://superbot.gg/developers#errors-conflict) | The resource is not in a state that allows this change. |
| 502 | — | Cloudflare refused the takedown. |

### Examples

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

```js
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())
```