The JSON API is available on the account host under /api/v1 when agent access is enabled. Every account operation requires Authorization: Bearer followed by your scoped access token. Browser session cookies are not API credentials. Mutating requests accept application/json only. A supplied browser Origin must match the account origin; no cross-origin browser integration is offered. Keep tokens in your client's protected environment and send the header on each request.
Responses and human steps
Creation does not charge a card or provision an unpaid bot. A paid request returns human_payment_required with a checkout_url. The human opens and pays it, then the existing payment confirmation provisions the bot. A Free request returns human_required and a normal claim URL for email verification or a captcha step. The Free link uses template=own, own_runtime=discordjs for Node or discordpy for Python, and starter=none. The claim form preserves that runtime and bring-your-own choice when submitted. Any sign-in method works for Free; captcha and the other account/abuse limits still apply. Check list_bots afterward. request_upgrade returns the human Billing page to review a configured paid plan; this API does not automatically prorate or switch an existing subscription. The billing summary omits payment credentials and provider identifiers.
Successful mutations return an acknowledgment. State transitions, dependency installation and startup can still take time. Poll status or inspect logs at a reasonable rate. Each token has a bounded request budget and a 429 response includes Retry-After. Tokens can be revoked from Account. An open log stream rechecks authorization and closes after revocation. Reinitialize an expired MCP session rather than replaying a mutation.
Errors and file handling
401 means the credential is missing, malformed or revoked. 403 means a scope, origin or account verification check denied access. 404 covers unavailable owner-scoped bots. 409 covers state or confirmation conflicts. 422 covers invalid values or checked file changes. 429 means rate limiting; 503 means a required integration or runtime is unavailable. Error responses contain fixed codes rather than upstream bodies or submitted secrets. MCP business errors include structuredContent.error, status and a fixed next recovery hint. For disk_limit_exceeded inspect get_usage and reduce the upload; invalid_archive requires a supported safe archive; public_archive_unavailable_or_over_limit means check the public repository/branch and remaining disk budget. file_unavailable means list_files and choose an existing path. Argument errors identify schema field names without echoing values. Upload one base64 file within the existing upload limit, then extract a supported archive through the checked extraction route. Text writes use the existing editor limit. Paths cannot escape the bot's directory.
Generated routes
The following method, path, scope and input information is generated from the same catalog as the served OpenAPI document. Download the OpenAPI JSON for a client generator. Its live counterpart is on the account host at /api/v1/openapi.json. The SSE route emits connected, log and end events with JSON data; it has no replay cursor and requires a new Authorization header on reconnect.
whoami
GET /api/v1/me
Required scope: read. This route does not take a bot reference.
list_plans
GET /api/v1/plans
Required scope: read. This route does not take a bot reference.
list_bots
GET /api/v1/bots
Required scope: read. This route does not take a bot reference.
create_bot
POST /api/v1/bots
Required scope: deploy. This route does not take a bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 3,
"maxLength": 32,
"pattern": "^[a-z0-9-]+$"
},
"runtime": {
"type": "string",
"enum": [
"node",
"python"
]
},
"tier": {
"default": "free",
"type": "string"
},
"period": {
"default": "monthly",
"type": "string",
"enum": [
"monthly",
"yearly"
]
}
},
"required": [
"name",
"runtime",
"tier",
"period"
],
"additionalProperties": false
}start_checkout
POST /api/v1/checkout
Required scope: deploy. This route does not take a bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 3,
"maxLength": 32,
"pattern": "^[a-z0-9-]+$"
},
"runtime": {
"type": "string",
"enum": [
"node",
"python"
]
},
"tier": {
"default": "free",
"type": "string"
},
"period": {
"default": "monthly",
"type": "string",
"enum": [
"monthly",
"yearly"
]
}
},
"required": [
"name",
"runtime",
"tier",
"period"
],
"additionalProperties": false
}get_bot
GET /api/v1/bots/{id}
Required scope: read. Replace {id} with your public bot reference.
get_status
GET /api/v1/bots/{id}/status
Required scope: read. Replace {id} with your public bot reference.
get_usage
GET /api/v1/bots/{id}/usage
Required scope: read. Replace {id} with your public bot reference.
request_upgrade
POST /api/v1/bots/{id}/upgrade
Required scope: deploy. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"tier": {
"type": "string"
},
"period": {
"default": "monthly",
"type": "string",
"enum": [
"monthly",
"yearly"
]
}
},
"required": [
"tier",
"period"
],
"additionalProperties": false
}power
POST /api/v1/bots/{id}/power
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"signal": {
"type": "string",
"enum": [
"start",
"stop",
"restart"
]
}
},
"required": [
"signal"
],
"additionalProperties": false
}get_logs
GET /api/v1/bots/{id}/logs
Required scope: read. Replace {id} with your public bot reference.
tail_logs
GET /api/v1/bots/{id}/logs/stream
Required scope: read. Replace {id} with your public bot reference.
get_env
GET /api/v1/bots/{id}/env
Required scope: manage. Replace {id} with your public bot reference.
set_bot_token
POST /api/v1/bots/{id}/token
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"token": {
"type": "string",
"minLength": 1,
"maxLength": 16384,
"writeOnly": true
}
},
"required": [
"token"
],
"additionalProperties": false
}set_env
POST /api/v1/bots/{id}/env
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"values": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[A-Z][A-Z0-9_]*$"
},
"additionalProperties": {
"type": "string",
"maxLength": 16384
}
}
},
"required": [
"values"
],
"additionalProperties": false
}list_files
GET /api/v1/bots/{id}/files
Required scope: manage. Replace {id} with your public bot reference.
Optional query: directory.
read_file
GET /api/v1/bots/{id}/files/read
Required scope: manage. Replace {id} with your public bot reference.
Required query: path.
write_file
POST /api/v1/bots/{id}/files/write
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"content": {
"type": "string",
"maxLength": 262144
}
},
"required": [
"path",
"content"
],
"additionalProperties": false
}upload_files
POST /api/v1/bots/{id}/files/upload
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"base64": {
"type": "string",
"maxLength": 1398104
}
},
"required": [
"path",
"base64"
],
"additionalProperties": false
}extract_file
POST /api/v1/bots/{id}/files/extract
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"path"
],
"additionalProperties": false
}connect_github
POST /api/v1/bots/{id}/github
Required scope: deploy and manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"repo": {
"type": "string",
"maxLength": 240
},
"branch": {
"default": "main",
"type": "string",
"minLength": 1,
"maxLength": 240
}
},
"required": [
"repo",
"branch"
],
"additionalProperties": false
}deploy
POST /api/v1/bots/{id}/deploy
Required scope: deploy. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"confirm": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"confirm"
],
"additionalProperties": false
}delete_bot
DELETE /api/v1/bots/{id}
Required scope: manage. Replace {id} with your public bot reference.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"confirm": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
},
"required": [
"confirm"
],
"additionalProperties": false
}billing_status
GET /api/v1/billing
Required scope: billing-read. This route does not take a bot reference.
Read the agent quickstart, tool reference, API reference, complete deployment example and troubleshooting guide.
Still stuck? Contact support