{ "openapi": "3.1.0", "info": { "title": "SuperCool API", "version": "1.0.0", "summary": "One agent, one endpoint. Send a message; get back finished work.", "description": "The SuperCool API gives your code the same agent you talk to in the SuperCool app.\nSend it a plain-language message and it plans the work, runs the tools and hands\nback the result: videos, images, websites, decks, research and writing.\n\nAll requests go to `https://api.supercool.com/v1` with an API key in the\n`Authorization` header. Every response carries a `Request-Id` header.\n", "contact": { "name": "SuperCool", "url": "https://supercool.com/docs/api" }, "termsOfService": "https://supercool.com/terms" }, "externalDocs": { "description": "Guides", "url": "https://supercool.com/docs/api" }, "servers": [ { "url": "https://api.supercool.com/v1", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Messages", "description": "Talk to your agent and follow the work it starts." }, { "name": "Uploads", "description": "Attach large files (up to 500 MB each) to a message." }, { "name": "Work", "description": "The chats your agent works in, the same ones you see in the app." }, { "name": "Files", "description": "Download what the agent made." }, { "name": "Account", "description": "Who the key belongs to, the plan, credits and limits." }, { "name": "Webhooks", "description": "Get pushed events instead of polling." } ], "paths": { "/messages": { "post": { "operationId": "createMessage", "tags": [ "Messages" ], "summary": "Send a message", "description": "Sends your agent a message, optionally with files. The call returns within about 30\nseconds: either the finished answer, or `status: \"processing\"` when the agent started\nlonger work. Follow a processing message with\n[`GET /messages/{message_id}`](#get-message) (use `?wait=` to long-poll), its\n[events](#list-message-events), or a [webhook](/docs/api/webhooks).\n\nReturns `201` for a new message and `200` when an `Idempotency-Key` replays an\nexisting one. Running out of credits is not an error: the message comes back with\n`status: \"blocked\"` and `reason: \"out_of_credits\"`. Neither is the running-jobs cap:\nwork the agent can't start because 5 jobs are already running comes back as a\n`blocked` job with `reason: \"too_many_running\"`, and the message lists the `running` work.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreate" }, "example": { "message": "A 15 second vertical ad for my candle shop, warm and cozy" } } } }, "responses": { "200": { "description": "An `Idempotency-Key` you already used with the same body. The same message, as it is now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "201": { "description": "The message was accepted. It is either final already or `processing`.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "object": "message", "status": "processing", "reason": null, "question": null, "final": false, "reply": "On it. I'm making a 15 second vertical ad with warm candlelight shots.", "jobs": [ { "job_id": "exe_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e", "kind": "execution", "role": "execution", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "title": "Candle shop vertical ad", "status": "running", "reason": null, "final": false, "queued": null, "resume_by": null, "link": "https://supercool.com/chat/5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "started_at": "2026-09-30T14:02:11.402000Z", "settled_at": null, "files": [] } ], "files": [], "notes": [], "credits_used": 0, "created_at": "2026-09-30T14:02:03.118000Z", "updated_at": "2026-09-30T14:02:12.950000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "empty_message", "too_long", "too_many", "unauthorized", "not_found", "idempotency_conflict", "upload_not_ready", "too_large", "rate_limited" ] } }, "/messages/{message_id}": { "get": { "operationId": "getMessage", "tags": [ "Messages" ], "summary": "Get a message", "description": "One message: its status, the agent's reply, the jobs it started and the files they\nmade. With `wait`, the call holds for up to that many seconds and returns as soon as\nsomething changes (the status, the reply arriving, or a job's status) or the message\nis final.\n\nMessages are kept for at least 14 days after their last job's deadline. After that\nthis returns `404 not_found`; read the work instead ([`GET /work/{work_id}`](#get-work)).\n", "parameters": [ { "$ref": "#/components/parameters/MessageId" }, { "name": "wait", "in": "query", "required": false, "description": "Long-poll for up to this many seconds (0 to 45). `0` returns immediately.", "schema": { "type": "integer", "minimum": 0, "maximum": 45, "default": 0 }, "example": 30 } ], "responses": { "200": { "description": "The message.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "object": "message", "status": "completed", "reason": null, "question": null, "final": true, "reply": "On it. I'm making a 15 second vertical ad with warm candlelight shots.", "jobs": [ { "job_id": "exe_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e", "kind": "execution", "role": "execution", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "title": "Candle shop vertical ad", "status": "completed", "reason": null, "final": true, "queued": null, "resume_by": null, "link": "https://supercool.com/chat/5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "started_at": "2026-09-30T14:02:11.402000Z", "settled_at": "2026-09-30T14:06:40.221000Z", "files": [ { "file_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f/candle_ad.mp4", "name": "candle_ad.mp4", "content_type": "video/mp4", "kind": "video", "size": 4812345, "url": "https://api.supercool.sh/api/v1/files/s/eyJmIjoiNWQwYzNl...", "revision": "\"5b1c0e6f9d2a4b7c8e1f3a5d7c9b0e2f\"", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "label": null } ] } ], "files": [ { "file_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f/candle_ad.mp4", "name": "candle_ad.mp4", "content_type": "video/mp4", "kind": "video", "size": 4812345, "url": "https://api.supercool.sh/api/v1/files/s/eyJmIjoiNWQwYzNl...", "revision": "\"5b1c0e6f9d2a4b7c8e1f3a5d7c9b0e2f\"", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "label": null } ], "notes": [], "credits_used": 42.5, "created_at": "2026-09-30T14:02:03.118000Z", "updated_at": "2026-09-30T14:02:12.950000Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "unauthorized", "not_found", "rate_limited" ] } }, "/messages/{message_id}/events": { "get": { "operationId": "listMessageEvents", "tags": [ "Messages" ], "summary": "List a message's events", "description": "The message's update log, oldest first: progress steps, late replies, each job's\nresult with its files, and state changes. Only this message's entries: another\nmessage's progress in the same chat isn't included. Pass back the `cursor` from the previous\npage to get only what's new. With no cursor, the log starts where the message\nstarted. `done` is `true` once the message has nothing more to report.\n\nThe call waits at least one second, and up to `wait` seconds, for new entries. Only\none wait per message runs at a time (`409 poll_in_progress` otherwise). Entries are\nkept for 7 days; a cursor older than that returns `cursor_expired: true` with a fresh\ncursor.\n", "parameters": [ { "$ref": "#/components/parameters/MessageId" }, { "name": "cursor", "in": "query", "required": false, "description": "The `cursor` from the previous page. Opaque.", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "Wait up to this many seconds for new entries (0 to 45; at least 1 second is always waited).", "schema": { "type": "integer", "minimum": 0, "maximum": 45, "default": 0 }, "example": 30 } ], "responses": { "200": { "description": "A page of events.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "object": "list", "data": [ { "seq": 118, "type": "progress", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "message_id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "at": "2026-09-30T14:03:02.000000Z", "step": "Rendering the video", "status": "started", "file_names": [] }, { "seq": 121, "type": "result", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "message_id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "at": "2026-09-30T14:06:40.000000Z", "title": "Candle shop vertical ad", "text": "Your 15 second ad is ready.", "outcome": "completed", "files": [] } ], "has_more": false, "done": true, "cursor": "eyJjIjoiYXBpOnU..." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "bad_cursor", "unauthorized", "not_found", "poll_in_progress", "rate_limited" ] } }, "/messages/{message_id}/recover": { "post": { "operationId": "recoverMessage", "tags": [ "Messages" ], "summary": "Recover a message's results", "description": "For work that outlived its watch (a job or message that `expired`): re-arms the watch\nso the result is looked up again and lands in the message, its events and your\nwebhooks. It never resends the message or starts new work. One entry per piece of\nwork: `settled` (already has its outcome), `watching` (still being watched),\n`recovering` (re-armed now) or `exhausted` (recovered too many times; read the work).\n", "parameters": [ { "$ref": "#/components/parameters/MessageId" } ], "responses": { "200": { "description": "What happened to each piece of work.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recovery" }, "example": { "id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "object": "recovery", "work": [ { "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "state": "recovering" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "not_found", "rate_limited" ] } }, "/uploads": { "post": { "operationId": "createUpload", "tags": [ "Uploads" ], "summary": "Start an upload", "description": "Starts a large upload (up to 500 MB). Returns a presigned POST: send a\n`multipart/form-data` POST to `url` with every entry of `fields` as form fields and\nthe file last, as a field named `file`. The link is valid for 15 minutes. Then call\n[`POST /uploads/{upload_id}/complete`](#complete-upload) and pass the `upload_id` in a\nmessage's `upload_ids`. Uploads never attached to a message are deleted after 24 hours.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCreate" }, "example": { "filename": "product-shoot.mov", "size": 157286400, "content_type": "video/quicktime" } } } }, "responses": { "201": { "description": "The upload was created. POST the file to `url` next.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCreated" }, "example": { "object": "upload", "upload_id": "up_0a1b2c3d4e5f60718293a4b5c6d7e8f9", "url": "https://supercool-uploads.s3.amazonaws.com/", "fields": { "key": "agent-uploads/incoming/.../product-shoot.mov", "Content-Type": "video/quicktime", "policy": "eyJleHBpcmF0aW9uIjoi...", "x-amz-signature": "3f1c..." }, "expires_at": "2026-09-30T14:17:03.118000Z", "max_bytes": 157286400 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/TooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "bad_size", "unauthorized", "too_large", "rate_limited" ] } }, "/uploads/{upload_id}/complete": { "post": { "operationId": "completeUpload", "tags": [ "Uploads" ], "summary": "Complete an upload", "description": "Finalizes an upload after the file was POSTed to the presigned `url`. The file is\nchecked (its real size, and executables are refused) and becomes `ready` to attach.\nCalling it again on a ready upload returns the same result.\n", "parameters": [ { "name": "upload_id", "in": "path", "required": true, "description": "The `upload_id` from `POST /uploads` (`up_…`).", "schema": { "type": "string" }, "example": "up_0a1b2c3d4e5f60718293a4b5c6d7e8f9" } ], "responses": { "200": { "description": "The upload is ready to attach.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" }, "example": { "object": "upload", "upload_id": "up_0a1b2c3d4e5f60718293a4b5c6d7e8f9", "status": "ready", "filename": "product-shoot.mov", "content_type": "video/quicktime", "size": 157286400 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "not_found", "not_pending", "not_uploaded", "changed", "too_large", "executable_refused", "rate_limited" ] } }, "/work": { "get": { "operationId": "listWork", "tags": [ "Work" ], "summary": "List recent work", "description": "Your agent's recent work (chats), newest first: the same list you see in the app,\nwhether the work was started over the API, in the app, by phone or anywhere else.\n", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many to return (1 to 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "example": 10 } ], "responses": { "200": { "description": "Recent work.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkList" }, "example": { "object": "list", "data": [ { "object": "work", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "title": "Candle shop vertical ad", "preview": "Your 15 second ad is ready.", "link": "https://supercool.com/chat/5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "unauthorized", "rate_limited" ] } }, "/work/{work_id}": { "get": { "operationId": "getWork", "tags": [ "Work" ], "summary": "Get a piece of work", "description": "One piece of work: whether it's running, the latest result text (paged with\n`from_char` / `next_from_char`) and its most recent files (up to 8), each with a\nfresh download link.\n", "parameters": [ { "name": "work_id", "in": "path", "required": true, "description": "The `work_id` from a job, an event or `GET /work`.", "schema": { "type": "string" }, "example": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f" }, { "name": "from_char", "in": "query", "required": false, "description": "Read the text from this character on (use the previous `next_from_char`).", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "The work.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Work" }, "example": { "object": "work", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "title": "Candle shop vertical ad", "status": "idle", "text": "Your 15 second ad is ready. I used warm, slow push-ins on the candles...", "next_from_char": null, "link": "https://supercool.com/chat/5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "files": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "unauthorized", "not_found", "rate_limited" ] } }, "/files/{file_id}": { "get": { "operationId": "getFile", "tags": [ "Files" ], "summary": "Get a file", "description": "A file's record with a fresh signed download link. Use it when a `url` has expired,\nor when a download answered `412` because the file changed since the link was made.\nFile ids contain slashes (`/`); put them in the path as they are.\n", "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "The `file_id` from a message, job, event or work (`/`, slashes included).", "schema": { "type": "string" }, "example": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f/candle_ad.mp4" } ], "responses": { "200": { "description": "The file.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileObject" }, "example": { "object": "file", "file_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f/candle_ad.mp4", "name": "candle_ad.mp4", "content_type": "video/mp4", "kind": "video", "size": 4812345, "url": "https://api.supercool.sh/api/v1/files/s/eyJmIjoiNWQwYzNl...", "revision": "\"5b1c0e6f9d2a4b7c8e1f3a5d7c9b0e2f\"", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "label": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "not_found", "rate_limited" ] } }, "/me": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Get the account", "description": "The account the API key belongs to, its plan, available credits, the agent's name, the key itself and your limits.", "responses": { "200": { "description": "The account.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "user_id": "64f1c2a9e4b0a1b2c3d4e5f6", "email": "you@example.com", "name": "Sam Rivera", "plan": "pro", "credits": 1840, "agent": { "name": "Nova" }, "key": { "id": "pat:6a1b2c3d4e5f", "name": "prod server" }, "limits": { "running_jobs": 5, "requests_per_minute": 600 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "rate_limited" ] } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "The account's webhook endpoints (up to 10).", "responses": { "200": { "description": "The endpoints.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "example": { "object": "list", "data": [ { "object": "webhook_endpoint", "id": "whe_4c1d2e3f4a5b6c7d8e9f", "url": "https://example.com/hooks/supercool", "events": [ "*" ], "description": "prod", "created_at": "2026-09-30T13:40:00.000000Z", "disabled_at": null, "disabled_reason": null, "failing_since": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "rate_limited" ] }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "Registers a public `https` URL (port 443 or 8443) to receive events. The response\nincludes the endpoint's signing `secret` (`whsec_…`). It is shown only this once:\nstore it now. Omit `events` (or pass `[\"*\"]`) to receive every event.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" }, "example": { "url": "https://example.com/hooks/supercool", "events": [ "message.completed", "message.failed", "message.blocked" ], "description": "prod" } } } }, "responses": { "201": { "description": "The endpoint, with its secret (shown once).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "example": { "object": "webhook_endpoint", "id": "whe_4c1d2e3f4a5b6c7d8e9f", "url": "https://example.com/hooks/supercool", "events": [ "message.completed", "message.failed", "message.blocked" ], "description": "prod", "created_at": "2026-09-30T13:40:00.000000Z", "disabled_at": null, "disabled_reason": null, "failing_since": null, "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "bad_url", "bad_events", "bad_request", "unauthorized", "too_many_endpoints", "rate_limited" ] } }, "/webhooks/{endpoint_id}": { "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "description": "One endpoint and its 20 most recent deliveries.", "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "The endpoint.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDetail" }, "example": { "object": "webhook_endpoint", "id": "whe_4c1d2e3f4a5b6c7d8e9f", "url": "https://example.com/hooks/supercool", "events": [ "*" ], "description": "prod", "created_at": "2026-09-30T13:40:00.000000Z", "disabled_at": null, "disabled_reason": null, "failing_since": null, "recent_deliveries": [ { "object": "webhook_delivery", "id": "evt_7d8e9f0a1b2c3d4e5f6a7b8c", "event": "message.completed", "status": "delivered", "attempts": 1, "last_status_code": 200, "last_error": null, "last_response": "ok", "last_ms": 184, "created_at": "2026-09-30T14:06:41.000000Z", "delivered_at": "2026-09-30T14:06:41.000000Z", "next_attempt_at": "2026-09-30T14:06:41.000000Z", "message_id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "not_found", "rate_limited" ] }, "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "Changes an endpoint's URL, events or description, or turns it off and on. Send only\nthe fields to change. `\"enabled\": true` turns a disabled endpoint back on (after you\nfixed it) and clears its failure state.\n", "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "The updated endpoint.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "invalid_request", "bad_url", "bad_events", "bad_request", "unauthorized", "not_found", "rate_limited" ] }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Deletes the endpoint. Deliveries still waiting to be sent to it are cancelled.", "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "Deleted.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "object": "webhook_endpoint", "id": "whe_4c1d2e3f4a5b6c7d8e9f", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "not_found", "rate_limited" ] } }, "/webhooks/{endpoint_id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Rotate a signing secret", "description": "Replaces the endpoint's signing secret and returns the new one (shown once). Every\ndelivery from now on is signed with the new secret, including retries of earlier\nevents.\n", "parameters": [ { "$ref": "#/components/parameters/EndpointId" } ], "responses": { "200": { "description": "The new secret.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedSecret" }, "example": { "object": "webhook_endpoint", "id": "whe_4c1d2e3f4a5b6c7d8e9f", "secret": "whsec_Q2hhbmdlZC1zZWNyZXQtZXhhbXBsZTEy" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-errors": [ "unauthorized", "not_found", "rate_limited" ] } } }, "webhooks": { "job-event": { "post": { "operationId": "jobEvent", "summary": "A job changed", "description": "Sent when one job (one piece of work) changes: `job.completed`, `job.failed`,\n`job.blocked`, `job.resumed` or `job.expired`. `data` is the job, with its\n`message_id` and files. Signed with the Standard Webhooks headers.\n", "parameters": [ { "$ref": "#/components/parameters/WebhookIdHeader" }, { "$ref": "#/components/parameters/WebhookTimestampHeader" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEvent" }, "example": { "type": "job.completed", "timestamp": "2026-09-30T14:06:40.310000Z", "data": { "object": "job", "message_id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d", "job_id": "exe_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e", "kind": "execution", "role": "execution", "work_id": "5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "title": "Candle shop vertical ad", "status": "completed", "reason": null, "final": true, "queued": null, "resume_by": null, "link": "https://supercool.com/chat/5d0c3e2a-8f1b-4c6d-9e7f-1a2b3c4d5e6f", "started_at": "2026-09-30T14:02:11.402000Z", "settled_at": "2026-09-30T14:06:40.221000Z", "files": [] } } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds counts as delivered. Anything else is retried." } } } }, "message-event": { "post": { "operationId": "messageEvent", "summary": "A message reached a status", "description": "Sent once each time a message reaches a status other than `processing`:\n`message.completed`, `message.partial`, `message.failed`, `message.needs_input`,\n`message.blocked` or `message.expired`. `data` is the full message, exactly as\n`GET /messages/{message_id}` returns it.\n", "parameters": [ { "$ref": "#/components/parameters/WebhookIdHeader" }, { "$ref": "#/components/parameters/WebhookTimestampHeader" }, { "$ref": "#/components/parameters/WebhookSignatureHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageEvent" } } } }, "responses": { "200": { "description": "Any 2xx within 10 seconds counts as delivered. Anything else is retried." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sc_key_…", "description": "An API key from the dashboard (https://supercool.com/dashboard#api), sent as\n`Authorization: Bearer sc_key_…`. Keys are server-side secrets.\n" } }, "headers": { "Request-Id": { "description": "This request's id (`req_…`). Find it in the dashboard's request inspector.", "schema": { "type": "string", "example": "req_6c2f0e1d9a8b7c6d5e4f3a2b" } }, "RateLimit-Limit": { "description": "Requests this API key may make per minute (600).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the oldest counted request leaves the window.", "schema": { "type": "integer" } }, "Retry-After": { "description": "On every `429`: seconds to wait before retrying. Exact for the per-key budget; `60` for account-level limits (messages, waits, work reads).", "schema": { "type": "integer" } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any string up to 128 characters, unique per logical request. Scoped to the API key and\nkept for 7 days: sending it again with the same body returns the same message (`200`)\nand never starts work twice; with a different body it's `409 idempotency_conflict`.\n", "schema": { "type": "string", "maxLength": 128 }, "example": "order-8812-ad" }, "MessageId": { "name": "message_id", "in": "path", "required": true, "description": "The message's `id` (`msg_…`).", "schema": { "type": "string" }, "example": "msg_3f9a1c2e7b8d4e5f6a7b8c9d" }, "EndpointId": { "name": "endpoint_id", "in": "path", "required": true, "description": "The webhook endpoint's `id` (`whe_…`).", "schema": { "type": "string" }, "example": "whe_4c1d2e3f4a5b6c7d8e9f" }, "WebhookIdHeader": { "name": "webhook-id", "in": "header", "required": true, "description": "The delivery's id (`evt_…`). The same across retries of one event; use it to drop duplicates.", "schema": { "type": "string" } }, "WebhookTimestampHeader": { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, "WebhookSignatureHeader": { "name": "webhook-signature", "in": "header", "required": true, "description": "`v1,` + base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64-decoded part of your `whsec_` secret.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "The request can't be processed as sent. `invalid_request` (with `problems`) when it doesn't match the schema.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_request", "message": "The request doesn't match what this endpoint expects; see `problems`.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#invalid_request", "problems": [ { "field": "files", "problem": "Input should be a valid list" } ] } } } }, "Unauthorized": { "description": "The API key is missing, unknown or revoked.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "WWW-Authenticate": { "description": "Always `Bearer`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "unauthorized", "message": "unknown or revoked token. Send your API key as 'Authorization: Bearer sc_key_…'.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#unauthorized" } } } }, "NotFound": { "description": "Nothing with that id for this API key or account.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "No message with that id for this API key.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#not_found" } } } }, "Conflict": { "description": "The request conflicts with the current state.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "idempotency_conflict", "message": "That Idempotency-Key was already used for a different message. Use a new key for a new request.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#idempotency_conflict" } } } }, "TooLarge": { "description": "A file or upload is over the size limit.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "too_large", "message": "Files can be up to 500 MB.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#too_large" } } } }, "Unprocessable": { "description": "The uploaded file was refused (an executable).", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "executable_refused", "message": "Executable files can't be attached.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#executable_refused" } } } }, "TooManyRequests": { "description": "A rate limit was hit. Wait `Retry-After` seconds.", "headers": { "Request-Id": { "$ref": "#/components/headers/Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "message": "Too many requests for this API key; slow down and retry after the Retry-After seconds.", "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b", "docs": "https://supercool.com/docs/api/errors#rate_limited" } } } } }, "schemas": { "MessageCreate": { "type": "object", "description": "A message to your agent. Send `message`, files, or both.", "properties": { "message": { "type": "string", "maxLength": 20000, "default": "", "description": "What you want, in plain language. Up to 20,000 characters; send longer text as a file." }, "files": { "type": "array", "description": "Small files inline (up to 5, 10 MB each, 25 MB in total). Each has a `url` or `base64`. A file that can't be fetched doesn't fail the message: it's listed in the message's `notes`.", "items": { "$ref": "#/components/schemas/InlineFile" } }, "upload_ids": { "type": "array", "description": "Finished uploads to attach (up to 10, 1 GB in total). See `POST /uploads`.", "items": { "type": "string" } }, "webhook_endpoint_id": { "type": [ "string", "null" ], "description": "Send this message's webhook events to this registered endpoint (`whe_…`) instead of the account's endpoints." } } }, "InlineFile": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "A file name for the agent to see." }, "url": { "type": [ "string", "null" ], "description": "A public `https` URL to fetch the file from." }, "base64": { "type": [ "string", "null" ], "description": "The file's bytes, base64-encoded." }, "content_type": { "type": [ "string", "null" ], "description": "The MIME type, for `base64` files." } } }, "Message": { "type": "object", "description": "A message you sent and everything that came of it.", "required": [ "id", "object", "status", "final", "jobs", "files", "notes", "credits_used", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The message id (`msg_…`), always generated by SuperCool." }, "object": { "const": "message" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "reason": { "type": [ "string", "null" ], "description": "Why, for `blocked`, `failed`, `partial` and `expired`: `out_of_credits`, `hosting_fees`, `too_many_running`, `queue_expired`, `watch_expired`, `result_unknown`, `execution_failed`, `stopped`, `agent_busy`, `turn_failed` and others. See [Getting results](/docs/api/results#reasons)." }, "question": { "type": [ "string", "null" ], "description": "For `needs_input`, the agent's question. Answer by sending a new message." }, "final": { "type": "boolean", "description": "`true` when nothing about this message will change any more. Stop polling." }, "reply": { "type": [ "string", "null" ], "description": "What the agent said, once it has answered." }, "jobs": { "type": "array", "description": "The pieces of work this message started, each with its own status.", "items": { "$ref": "#/components/schemas/Job" } }, "files": { "type": "array", "description": "Every file the message produced (handed over in the reply, or made by its jobs).", "items": { "$ref": "#/components/schemas/File" } }, "notes": { "type": "array", "description": "Problems with attachments (a file that couldn't be fetched, files over the limit).", "items": { "type": "string" } }, "credits_used": { "type": "number", "description": "Credits this message's jobs used so far." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the agent's turn ended (or `created_at` while it's still going)." }, "resume": { "const": "add_credits", "description": "Present when queued work is waiting for credits: add credits before `resume_by` and it runs by itself. Don't resend the message." }, "resume_by": { "type": "string", "format": "date-time", "description": "The earliest deadline among queued jobs waiting for credits (24 hours after they were queued)." }, "retry_after_seconds": { "type": "integer", "description": "With `reason: \"agent_busy\"`: retry with the same `Idempotency-Key` after this many seconds." }, "running": { "type": "array", "description": "Present when the agent tried to start work while 5 jobs were already running on the account (a job with `reason: \"too_many_running\"`): the work running now, and the message that started each.", "items": { "type": "object", "properties": { "job_id": { "type": "string", "description": "`exe_…`" }, "message_id": { "type": "string" }, "work_id": { "type": "string" } } } } } }, "MessageStatus": { "type": "string", "description": "The message's status, aggregated over its jobs.", "enum": [ "processing", "needs_input", "blocked", "completed", "partial", "failed", "expired" ] }, "Job": { "type": "object", "description": "One piece of work a message started (or was refused).", "properties": { "job_id": { "type": "string", "description": "`exe_…` for work that ran or is queued; `ref_…` for work refused before it was queued." }, "kind": { "type": "string", "enum": [ "execution", "refusal" ] }, "role": { "type": "string", "enum": [ "execution", "follow_up" ], "description": "`follow_up` when the message joined work that was already running; its status follows that work." }, "work_id": { "type": [ "string", "null" ], "description": "The chat the work runs in." }, "title": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/JobStatus" }, "reason": { "type": [ "string", "null" ], "description": "For `blocked`, `failed`, `cancelled` and `expired`: `out_of_credits`, `hosting_fees`, `too_many_running`, `execution_failed`, `stopped`, `queue_expired`, `watch_expired`, `result_unknown`." }, "final": { "type": "boolean", "description": "`false` while running, and for queued work waiting for credits (it can still run)." }, "queued": { "type": [ "boolean", "null" ], "description": "`true` for work that is queued and waiting for credits; otherwise `null`." }, "resume_by": { "type": [ "string", "null" ], "format": "date-time", "description": "For queued work waiting for credits, the deadline to add them (24 hours after it was queued)." }, "link": { "type": [ "string", "null" ], "description": "The work in the SuperCool app." }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } } }, "JobStatus": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled", "blocked", "expired" ] }, "File": { "type": "object", "description": "A file the agent made or handed over.", "properties": { "file_id": { "type": "string", "description": "`/`. Use it with `GET /files/{file_id}` for a fresh link." }, "name": { "type": "string" }, "content_type": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "doc", "site" ] }, "size": { "type": [ "integer", "null" ], "description": "Bytes. `null` for a site." }, "url": { "type": [ "string", "null" ], "description": "A signed download link. It expires, and it is pinned to `revision`; a download answers `412` if the file changed since." }, "revision": { "type": [ "string", "null" ], "description": "The file's version the link is pinned to. `null` for a site (its link always opens the live site)." }, "work_id": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "FileObject": { "allOf": [ { "type": "object", "properties": { "object": { "const": "file" } } }, { "$ref": "#/components/schemas/File" } ] }, "EventList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean", "description": "More entries are ready; call again with `cursor` right away." }, "done": { "type": "boolean", "description": "The message has nothing more to report." }, "cursor": { "type": "string", "description": "Pass this back as `cursor` for the next page." }, "cursor_expired": { "type": "boolean", "description": "Your cursor pointed at entries older than 7 days. `cursor` restarts from now." } } }, "Event": { "type": "object", "description": "One entry in a message's update log. Fields beyond the common ones depend on `type`.", "properties": { "seq": { "type": "integer" }, "type": { "type": "string", "enum": [ "result", "progress", "agent_reply", "state", "turn_failed", "turn_busy" ], "description": "`result` (a job finished, with text and files), `progress` (a step started or a file landed), `agent_reply` (the agent's reply), `state` (`resumed`, `stopped`, `expired`, `unknown`), `turn_failed`, `turn_busy`." }, "work_id": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ], "description": "The message the entry belongs to, when known." }, "at": { "type": "string", "format": "date-time" }, "job_id": { "type": "string", "description": "The job (`exe_…`) the entry belongs to, when known." }, "title": { "type": [ "string", "null" ], "description": "`result`" }, "text": { "type": [ "string", "null" ], "description": "`result`, `agent_reply`, `state`, `turn_failed`, `turn_busy`" }, "outcome": { "type": "string", "enum": [ "completed", "failed", "stalled_credits" ], "description": "`result`" }, "files": { "type": "array", "description": "`result`, `agent_reply`", "items": { "$ref": "#/components/schemas/File" } }, "state": { "type": "string", "description": "`state`" }, "step": { "type": [ "string", "null" ], "description": "`progress`" }, "status": { "type": [ "string", "null" ], "description": "`progress`" }, "file_names": { "type": "array", "description": "`progress`: names of files that just landed (download them from the `result`).", "items": { "type": "string" } }, "delivered_sync": { "type": [ "boolean", "null" ], "description": "`agent_reply`: `true` when this reply was already in the `POST /messages` response." }, "reason": { "type": [ "string", "null" ], "description": "`turn_failed`, `turn_busy`" } } }, "Recovery": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "recovery" }, "work": { "type": "array", "items": { "type": "object", "properties": { "work_id": { "type": "string" }, "state": { "type": "string", "enum": [ "settled", "watching", "recovering", "exhausted" ] }, "outcome": { "type": "string", "description": "For `settled`, how it ended." } } } } } }, "UploadCreate": { "type": "object", "required": [ "filename", "size" ], "properties": { "filename": { "type": "string" }, "size": { "type": "integer", "description": "The exact size in bytes (up to 500 MB). The upload is capped at this size." }, "content_type": { "type": [ "string", "null" ], "description": "The MIME type. Guessed from the file name when omitted. The POST must send the same `Content-Type` field (it is in `fields`)." } } }, "UploadCreated": { "type": "object", "properties": { "object": { "const": "upload" }, "upload_id": { "type": "string" }, "url": { "type": "string", "description": "Where to POST the file (`multipart/form-data`)." }, "fields": { "type": "object", "description": "Form fields to send with the file, exactly as given.", "additionalProperties": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time", "description": "The presigned POST works until then (15 minutes)." }, "max_bytes": { "type": "integer" } } }, "Upload": { "type": "object", "properties": { "object": { "const": "upload" }, "upload_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready" ] }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" } } }, "WorkList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkSummary" } } } }, "WorkSummary": { "type": "object", "properties": { "object": { "const": "work" }, "work_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "preview": { "type": [ "string", "null" ] }, "link": { "type": "string" } } }, "Work": { "type": "object", "properties": { "object": { "const": "work" }, "work_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "running", "stalled_credits", "idle" ], "description": "`running`, `stalled_credits` (stopped until credits are added), or `idle`." }, "text": { "type": "string", "description": "The latest result text, from `from_char`." }, "next_from_char": { "type": [ "integer", "null" ], "description": "Pass as `from_char` to read on; `null` when there's no more." }, "link": { "type": "string" }, "files": { "type": "array", "description": "The most recent files (up to 8).", "items": { "$ref": "#/components/schemas/File" } } } }, "Account": { "type": "object", "properties": { "object": { "const": "account" }, "user_id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "plan": { "type": [ "string", "null" ] }, "credits": { "type": [ "number", "null" ], "description": "Credits available now." }, "agent": { "type": "object", "properties": { "name": { "type": "string" } } }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "limits": { "type": "object", "properties": { "running_jobs": { "type": "integer", "description": "Running jobs allowed per account (5)." }, "requests_per_minute": { "type": "integer", "description": "Requests allowed per API key per minute (600)." } } } } }, "WebhookEventType": { "type": "string", "enum": [ "job.completed", "job.failed", "job.blocked", "job.resumed", "job.expired", "message.completed", "message.partial", "message.failed", "message.needs_input", "message.blocked", "message.expired" ] }, "WebhookCreate": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "A public `https` URL (port 443 or 8443, up to 2,000 characters)." }, "events": { "type": [ "array", "null" ], "description": "Events to receive, or `[\"*\"]` for all (the default).", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ], "maxLength": 120 } } }, "WebhookUpdate": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "events": { "type": [ "array", "null" ], "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ], "description": "`true` turns the endpoint back on and clears its failure state; `false` turns it off." } } }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "const": "webhook_endpoint" }, "id": { "type": "string", "description": "`whe_…`" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set when the endpoint is off (by you, or after 3 days of failed deliveries)." }, "disabled_reason": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ], "format": "date-time", "description": "When deliveries started failing. Cleared by the next success." } } }, "WebhookEndpointWithSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "The signing secret (`whsec_…`). Shown only in this response." } } } ] }, "WebhookEndpointDetail": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "recent_deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "WebhookDelivery": { "type": "object", "properties": { "object": { "const": "webhook_delivery" }, "id": { "type": "string", "description": "The delivery id (`evt_…`), sent as `webhook-id`." }, "event": { "$ref": "#/components/schemas/WebhookEventType" }, "status": { "type": "string", "enum": [ "pending", "delivered", "cancelled", "dead" ] }, "attempts": { "type": "integer" }, "last_status_code": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "last_response": { "type": [ "string", "null" ], "description": "The first 4 KB of your endpoint's last response." }, "last_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "message_id": { "type": [ "string", "null" ] } } }, "RotatedSecret": { "type": "object", "properties": { "object": { "const": "webhook_endpoint" }, "id": { "type": "string" }, "secret": { "type": "string" } } }, "Deleted": { "type": "object", "properties": { "object": { "const": "webhook_endpoint" }, "id": { "type": "string" }, "deleted": { "const": true } } }, "JobEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "job.completed", "job.failed", "job.blocked", "job.resumed", "job.expired" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "allOf": [ { "type": "object", "properties": { "object": { "const": "job" }, "message_id": { "type": "string" } } }, { "$ref": "#/components/schemas/Job" } ] } } }, "MessageEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "message.completed", "message.partial", "message.failed", "message.needs_input", "message.blocked", "message.expired" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/Message" } } }, "Error": { "type": "object", "description": "Every API error has this shape.", "required": [ "error", "message", "request_id", "docs" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "What went wrong, for people." }, "request_id": { "type": "string", "description": "The request's id (`req_…`), also in the `Request-Id` header." }, "docs": { "type": "string", "description": "A link to this error code's documentation." }, "problems": { "type": "array", "description": "With `invalid_request`: what doesn't match, one entry per problem (up to 10).", "items": { "type": "object", "properties": { "field": { "type": [ "string", "null" ], "description": "The dotted location of the field (like `files.0.url` or `wait`), or `null` for the body as a whole." }, "problem": { "type": "string" } } } }, "cursor": { "type": "string", "description": "With `poll_in_progress`: the cursor to use when you call again." } } }, "ErrorCode": { "type": "string", "description": "A stable, machine-readable error code. Each one is documented at `https://supercool.com/docs/api/errors#`.", "enum": [ "bad_request", "invalid_request", "empty_message", "too_long", "bad_cursor", "bad_url", "bad_events", "bad_size", "too_many", "unauthorized", "not_found", "idempotency_conflict", "poll_in_progress", "too_many_endpoints", "not_pending", "not_uploaded", "changed", "upload_not_ready", "too_large", "executable_refused", "rate_limited", "internal", "unavailable" ], "x-http-status": { "bad_request": 400, "invalid_request": 400, "empty_message": 400, "too_long": 400, "bad_cursor": 400, "bad_url": 400, "bad_events": 400, "bad_size": 400, "too_many": 400, "unauthorized": 401, "not_found": 404, "idempotency_conflict": 409, "poll_in_progress": 409, "too_many_endpoints": 409, "not_pending": 409, "not_uploaded": 409, "changed": 409, "upload_not_ready": 409, "too_large": 413, "executable_refused": 422, "rate_limited": 429, "internal": 500, "unavailable": 503 } } } } }