{ "openapi": "3.1.0", "info": { "title": "Superstep public API", "description": "Start workflow runs from other services and read their results, and talk to a published chat.\n\nAuthenticate with a **workflow token** (`wft_…`) in `X-Workflow-Token` or `Authorization: Bearer`. The workflow owner\ncreates tokens in the editor under **⋯ → API**; each token starts runs of one workflow only.\n\nEvery response is an envelope: `{\"success\": true, \"data\": …, \"error\": null}` or\n`{\"success\": false, \"data\": null, \"error\": {\"code\", \"message\", \"details\"}}`. `code` is the stable contract.\n\n**Chat API v1** (`/api/public/v1/chat/{slug}`): the published chat page of a workflow. An anonymous visitor is identified\nby a visitor token: send `X-Chat-Visitor: new` once, keep the `visitor_token` of the answer and send it back in\n`X-Chat-Visitor`. Messages are sent over the WebSocket `/ws/public/v1/chat/{slug}`. Clients must ignore fields they do\nnot know: v1 only grows.\n", "version": "1.1.0" }, "paths": { "/api/hooks/workflows/{wid}/runs": { "post": { "tags": [ "public" ], "summary": "Start a run", "description": "Queue a run of the workflow's latest saved version with `input` as the initial state.\n\nEach token may start `STUDIO_TRIGGER_RATE_LIMIT` runs per `STUDIO_TRIGGER_RATE_WINDOW` seconds; over the limit the\nanswer is `429 RATE_LIMITED` with `Retry-After`.", "operationId": "startRun", "security": [ { "WorkflowToken": [] }, { "WorkflowBearer": [] } ], "parameters": [ { "name": "wid", "in": "path", "required": true, "schema": { "type": "string", "description": "Workflow id (shown in the editor URL and the API dialog).", "examples": [ "example" ], "title": "Wid" }, "description": "Workflow id (shown in the editor URL and the API dialog)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartRunRequest" } } } }, "responses": { "202": { "description": "Queued (`async`), or a `sync` run still going. Poll `poll_url`; the same URL is in the `Location` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAcceptedEnvelope" } } }, "headers": { "Location": { "description": "The poll URL.", "schema": { "type": "string" } } } }, "200": { "description": "`sync` mode: the run finished within the wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResultEnvelope" } } } }, "401": { "description": "TRIGGER_TOKEN_INVALID", "content": { "application/json": { "examples": { "TRIGGER_TOKEN_INVALID": { "value": { "success": false, "error": { "code": "TRIGGER_TOKEN_INVALID", "message": "Missing, invalid or revoked workflow token" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "400": { "description": "RUN_INPUT_INVALID, CALLBACK_URL_INVALID", "content": { "application/json": { "examples": { "RUN_INPUT_INVALID": { "value": { "success": false, "error": { "code": "RUN_INPUT_INVALID", "message": "Run input must be a JSON object" } } }, "CALLBACK_URL_INVALID": { "value": { "success": false, "error": { "code": "CALLBACK_URL_INVALID", "message": "callback_url must be a public http(s) URL" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "RUN_INPUT_TOO_LARGE", "content": { "application/json": { "examples": { "RUN_INPUT_TOO_LARGE": { "value": { "success": false, "error": { "code": "RUN_INPUT_TOO_LARGE", "message": "Run input is too large (max 256 KB)" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/hooks/workflows/{wid}/runs/{run_id}": { "get": { "tags": [ "public" ], "summary": "Get a run", "description": "Status and result of a run started with this workflow's tokens. Polling is not rate limited.\n\nFinished statuses: `ok`, `error`, `cancelled`, `timeout`, `waiting` (paused at a Human node), `expired`.", "operationId": "getRun", "security": [ { "WorkflowToken": [] }, { "WorkflowBearer": [] } ], "parameters": [ { "name": "wid", "in": "path", "required": true, "schema": { "type": "string", "description": "Workflow id (shown in the editor URL and the API dialog).", "examples": [ "example" ], "title": "Wid" }, "description": "Workflow id (shown in the editor URL and the API dialog)." }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Run id returned when the run was started.", "examples": [ "3f9c2a1b7d" ], "title": "Run Id" }, "description": "Run id returned when the run was started." } ], "responses": { "200": { "description": "Current status; `final_state` once finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResultEnvelope" } } } }, "401": { "description": "TRIGGER_TOKEN_INVALID", "content": { "application/json": { "examples": { "TRIGGER_TOKEN_INVALID": { "value": { "success": false, "error": { "code": "TRIGGER_TOKEN_INVALID", "message": "Missing, invalid or revoked workflow token" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "RUN_NOT_FOUND", "content": { "application/json": { "examples": { "RUN_NOT_FOUND": { "value": { "success": false, "error": { "code": "RUN_NOT_FOUND", "message": "Run not found, already finished or not yours" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}": { "get": { "tags": [ "Chat" ], "summary": "Get the chat page", "operationId": "getChatPage", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatPageEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}/logo": { "get": { "tags": [ "Chat" ], "summary": "Get the chat logo", "operationId": "getChatLogo", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "v", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "V" } } ], "responses": { "200": { "description": "The logo image.", "content": { "application/json": { "schema": {} }, "image/png": {}, "image/jpeg": {}, "image/webp": {} } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_LOGO_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_LOGO_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_LOGO_NOT_FOUND", "message": "This chat has no logo" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ] } }, "/api/public/v1/chat/{slug}/sessions": { "get": { "tags": [ "Chat" ], "summary": "List the caller's chats", "operationId": "listChatSessions", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSessionListEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Chat" ], "summary": "Start a chat", "operationId": "createChatSession", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSessionEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "embed": { "type": "boolean", "description": "The chat is opened in an embed (the widget)." } } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}": { "get": { "tags": [ "Chat" ], "summary": "Get a chat with its turns", "operationId": "getChatSession", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatSessionViewEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}/edits": { "post": { "tags": [ "Chat" ], "summary": "Prepare an independent edited conversation", "operationId": "prepareChatEdit", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatEditIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatEditEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_SESSION_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "400": { "description": "CHAT_EDIT_INVALID", "content": { "application/json": { "examples": { "CHAT_EDIT_INVALID": { "value": { "success": false, "error": { "code": "CHAT_EDIT_INVALID", "message": "This message cannot be edited" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CHAT_EDIT_BUSY, CHAT_EDIT_STALE, CHAT_EDIT_CONTEXT_UNAVAILABLE, CHAT_EDIT_CONFLICT", "content": { "application/json": { "examples": { "CHAT_EDIT_BUSY": { "value": { "success": false, "error": { "code": "CHAT_EDIT_BUSY", "message": "Wait for the conversation to finish before creating a new branch" } } }, "CHAT_EDIT_STALE": { "value": { "success": false, "error": { "code": "CHAT_EDIT_STALE", "message": "The conversation changed; refresh it before trying again" } } }, "CHAT_EDIT_CONTEXT_UNAVAILABLE": { "value": { "success": false, "error": { "code": "CHAT_EDIT_CONTEXT_UNAVAILABLE", "message": "The agent context at this point is no longer available; start a new conversation" } } }, "CHAT_EDIT_CONFLICT": { "value": { "success": false, "error": { "code": "CHAT_EDIT_CONFLICT", "message": "This operation ID was already used for a different revision" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "CHAT_EDIT_GONE", "content": { "application/json": { "examples": { "CHAT_EDIT_GONE": { "value": { "success": false, "error": { "code": "CHAT_EDIT_GONE", "message": "The new conversation branch was removed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}/regenerations": { "post": { "tags": [ "Chat" ], "summary": "Prepare a fresh attempt of the latest terminal answer", "operationId": "prepareChatRegeneration", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRegenerateIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatEditEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_SESSION_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "400": { "description": "CHAT_REGENERATE_INVALID", "content": { "application/json": { "examples": { "CHAT_REGENERATE_INVALID": { "value": { "success": false, "error": { "code": "CHAT_REGENERATE_INVALID", "message": "Only the latest completed answer can be regenerated" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CHAT_EDIT_BUSY, CHAT_EDIT_STALE, CHAT_EDIT_CONTEXT_UNAVAILABLE, CHAT_EDIT_CONFLICT", "content": { "application/json": { "examples": { "CHAT_EDIT_BUSY": { "value": { "success": false, "error": { "code": "CHAT_EDIT_BUSY", "message": "Wait for the conversation to finish before creating a new branch" } } }, "CHAT_EDIT_STALE": { "value": { "success": false, "error": { "code": "CHAT_EDIT_STALE", "message": "The conversation changed; refresh it before trying again" } } }, "CHAT_EDIT_CONTEXT_UNAVAILABLE": { "value": { "success": false, "error": { "code": "CHAT_EDIT_CONTEXT_UNAVAILABLE", "message": "The agent context at this point is no longer available; start a new conversation" } } }, "CHAT_EDIT_CONFLICT": { "value": { "success": false, "error": { "code": "CHAT_EDIT_CONFLICT", "message": "This operation ID was already used for a different revision" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "CHAT_EDIT_GONE", "content": { "application/json": { "examples": { "CHAT_EDIT_GONE": { "value": { "success": false, "error": { "code": "CHAT_EDIT_GONE", "message": "The new conversation branch was removed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}/turns": { "get": { "tags": [ "Chat" ], "summary": "List newer turns", "description": "The chat's turns after the turn `after` (all of them without it), in order, in the page's steps mode. An `after`\nthat is not a turn of this chat is `404 CHAT_TURN_NOT_FOUND`.", "operationId": "listChatTurns", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "After" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatTurnsEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND, CHAT_TURN_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } }, "CHAT_TURN_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_TURN_NOT_FOUND", "message": "Message not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}/attachments": { "post": { "tags": [ "Chat" ], "summary": "Upload a file before the message", "operationId": "uploadChatAttachment", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "CHAT_ATTACHMENTS_OFF, CHAT_ATTACHMENT_DEMO", "content": { "application/json": { "examples": { "CHAT_ATTACHMENTS_OFF": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENTS_OFF", "message": "This chat does not accept attachments" } } }, "CHAT_ATTACHMENT_DEMO": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENT_DEMO", "message": "Attachments are turned off in the public demo" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "400": { "description": "CHAT_ATTACHMENT_TYPE, CHAT_ATTACHMENT_TOO_MANY", "content": { "application/json": { "examples": { "CHAT_ATTACHMENT_TYPE": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENT_TYPE", "message": "This file type is not allowed here. Allowed: document, image" } } }, "CHAT_ATTACHMENT_TOO_MANY": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENT_TOO_MANY", "message": "A message may carry at most 5 files" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "CHAT_ATTACHMENT_TOO_LARGE", "content": { "application/json": { "examples": { "CHAT_ATTACHMENT_TOO_LARGE": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENT_TOO_LARGE", "message": "A file may be at most 10 MB" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}/attachments/{aid}": { "get": { "tags": [ "Chat" ], "summary": "Download a file", "operationId": "downloadChatAttachment", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string", "title": "Aid" } } ], "responses": { "200": { "description": "The file, as a download.", "content": { "application/json": { "schema": {} }, "application/octet-stream": {} } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND, CHAT_ATTACHMENT_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } }, "CHAT_ATTACHMENT_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENT_NOT_FOUND", "message": "File not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Chat" ], "summary": "Delete an unsent file", "operationId": "deleteChatAttachment", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } }, { "name": "aid", "in": "path", "required": true, "schema": { "type": "string", "title": "Aid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND, CHAT_ATTACHMENT_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } }, "CHAT_ATTACHMENT_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_ATTACHMENT_NOT_FOUND", "message": "File not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/public/v1/chat/{slug}/sessions/{sid}/turns/{tid}/rating": { "put": { "tags": [ "Chat" ], "summary": "Rate an answer", "operationId": "rateChatTurn", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } }, { "name": "tid", "in": "path", "required": true, "schema": { "type": "string", "title": "Tid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRatingIn" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRatingEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND, CHAT_TURN_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } }, "CHAT_TURN_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_TURN_NOT_FOUND", "message": "Message not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "CHAT_RATING_NOT_ALLOWED", "content": { "application/json": { "examples": { "CHAT_RATING_NOT_ALLOWED": { "value": { "success": false, "error": { "code": "CHAT_RATING_NOT_ALLOWED", "message": "This message cannot be rated" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "400": { "description": "CHAT_RATING_INVALID", "content": { "application/json": { "examples": { "CHAT_RATING_INVALID": { "value": { "success": false, "error": { "code": "CHAT_RATING_INVALID", "message": "Rating: invalid value" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Chat" ], "summary": "Remove a rating", "operationId": "unrateChatTurn", "security": [ { "ChatUserToken": [] }, { "ChatVisitor": [] }, {} ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "title": "Slug" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "title": "Sid" } }, { "name": "tid", "in": "path", "required": true, "schema": { "type": "string", "title": "Tid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkEnvelope" } } } }, "422": { "description": "VALIDATION_ERROR", "content": { "application/json": { "examples": { "VALIDATION_ERROR": { "value": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "CHAT_NOT_PUBLISHED, CHAT_SESSION_NOT_FOUND, CHAT_TURN_NOT_FOUND", "content": { "application/json": { "examples": { "CHAT_NOT_PUBLISHED": { "value": { "success": false, "error": { "code": "CHAT_NOT_PUBLISHED", "message": "This chat is not available" } } }, "CHAT_SESSION_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_SESSION_NOT_FOUND", "message": "Chat not found" } } }, "CHAT_TURN_NOT_FOUND": { "value": { "success": false, "error": { "code": "CHAT_TURN_NOT_FOUND", "message": "Message not found" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "CHAT_SIGN_IN_REQUIRED", "content": { "application/json": { "examples": { "CHAT_SIGN_IN_REQUIRED": { "value": { "success": false, "error": { "code": "CHAT_SIGN_IN_REQUIRED", "message": "Sign in to use this chat" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "examples": { "RATE_LIMITED": { "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests, retry in 12 s" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "schemas": { "AttachmentLimits": { "properties": { "enabled": { "type": "boolean", "title": "Enabled" }, "kinds": { "items": { "type": "string" }, "type": "array", "title": "Kinds", "description": "Allowed kinds: `document`, `image`." }, "max_files": { "type": "integer", "title": "Max Files" }, "max_mb": { "type": "number", "title": "Max Mb" } }, "additionalProperties": true, "type": "object", "required": [ "enabled", "kinds", "max_files", "max_mb" ], "title": "AttachmentLimits" }, "ChatAttachment": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "kind": { "type": "string", "title": "Kind" }, "mime": { "type": "string", "title": "Mime" }, "size": { "type": "integer", "title": "Size", "description": "Bytes." }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token" } }, "additionalProperties": true, "type": "object", "required": [ "id", "name", "kind", "mime", "size" ], "title": "ChatAttachment" }, "ChatAttachmentEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatAttachment" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatAttachmentEnvelope", "description": "Success envelope: an uploaded file." }, "ChatEdit": { "properties": { "session": { "$ref": "#/components/schemas/ChatSessionView" }, "operation_id": { "type": "string", "title": "Operation Id" }, "run_id": { "type": "string", "title": "Run Id" }, "message": { "type": "string", "title": "Message" }, "attachment_ids": { "items": { "type": "string" }, "type": "array", "title": "Attachment Ids" }, "state": { "type": "string", "enum": [ "prepared", "started", "finished" ], "title": "State" }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token" } }, "additionalProperties": true, "type": "object", "required": [ "session", "operation_id", "run_id", "message", "attachment_ids", "state" ], "title": "ChatEdit" }, "ChatEditEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatEdit" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatEditEnvelope", "description": "Success envelope: a prepared independent revision branch (edit or regenerate)." }, "ChatEditIn": { "properties": { "turn_id": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Turn Id" }, "operation_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "title": "Operation Id" }, "expected_last_turn_id": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Expected Last Turn Id" }, "message": { "type": "string", "maxLength": 4000, "title": "Message" } }, "type": "object", "required": [ "turn_id", "operation_id", "expected_last_turn_id", "message" ], "title": "ChatEditIn" }, "ChatPage": { "properties": { "slug": { "type": "string", "title": "Slug", "examples": [ "support" ] }, "title": { "type": "string", "title": "Title", "examples": [ "Support" ] }, "intro": { "type": "string", "title": "Intro", "description": "Markdown shown above the first message.", "default": "" }, "suggestions": { "items": { "type": "string" }, "type": "array", "title": "Suggestions", "description": "Up to 4 suggested first messages." }, "access": { "anyOf": [ { "type": "string", "enum": [ "studio", "anonymous", "signed_in", "app" ] }, { "items": { "type": "string", "enum": [ "studio", "anonymous", "signed_in", "app" ] }, "type": "array" } ], "title": "Access" }, "steps_mode": { "type": "string", "enum": [ "none", "labels", "full" ], "title": "Steps Mode", "description": "What a visitor sees of the run's steps." }, "signed_in": { "type": "boolean", "title": "Signed In", "description": "Whether the caller is a signed-in studio user." }, "embed_origins": { "items": { "type": "string" }, "type": "array", "title": "Embed Origins", "description": "Sites that may embed the page in an iframe." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo", "description": "Hash of the logo; fetch it from `.../logo?v=`." }, "attachments": { "$ref": "#/components/schemas/AttachmentLimits" } }, "additionalProperties": true, "type": "object", "required": [ "slug", "title", "access", "steps_mode", "signed_in", "attachments" ], "title": "ChatPage", "description": "The published chat page: what a client shows before the first message." }, "ChatPageEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatPage" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatPageEnvelope", "description": "Success envelope: the chat page." }, "ChatRating": { "properties": { "value": { "type": "string", "enum": [ "up", "down" ], "title": "Value" }, "comment": { "type": "string", "title": "Comment", "default": "" }, "updated": { "type": "number", "title": "Updated" }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token" } }, "additionalProperties": true, "type": "object", "required": [ "value", "updated" ], "title": "ChatRating" }, "ChatRatingEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatRating" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatRatingEnvelope", "description": "Success envelope: the rating." }, "ChatRatingIn": { "properties": { "value": { "type": "string", "title": "Value" }, "comment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comment" } }, "type": "object", "required": [ "value" ], "title": "ChatRatingIn", "description": "A thumbs up or down on one finished answer (DEC-0070). `comment` is only kept with a thumbs down." }, "ChatRegenerateIn": { "properties": { "turn_id": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Turn Id" }, "operation_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$", "title": "Operation Id" }, "expected_last_turn_id": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Expected Last Turn Id" } }, "additionalProperties": false, "type": "object", "required": [ "turn_id", "operation_id", "expected_last_turn_id" ], "title": "ChatRegenerateIn" }, "ChatSession": { "properties": { "id": { "type": "string", "title": "Id", "examples": [ "c7d1e0a9b2" ] }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "channel": { "type": "string", "title": "Channel" }, "title": { "type": "string", "title": "Title" }, "last_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Run Id" }, "created": { "type": "number", "title": "Created", "description": "Unix time (seconds)." }, "updated": { "type": "number", "title": "Updated", "description": "Unix time (seconds)." }, "source_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Session Id" }, "source_turn_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Turn Id" }, "source_action": { "anyOf": [ { "type": "string", "enum": [ "edit", "regenerate" ] }, { "type": "null" } ], "title": "Source Action" }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token", "description": "Set once for a new anonymous visitor that sent `X-Chat-Visitor: new`: keep it and send it back in `X-Chat-Visitor`." } }, "additionalProperties": true, "type": "object", "required": [ "id", "workflow_id", "channel", "title", "created", "updated" ], "title": "ChatSession" }, "ChatSessionEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatSession" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatSessionEnvelope", "description": "Success envelope: a new chat." }, "ChatSessionList": { "properties": { "sessions": { "items": { "$ref": "#/components/schemas/ChatSession" }, "type": "array", "title": "Sessions" }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token" } }, "additionalProperties": true, "type": "object", "required": [ "sessions" ], "title": "ChatSessionList" }, "ChatSessionListEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatSessionList" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatSessionListEnvelope", "description": "Success envelope: the caller's chats." }, "ChatSessionView": { "properties": { "id": { "type": "string", "title": "Id", "examples": [ "c7d1e0a9b2" ] }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "channel": { "type": "string", "title": "Channel" }, "title": { "type": "string", "title": "Title" }, "last_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Run Id" }, "created": { "type": "number", "title": "Created", "description": "Unix time (seconds)." }, "updated": { "type": "number", "title": "Updated", "description": "Unix time (seconds)." }, "source_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Session Id" }, "source_turn_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Turn Id" }, "source_action": { "anyOf": [ { "type": "string", "enum": [ "edit", "regenerate" ] }, { "type": "null" } ], "title": "Source Action" }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token", "description": "Set once for a new anonymous visitor that sent `X-Chat-Visitor: new`: keep it and send it back in `X-Chat-Visitor`." }, "steps_mode": { "type": "string", "enum": [ "none", "labels", "full" ], "title": "Steps Mode" }, "turns": { "items": { "$ref": "#/components/schemas/ChatTurn" }, "type": "array", "title": "Turns" }, "capabilities": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Capabilities" } }, "additionalProperties": true, "type": "object", "required": [ "id", "workflow_id", "channel", "title", "created", "updated", "steps_mode", "turns" ], "title": "ChatSessionView", "description": "One chat with its turns in the page's steps mode." }, "ChatSessionViewEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatSessionView" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatSessionViewEnvelope", "description": "Success envelope: one chat with its turns." }, "ChatTurn": { "properties": { "id": { "type": "string", "title": "Id" }, "role": { "type": "string", "enum": [ "user", "assistant" ], "title": "Role" }, "text": { "type": "string", "title": "Text" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status", "description": "Answer status, e.g. `ok`, `error`, `waiting`, `cancelled`." }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Id" }, "node": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Node", "description": "Set on a Human node's question: the node to answer." }, "answered_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Answered By" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code", "description": "Error code of a failed answer." }, "created": { "type": "number", "title": "Created" }, "inherited": { "type": "boolean", "title": "Inherited", "default": false }, "editable": { "type": "boolean", "title": "Editable", "default": false }, "regeneratable": { "type": "boolean", "title": "Regeneratable", "default": false }, "attachments": { "items": { "$ref": "#/components/schemas/ChatAttachment" }, "type": "array", "title": "Attachments" }, "rating": { "anyOf": [ { "$ref": "#/components/schemas/ChatRating" }, { "type": "null" } ] }, "run_exists": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Run Exists" }, "steps": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Steps", "description": "The run's steps in `steps_mode`, on the run's first answer." } }, "additionalProperties": true, "type": "object", "required": [ "id", "role", "text", "created" ], "title": "ChatTurn" }, "ChatTurns": { "properties": { "turns": { "items": { "$ref": "#/components/schemas/ChatTurn" }, "type": "array", "title": "Turns" }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token" } }, "additionalProperties": true, "type": "object", "required": [ "turns" ], "title": "ChatTurns", "description": "The turns after `after` (incremental history): poll with the id of the last turn you have." }, "ChatTurnsEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/ChatTurns" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "ChatTurnsEnvelope", "description": "Success envelope: newer turns." }, "ErrorBody": { "properties": { "code": { "type": "string", "title": "Code", "description": "Stable UPPER_SNAKE error code; the contract (see docs/api-errors.md).", "examples": [ "TRIGGER_TOKEN_INVALID" ] }, "message": { "type": "string", "title": "Message", "description": "English message for humans and logs.", "examples": [ "Missing, invalid or revoked workflow token" ] }, "details": { "anyOf": [ {}, { "type": "null" } ], "title": "Details", "description": "Optional extra data, e.g. a list of {field, message} for VALIDATION_ERROR." } }, "type": "object", "required": [ "code", "message" ], "title": "ErrorBody" }, "ErrorEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": false, "examples": [ false ] }, "data": { "type": "null", "title": "Data" }, "error": { "$ref": "#/components/schemas/ErrorBody" } }, "type": "object", "required": [ "error" ], "title": "ErrorEnvelope" }, "Ok": { "properties": { "ok": { "type": "boolean", "title": "Ok", "default": true }, "visitor_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Visitor Token" } }, "additionalProperties": true, "type": "object", "title": "Ok" }, "OkEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/Ok" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "OkEnvelope", "description": "Success envelope: done." }, "RunAccepted": { "properties": { "run_id": { "type": "string", "title": "Run Id", "examples": [ "3f9c2a1b7d" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ok", "error", "cancelled", "timeout", "waiting", "expired" ], "title": "Status", "examples": [ "queued" ] }, "poll_url": { "type": "string", "title": "Poll Url", "examples": [ "https://superstep.example.com/api/hooks/workflows/example/runs/3f9c2a1b7d" ] } }, "type": "object", "required": [ "run_id", "status", "poll_url" ], "title": "RunAccepted", "description": "202 body: the run is queued; poll `poll_url` (also sent as the Location header)." }, "RunAcceptedEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "anyOf": [ { "$ref": "#/components/schemas/RunAccepted" }, { "$ref": "#/components/schemas/RunPending" } ], "title": "Data" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "RunAcceptedEnvelope", "description": "Success envelope of a 202: a queued run, or a sync run that is still going." }, "RunMetrics": { "properties": { "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration Ms" }, "tokens_in": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens In" }, "tokens_out": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tokens Out" }, "cost_usd": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Cost Usd" }, "error_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Error Count" } }, "type": "object", "title": "RunMetrics" }, "RunPending": { "properties": { "run_id": { "type": "string", "title": "Run Id" }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "status": { "type": "string", "enum": [ "queued", "running", "ok", "error", "cancelled", "timeout", "waiting", "expired" ], "title": "Status" }, "source": { "type": "string", "title": "Source", "description": "Where the run came from: `api` for this API." }, "final_state": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Final State", "description": "State at the end; set once the run has finished." }, "error": { "anyOf": [ {}, { "type": "null" } ], "title": "Error", "description": "The last error event of a failed run (an object with `code` and `message`)." }, "waiting": { "anyOf": [ { "$ref": "#/components/schemas/RunWaiting" }, { "type": "null" } ] }, "parent_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Run Id", "description": "Set on the child run of a workflow tool: the run whose Agent node called it." }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/RunMetrics" }, { "type": "null" } ] }, "trace_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Url" }, "started": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Started", "description": "Unix time (seconds)." }, "ended": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Ended", "description": "Unix time (seconds); set once the run has finished." }, "poll_url": { "type": "string", "title": "Poll Url" } }, "type": "object", "required": [ "run_id", "workflow_id", "status", "source", "poll_url" ], "title": "RunPending", "description": "202 body of a `sync` run that is still going after STUDIO_SYNC_WAIT_MAX: the current result plus `poll_url`.", "examples": [ { "ended": 1761292800.4, "final_state": { "intent": "order_status" }, "metrics": { "cost_usd": 0.0, "duration_ms": 412, "error_count": 0, "tokens_in": 0, "tokens_out": 0 }, "run_id": "3f9c2a1b7d", "source": "api", "started": 1761292800.0, "status": "ok", "workflow_id": "example" } ] }, "RunResult": { "properties": { "run_id": { "type": "string", "title": "Run Id" }, "workflow_id": { "type": "string", "title": "Workflow Id" }, "status": { "type": "string", "enum": [ "queued", "running", "ok", "error", "cancelled", "timeout", "waiting", "expired" ], "title": "Status" }, "source": { "type": "string", "title": "Source", "description": "Where the run came from: `api` for this API." }, "final_state": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Final State", "description": "State at the end; set once the run has finished." }, "error": { "anyOf": [ {}, { "type": "null" } ], "title": "Error", "description": "The last error event of a failed run (an object with `code` and `message`)." }, "waiting": { "anyOf": [ { "$ref": "#/components/schemas/RunWaiting" }, { "type": "null" } ] }, "parent_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Run Id", "description": "Set on the child run of a workflow tool: the run whose Agent node called it." }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/RunMetrics" }, { "type": "null" } ] }, "trace_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Url" }, "started": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Started", "description": "Unix time (seconds)." }, "ended": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Ended", "description": "Unix time (seconds); set once the run has finished." } }, "type": "object", "required": [ "run_id", "workflow_id", "status", "source" ], "title": "RunResult", "examples": [ { "ended": 1761292800.4, "final_state": { "intent": "order_status" }, "metrics": { "cost_usd": 0.0, "duration_ms": 412, "error_count": 0, "tokens_in": 0, "tokens_out": 0 }, "run_id": "3f9c2a1b7d", "source": "api", "started": 1761292800.0, "status": "ok", "workflow_id": "example" } ] }, "RunResultEnvelope": { "properties": { "success": { "type": "boolean", "title": "Success", "default": true, "examples": [ true ] }, "data": { "$ref": "#/components/schemas/RunResult" }, "error": { "type": "null", "title": "Error" } }, "type": "object", "required": [ "data" ], "title": "RunResultEnvelope", "description": "Success envelope carrying a run result." }, "RunWaiting": { "properties": { "node": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Node" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prompt" }, "child_run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Child Run Id", "description": "Set while an Agent node's workflow tool runs: the child run the run waits for." } }, "type": "object", "title": "RunWaiting", "description": "Set when status is `waiting`: the Human node the run is paused at, or the child run of a workflow tool it waits for." }, "StartRunRequest": { "properties": { "input": { "additionalProperties": true, "type": "object", "title": "Input", "description": "Initial state of the run." }, "mode": { "type": "string", "enum": [ "async", "sync" ], "title": "Mode", "description": "`async` returns 202 at once. `sync` waits up to STUDIO_SYNC_WAIT_MAX seconds for the result, then falls back to 202 with `poll_url`.", "default": "async" }, "callback_url": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Callback Url", "description": "Public http(s) URL that receives a signed POST when the run ends." } }, "type": "object", "title": "StartRunRequest", "examples": [ { "input": { "message": "where is my order A100" }, "mode": "async" } ] } }, "securitySchemes": { "WorkflowToken": { "type": "apiKey", "description": "Workflow token (`wft_…`), created by the workflow owner under **⋯ → API** in the editor.", "in": "header", "name": "X-Workflow-Token" }, "WorkflowBearer": { "type": "http", "description": "The same workflow token as `Authorization: Bearer wft_…`.", "scheme": "bearer", "bearerFormat": "wft_…" }, "HTTPBearer": { "type": "http", "scheme": "bearer" }, "ChatUserToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "HS256 user token signed server-side with a chat app key. aud=superstep-chat:; lifetime at most 1 hour. Never send the app secret to a client." }, "ChatVisitor": { "type": "apiKey", "in": "header", "name": "X-Chat-Visitor", "description": "Anonymous visitor token, or new to create one." } } }, "tags": [ { "name": "public", "description": "Workflow-trigger API for external callers (workflow token)." }, { "name": "Chat", "description": "Chat API v1: a published chat page, its chats, files and ratings (anonymous visitor, studio sign-in or a third-party HS256 user token)." } ] }