{ "openapi": "3.1.0", "info": { "title": "Kazzle API", "description": "Development documentation", "version": "1.0.0" }, "servers": [ { "url": "http://localhost:8080", "description": "Local" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Better Auth JWT token" }, "apiKey": { "type": "http", "scheme": "bearer", "description": "Kazzle API key (kzl_ prefix)" } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/chat/models": { "get": { "operationId": "getChatModels", "tags": [ "chat" ], "description": "List available AI models", "responses": { "200": { "description": "Models list", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "pricingRates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "credits": { "type": "string" }, "creditsPerUnit": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "label", "credits", "creditsPerUnit", "unit" ] } }, "effortOptions": { "type": "array", "items": { "type": "string" } }, "defaultEffort": { "type": "string" } }, "required": [ "id", "name", "provider" ], "additionalProperties": {} } }, "defaultModelId": { "type": "string" } }, "required": [ "models", "defaultModelId" ] } } } } } } }, "/chat/stream": { "post": { "operationId": "postChatStream", "tags": [ "chat" ], "summary": "Stream a conversation", "description": "Starts or continues an AI streaming conversation for a thread. Returns a Server-Sent Events stream of model output and tool activity.", "responses": { "200": { "description": "SSE stream of conversation events" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not the thread owner" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autoModel": { "type": "boolean" }, "modelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "default": [], "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "fileType": { "type": "string", "enum": [ "image", "pdf", "text", "code", "binary" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "containerId": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "path" ] } }, "notification": { "description": "Notification delivery preferences for this message/automation. priority today; extensible later. Missing → default.", "type": "object", "properties": { "priority": { "description": "How noisy the push for this turn is. low = no sound/quiet; default = normal banner + sound; high = heads-up on Android/desktop (on iOS behaves like default). See documents/notifications.md.", "type": "string", "enum": [ "low", "default", "high" ] } } }, "content": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "ask", "work" ] }, "threadId": { "type": "string" }, "toolResults": { "type": "array", "items": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "string" }, "isError": { "type": "boolean" }, "isTimeout": { "type": "boolean" } }, "required": [ "toolUseId", "content" ] } }, "spaceId": { "type": "string" }, "outboxItemId": { "type": "string" }, "userMessageId": { "type": "string" }, "deviceComputerId": { "type": "string" }, "openTabs": { "type": "array", "items": { "type": "object", "properties": { "paneId": { "type": "string" }, "isActive": { "type": "boolean" }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "tabId": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "isActive": { "type": "boolean" } }, "required": [ "tabId", "type", "title", "isActive" ] } } }, "required": [ "paneId", "isActive", "tabs" ] } }, "agentContextSnapshot": { "type": "object", "properties": { "capturedAt": { "type": "number" }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipLocation": { "anyOf": [ { "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "timezone": { "type": "string" }, "source": { "type": "string", "const": "cloudflare" } }, "required": [ "source" ] }, { "type": "null" } ] }, "windowSessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "senderComputerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spaceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "activePaneId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "panes": { "type": "array", "items": { "type": "object", "properties": { "paneId": { "type": "string" }, "isActive": { "type": "boolean" }, "activeTabId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tabs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "isActive": { "type": "boolean" }, "containerDriveItemId": { "type": "string" }, "path": { "type": "string" }, "totalLines": { "type": "number" }, "url": { "type": "string" }, "isLoading": { "type": "boolean" }, "browserTabId": { "type": "string" }, "sessionId": { "type": "string" }, "cwd": { "type": "string" }, "lastCommand": { "type": "string" }, "appId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "type", "title" ] } } }, "required": [ "paneId", "isActive", "activeTabId", "tabs" ] } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "active-tab", "closed-tab", "closed-pane", "closed-window", "thread", "page" ] }, "title": { "type": "string" }, "type": { "type": "string" }, "tabId": { "type": "string" }, "threadId": { "type": "string" }, "closedAt": { "type": "number" }, "lastSeenAt": { "type": "number" } }, "required": [ "kind", "title" ] } }, "linkedResources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "containerDriveItemId": { "type": "string" }, "path": { "type": "string" } }, "required": [ "type", "label" ] } } }, "required": [ "capturedAt", "windowSessionId", "senderComputerId", "spaceId", "activePaneId", "panes", "recent", "linkedResources" ] }, "rerunMessageId": { "type": "string" }, "truncateFromMessageId": { "type": "string" }, "truncateFromMessageOrder": { "type": "object", "properties": { "globalMessageOrder": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "id": { "type": "string" } }, "required": [ "globalMessageOrder", "createdAt", "id" ] }, "visibility": { "type": "string", "enum": [ "public", "private", "incognito" ] } }, "required": [ "threadId" ] } } } } } }, "/chat/watch/{threadId}": { "get": { "operationId": "getChatWatchByThreadId", "tags": [ "chat" ], "summary": "Watch a streaming thread", "description": "Subscribes to an active streaming thread via Server-Sent Events — replays buffered events then live-tails new ones. Used by readers other than the device that started the stream.", "responses": { "200": { "description": "SSE stream (replay + live tail)" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not a member of this space" } }, "parameters": [ { "in": "path", "name": "threadId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "after", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "in": "query", "name": "afterOrder", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "in": "query", "name": "afterDelta", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "in": "query", "name": "afterEpoch", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "in": "query", "name": "afterSequence", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "in": "query", "name": "messageId", "schema": { "type": "string" } } ] } }, "/chat/resume": { "post": { "operationId": "postChatResume", "tags": [ "chat" ], "summary": "Resume a stream", "description": "Resumes streaming for a thread that was paused or whose stream crashed. Returns a Server-Sent Events stream continuing the conversation.", "responses": { "200": { "description": "SSE stream continuing the conversation" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not the thread owner" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string" }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "toolCallId": { "type": "string" }, "elementId": { "type": "string" }, "input": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "toolCallId", "elementId" ] } }, "deviceComputerId": { "type": "string" } }, "required": [ "threadId" ] } } } } } }, "/chat/stop": { "post": { "operationId": "postChatStop", "tags": [ "chat" ], "description": "Stop an active streaming thread", "responses": { "200": { "description": "Stopped", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string" } }, "required": [ "threadId" ] } } } } } }, "/ai/models": { "get": { "operationId": "getAiModels", "summary": "List available AI models", "description": "Returns the model catalog the proxy can route to. Combined Cloudflare catalog + Workers AI catalog, deduped by id. Each `id` is in `provider/model` form — pass it verbatim as `model` on the endpoints. Filter by `modality` (chat, image, audio, video, data) to find ids that work on a given endpoint.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Model catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Model id in `provider/model` form, e.g. `openai/gpt-4o-mini`. Pass this verbatim as `model` on the proxy endpoints." }, "provider": { "type": "string", "description": "Provider prefix, e.g. `openai`, `anthropic`, `@cf`." }, "displayName": { "type": "string" }, "name": { "type": "string" }, "subtitle": { "type": "string" }, "pricingRates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "credits": { "type": "string" }, "creditsPerUnit": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "label", "credits", "creditsPerUnit", "unit" ] } }, "modalities": { "type": "array", "items": { "type": "string", "enum": [ "chat", "image", "audio", "video", "data" ] }, "description": "Which endpoints this model serves." }, "inputTypes": { "type": "array", "items": { "type": "string" } }, "outputTypes": { "type": "array", "items": { "type": "string" } }, "supportsStreaming": { "type": "boolean" }, "supportsTools": { "type": "boolean" }, "supportsJson": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "contextWindow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "defaultParams": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "billingMode": { "type": "string", "const": "cloudflare-cost" } }, "required": [ "id", "provider", "displayName", "name", "subtitle", "pricingRates", "modalities", "inputTypes", "outputTypes", "supportsStreaming", "supportsTools", "supportsJson", "reasoning", "contextWindow", "defaultParams", "billingMode" ] } } }, "required": [ "models" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "parameters": [ { "in": "query", "name": "modality", "schema": { "type": "string", "enum": [ "chat", "image", "audio", "video", "data" ] }, "description": "Only return models that serve this endpoint." } ] } }, "/ai/responses/{responseId}": { "get": { "operationId": "getAiResponsesByResponseId", "summary": "Poll an async AI response", "description": "Fetches a stored async response (currently used for video jobs). Returns the standardized `AsyncJob` shape with current status and output if available.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Stored response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed" ] }, "pollUrl": { "type": "string" }, "output": { "type": "object", "properties": {}, "additionalProperties": {} }, "error": { "type": "string" } }, "required": [ "jobId", "status", "pollUrl" ], "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "responseId", "required": true } ] } }, "/ai/chat/completions": { "post": { "operationId": "postAiChatCompletions", "summary": "Chat completions (OpenAI-compatible)", "description": "OpenAI-compatible chat completions. Forwarded to Cloudflare AI Gateway `compat/chat/completions`; Kazzle changes only the path, auth, and billing header. `response_format: { type: \"json_object\" }` makes `choices[].message.content` valid JSON text, but apps must still parse and validate that text against their own domain schema.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "metadata": { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be\nuseful for storing additional information about the object in a structured\nformat, and querying for objects via API or the dashboard. \n\nKeys are strings with a maximum length of 64 characters. Values are strings\nwith a maximum length of 512 characters.\n", "additionalProperties": { "type": "string" }, "x-oaiTypeLabel": "map", "nullable": true }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1, "example": 1, "nullable": true, "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.\nWe generally recommend altering this or `top_p` but not both.\n" }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "default": 1, "example": 1, "nullable": true, "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability\nmass. So 0.1 means only the tokens comprising the top 10% probability mass\nare considered.\n\nWe generally recommend altering this or `temperature` but not both.\n" }, "user": { "type": "string", "example": "user-1234", "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).\n" }, "service_tier": { "type": "string", "description": "Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:\n - If set to 'auto', and the Project is Scale tier enabled, the system\n will utilize scale tier credits until they are exhausted.\n - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing).\n - When not set, the default behavior is 'auto'.\n\n When this parameter is set, the response body will include the `service_tier` utilized.\n", "enum": [ "auto", "default", "flex" ], "nullable": true, "default": "auto" } } } ] }, { "type": "object", "properties": { "messages": { "description": "A list of messages comprising the conversation so far. Depending on the\n[model](/docs/models) you use, different message types (modalities) are\nsupported, like [text](/docs/guides/text-generation),\n[images](/docs/guides/vision), and [audio](/docs/guides/audio).\n", "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "title": "Developer message", "description": "Developer-provided instructions that the model should follow, regardless of\nmessages sent by the user. With o1 models and newer, `developer` messages\nreplace the previous `system` messages.\n", "properties": { "content": { "description": "The contents of the developer message.", "oneOf": [ { "type": "string", "description": "The contents of the developer message.", "title": "Text content" }, { "type": "array", "description": "An array of content parts with a defined type. For developer messages, only type `text` is supported.", "title": "Array of content parts", "items": { "type": "object", "title": "Text content part", "description": "Learn about [text inputs](/docs/guides/text-generation).\n", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part.", "x-stainless-const": true }, "text": { "type": "string", "description": "The text content." } }, "required": [ "type", "text" ] }, "minItems": 1 } ] }, "role": { "type": "string", "enum": [ "developer" ], "description": "The role of the messages author, in this case `developer`.", "x-stainless-const": true }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } }, "required": [ "content", "role" ] }, { "type": "object", "title": "System message", "description": "Developer-provided instructions that the model should follow, regardless of\nmessages sent by the user. With o1 models and newer, use `developer` messages\nfor this purpose instead.\n", "properties": { "content": { "description": "The contents of the system message.", "oneOf": [ { "type": "string", "description": "The contents of the system message.", "title": "Text content" }, { "type": "array", "description": "An array of content parts with a defined type. For system messages, only type `text` is supported.", "title": "Array of content parts", "items": { "oneOf": [ { "type": "object", "title": "Text content part", "description": "Learn about [text inputs](/docs/guides/text-generation).\n", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part.", "x-stainless-const": true }, "text": { "type": "string", "description": "The text content." } }, "required": [ "type", "text" ] } ] }, "minItems": 1 } ] }, "role": { "type": "string", "enum": [ "system" ], "description": "The role of the messages author, in this case `system`.", "x-stainless-const": true }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } }, "required": [ "content", "role" ] }, { "type": "object", "title": "User message", "description": "Messages sent by an end user, containing prompts or additional context\ninformation.\n", "properties": { "content": { "description": "The contents of the user message.\n", "oneOf": [ { "type": "string", "description": "The text contents of the message.", "title": "Text content" }, { "type": "array", "description": "An array of content parts with a defined type. Supported options differ based on the [model](/docs/models) being used to generate the response. Can contain text, image, or audio inputs.", "title": "Array of content parts", "items": { "oneOf": [ { "type": "object", "title": "Text content part", "description": "Learn about [text inputs](/docs/guides/text-generation).\n", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part.", "x-stainless-const": true }, "text": { "type": "string", "description": "The text content." } }, "required": [ "type", "text" ] }, { "type": "object", "title": "Image content part", "description": "Learn about [image inputs](/docs/guides/vision).\n", "properties": { "type": { "type": "string", "enum": [ "image_url" ], "description": "The type of the content part.", "x-stainless-const": true }, "image_url": { "type": "object", "properties": { "url": { "type": "string", "description": "Either a URL of the image or the base64 encoded image data.", "format": "uri" }, "detail": { "type": "string", "description": "Specifies the detail level of the image. Learn more in the [Vision guide](/docs/guides/vision#low-or-high-fidelity-image-understanding).", "enum": [ "auto", "low", "high" ], "default": "auto" } }, "required": [ "url" ] } }, "required": [ "type", "image_url" ] }, { "type": "object", "title": "Audio content part", "description": "Learn about [audio inputs](/docs/guides/audio).\n", "properties": { "type": { "type": "string", "enum": [ "input_audio" ], "description": "The type of the content part. Always `input_audio`.", "x-stainless-const": true }, "input_audio": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64 encoded audio data." }, "format": { "type": "string", "enum": [ "wav", "mp3" ], "description": "The format of the encoded audio data. Currently supports \"wav\" and \"mp3\".\n" } }, "required": [ "data", "format" ] } }, "required": [ "type", "input_audio" ] }, { "type": "object", "title": "File content part", "description": "Learn about [file inputs](/docs/guides/text) for text generation.\n", "properties": { "type": { "type": "string", "enum": [ "file" ], "description": "The type of the content part. Always `file`.", "x-stainless-const": true }, "file": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the file, used when passing the file to the model as a \nstring.\n" }, "file_data": { "type": "string", "description": "The base64 encoded file data, used when passing the file to the model \nas a string.\n" }, "file_id": { "type": "string", "description": "The ID of an uploaded file to use as input.\n" } } } }, "required": [ "type", "file" ] } ] }, "minItems": 1 } ] }, "role": { "type": "string", "enum": [ "user" ], "description": "The role of the messages author, in this case `user`.", "x-stainless-const": true }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } }, "required": [ "content", "role" ] }, { "type": "object", "title": "Assistant message", "description": "Messages sent by the model in response to user messages.\n", "properties": { "content": { "nullable": true, "oneOf": [ { "type": "string", "description": "The contents of the assistant message.", "title": "Text content" }, { "type": "array", "description": "An array of content parts with a defined type. Can be one or more of type `text`, or exactly one of type `refusal`.", "title": "Array of content parts", "items": { "oneOf": [ { "type": "object", "title": "Text content part", "description": "Learn about [text inputs](/docs/guides/text-generation).\n", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part.", "x-stainless-const": true }, "text": { "type": "string", "description": "The text content." } }, "required": [ "type", "text" ] }, { "type": "object", "title": "Refusal content part", "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The type of the content part.", "x-stainless-const": true }, "refusal": { "type": "string", "description": "The refusal message generated by the model." } }, "required": [ "type", "refusal" ] } ] }, "minItems": 1 } ], "description": "The contents of the assistant message. Required unless `tool_calls` or `function_call` is specified.\n" }, "refusal": { "nullable": true, "type": "string", "description": "The refusal message by the assistant." }, "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the messages author, in this case `assistant`.", "x-stainless-const": true }, "name": { "type": "string", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." }, "audio": { "type": "object", "nullable": true, "description": "Data about a previous audio response from the model. \n[Learn more](/docs/guides/audio).\n", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Unique identifier for a previous audio response from the model.\n" } } }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the tool call." }, "type": { "type": "string", "enum": [ "function" ], "description": "The type of the tool. Currently, only `function` is supported.", "x-stainless-const": true }, "function": { "type": "object", "description": "The function that the model called.", "properties": { "name": { "type": "string", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] } }, "function_call": { "type": "object", "deprecated": true, "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.", "nullable": true, "properties": { "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." }, "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "arguments", "name" ] } }, "required": [ "role" ] }, { "type": "object", "title": "Tool message", "properties": { "role": { "type": "string", "enum": [ "tool" ], "description": "The role of the messages author, in this case `tool`.", "x-stainless-const": true }, "content": { "oneOf": [ { "type": "string", "description": "The contents of the tool message.", "title": "Text content" }, { "type": "array", "description": "An array of content parts with a defined type. For tool messages, only type `text` is supported.", "title": "Array of content parts", "items": { "oneOf": [ { "type": "object", "title": "Text content part", "description": "Learn about [text inputs](/docs/guides/text-generation).\n", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part.", "x-stainless-const": true }, "text": { "type": "string", "description": "The text content." } }, "required": [ "type", "text" ] } ] }, "minItems": 1 } ], "description": "The contents of the tool message." }, "tool_call_id": { "type": "string", "description": "Tool call that this message is responding to." } }, "required": [ "role", "content", "tool_call_id" ] }, { "type": "object", "title": "Function message", "deprecated": true, "properties": { "role": { "type": "string", "enum": [ "function" ], "description": "The role of the messages author, in this case `function`.", "x-stainless-const": true }, "content": { "nullable": true, "type": "string", "description": "The contents of the function message." }, "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "role", "content", "name" ] } ] } }, "model": { "example": "openai/gpt-4o-mini", "anyOf": [ { "type": "string" }, { "type": "string" } ], "description": "Model id in `provider/model` form, e.g. `openai/gpt-4o-mini` or `anthropic/claude-3-5-sonnet-latest`. Call `GET /ai/models` for the full list. Bare OpenAI ids like `gpt-4o-mini` are not accepted — always prefix the provider." }, "modalities": { "type": "array", "nullable": true, "description": "Output types that you would like the model to generate.\nMost models are capable of generating text, which is the default:\n\n`[\"text\"]`\n\nThe `gpt-4o-audio-preview` model can also be used to \n[generate audio](/docs/guides/audio). To request that this model generate \nboth text and audio responses, you can use:\n\n`[\"text\", \"audio\"]`\n", "items": { "type": "string", "enum": [ "text", "audio" ] } }, "reasoning_effort": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "nullable": true, "description": "**o-series models only** \n\nConstrains effort on reasoning for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently supported values are `low`, `medium`, and `high`. Reducing\nreasoning effort can result in faster responses and fewer tokens used\non reasoning in a response.\n" }, "max_completion_tokens": { "description": "An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](/docs/guides/reasoning).\n", "type": "integer", "nullable": true }, "frequency_penalty": { "type": "number", "default": 0, "minimum": -2, "maximum": 2, "nullable": true, "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on\ntheir existing frequency in the text so far, decreasing the model's\nlikelihood to repeat the same line verbatim.\n" }, "presence_penalty": { "type": "number", "default": 0, "minimum": -2, "maximum": 2, "nullable": true, "description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on\nwhether they appear in the text so far, increasing the model's likelihood\nto talk about new topics.\n" }, "web_search_options": { "type": "object", "title": "Web search", "description": "This tool searches the web for relevant results to use in a response.\nLearn more about the [web search tool](/docs/guides/tools-web-search?api-mode=chat).\n", "properties": { "user_location": { "type": "object", "nullable": true, "required": [ "type", "approximate" ], "description": "Approximate location parameters for the search.\n", "properties": { "type": { "type": "string", "description": "The type of location approximation. Always `approximate`.\n", "enum": [ "approximate" ], "x-stainless-const": true }, "approximate": { "type": "object", "title": "Web search location", "description": "Approximate location parameters for the search.", "properties": { "country": { "type": "string", "description": "The two-letter \n[ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user,\ne.g. `US`.\n" }, "region": { "type": "string", "description": "Free text input for the region of the user, e.g. `California`.\n" }, "city": { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`.\n" }, "timezone": { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) \nof the user, e.g. `America/Los_Angeles`.\n" } } } } }, "search_context_size": { "type": "string", "description": "High level guidance for the amount of context window space to use for the \nsearch. One of `low`, `medium`, or `high`. `medium` is the default.\n", "enum": [ "low", "medium", "high" ], "default": "medium" } } }, "top_logprobs": { "description": "An integer between 0 and 20 specifying the number of most likely tokens to\nreturn at each token position, each with an associated log probability.\n`logprobs` must be set to `true` if this parameter is used.\n", "type": "integer", "minimum": 0, "maximum": 20, "nullable": true }, "response_format": { "description": "An object specifying the format that the model must output.\n\nSetting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables\nStructured Outputs which ensures the model will match your supplied JSON\nschema. Learn more in the [Structured Outputs\nguide](/docs/guides/structured-outputs).\n\nSetting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which\nensures the message the model generates is valid JSON. Using `json_schema`\nis preferred for models that support it.\n", "oneOf": [ { "type": "object", "title": "Text", "description": "Default response format. Used to generate text responses.\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `text`.", "enum": [ "text" ], "x-stainless-const": true } }, "required": [ "type" ] }, { "type": "object", "title": "JSON schema", "description": "JSON Schema response format. Used to generate structured JSON responses.\nLearn more about [Structured Outputs](/docs/guides/structured-outputs).\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_schema`.", "enum": [ "json_schema" ], "x-stainless-const": true }, "json_schema": { "type": "object", "title": "JSON schema", "description": "Structured Outputs configuration options, including a JSON Schema.\n", "properties": { "description": { "type": "string", "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format.\n" }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.\n" }, "schema": { "type": "object", "title": "JSON schema", "description": "The schema for the response format, described as a JSON Schema object.\nLearn how to build JSON schemas [here](https://json-schema.org/).\n", "additionalProperties": true }, "strict": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`. To learn more, read the [Structured Outputs\nguide](/docs/guides/structured-outputs).\n" } }, "required": [ "name" ] } }, "required": [ "type", "json_schema" ] }, { "type": "object", "title": "JSON object", "description": "JSON object response format. An older method of generating JSON responses.\nUsing `json_schema` is recommended for models that support it. Note that the\nmodel will not generate JSON without a system or user message instructing it\nto do so.\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_object`.", "enum": [ "json_object" ], "x-stainless-const": true } }, "required": [ "type" ] } ] }, "audio": { "type": "object", "nullable": true, "description": "Parameters for audio output. Required when audio output is requested with\n`modalities: [\"audio\"]`. [Learn more](/docs/guides/audio).\n", "required": [ "voice", "format" ], "properties": { "voice": { "example": "ash", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer", "verse" ] } ] }, "format": { "type": "string", "enum": [ "wav", "aac", "mp3", "flac", "opus", "pcm16" ], "description": "Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`,\n`opus`, or `pcm16`.\n" } } }, "store": { "type": "boolean", "default": false, "nullable": true, "description": "Whether or not to store the output of this chat completion request for \nuse in our [model distillation](/docs/guides/distillation) or\n[evals](/docs/guides/evals) products.\n" }, "stream": { "description": "If set to true, the model response data will be streamed to the client\nas it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).\nSee the [Streaming section below](/docs/api-reference/chat/streaming)\nfor more information, along with the [streaming responses](/docs/guides/streaming-responses)\nguide for more information on how to handle the streaming events.\n", "type": "boolean", "nullable": true, "default": false }, "stop": { "description": "Not supported with latest reasoning models `o3` and `o4-mini`.\n\nUp to 4 sequences where the API will stop generating further tokens. The\nreturned text will not contain the stop sequence.\n", "default": null, "nullable": true, "oneOf": [ { "type": "string", "default": "<|endoftext|>", "example": "\n", "nullable": true }, { "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string", "example": "[\"\\n\"]" } } ] }, "logit_bias": { "type": "object", "x-oaiTypeLabel": "map", "default": null, "nullable": true, "additionalProperties": { "type": "integer" }, "description": "Modify the likelihood of specified tokens appearing in the completion.\n\nAccepts a JSON object that maps tokens (specified by their token ID in the\ntokenizer) to an associated bias value from -100 to 100. Mathematically,\nthe bias is added to the logits generated by the model prior to sampling.\nThe exact effect will vary per model, but values between -1 and 1 should\ndecrease or increase likelihood of selection; values like -100 or 100\nshould result in a ban or exclusive selection of the relevant token.\n" }, "logprobs": { "description": "Whether to return log probabilities of the output tokens or not. If true,\nreturns the log probabilities of each output token returned in the\n`content` of `message`.\n", "type": "boolean", "default": false, "nullable": true }, "max_tokens": { "description": "The maximum number of [tokens](/tokenizer) that can be generated in the\nchat completion. This value can be used to control\n[costs](https://openai.com/api/pricing/) for text generated via API.\n\nThis value is now deprecated in favor of `max_completion_tokens`, and is\nnot compatible with [o-series models](/docs/guides/reasoning).\n", "type": "integer", "nullable": true, "deprecated": true }, "n": { "type": "integer", "minimum": 1, "maximum": 128, "default": 1, "example": 1, "nullable": true, "description": "How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs." }, "prediction": { "nullable": true, "description": "Configuration for a [Predicted Output](/docs/guides/predicted-outputs),\nwhich can greatly improve response times when large parts of the model\nresponse are known ahead of time. This is most common when you are\nregenerating a file with only minor changes to most of the content.\n", "oneOf": [ { "type": "object", "title": "Static Content", "description": "Static predicted output content, such as the content of a text file that is\nbeing regenerated.\n", "required": [ "type", "content" ], "properties": { "type": { "type": "string", "enum": [ "content" ], "description": "The type of the predicted content you want to provide. This type is\ncurrently always `content`.\n", "x-stainless-const": true }, "content": { "description": "The content that should be matched when generating a model response.\nIf generated tokens would match this content, the entire model response\ncan be returned much more quickly.\n", "oneOf": [ { "type": "string", "title": "Text content", "description": "The content used for a Predicted Output. This is often the\ntext of a file you are regenerating with minor changes.\n" }, { "type": "array", "description": "An array of content parts with a defined type. Supported options differ based on the [model](/docs/models) being used to generate the response. Can contain text inputs.", "title": "Array of content parts", "items": { "type": "object", "title": "Text content part", "description": "Learn about [text inputs](/docs/guides/text-generation).\n", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "The type of the content part.", "x-stainless-const": true }, "text": { "type": "string", "description": "The text content." } }, "required": [ "type", "text" ] }, "minItems": 1 } ] } } } ] }, "seed": { "type": "integer", "minimum": -9223372036854776000, "maximum": 9223372036854776000, "nullable": true, "description": "This feature is in Beta.\nIf specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.\nDeterminism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.\n", "x-oaiMeta": { "beta": true } }, "stream_options": { "description": "Options for streaming response. Only set this when you set `stream: true`.\n", "type": "object", "nullable": true, "default": null, "properties": { "include_usage": { "type": "boolean", "description": "If set, an additional chunk will be streamed before the `data: [DONE]`\nmessage. The `usage` field on this chunk shows the token usage statistics\nfor the entire request, and the `choices` field will always be an empty\narray. \n\nAll other chunks will also include a `usage` field, but with a null\nvalue. **NOTE:** If the stream is interrupted, you may not receive the\nfinal usage chunk which contains the total token usage for the request.\n" } } }, "tools": { "type": "array", "description": "A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.\n", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the tool. Currently, only `function` is supported.", "x-stainless-const": true }, "function": { "type": "object", "properties": { "description": { "type": "string", "description": "A description of what the function does, used by the model to choose when and how to call the function." }, "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. \n\nOmitting `parameters` defines a function with an empty parameter list.", "additionalProperties": true }, "strict": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](docs/guides/function-calling)." } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } }, "tool_choice": { "description": "Controls which (if any) tool is called by the model.\n`none` means the model will not call any tool and instead generates a message.\n`auto` means the model can pick between generating a message or calling one or more tools.\n`required` means the model must call one or more tools.\nSpecifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool.\n\n`none` is the default when no tools are present. `auto` is the default if tools are present.\n", "oneOf": [ { "type": "string", "description": "`none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.\n", "enum": [ "none", "auto", "required" ] }, { "type": "object", "description": "Specifies a tool the model should use. Use to force the model to call a specific function.", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the tool. Currently, only `function` is supported.", "x-stainless-const": true }, "function": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "name" ] } }, "required": [ "type", "function" ] } ] }, "parallel_tool_calls": { "description": "Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use.", "type": "boolean", "default": true }, "function_call": { "deprecated": true, "description": "Deprecated in favor of `tool_choice`.\n\nControls which (if any) function is called by the model.\n\n`none` means the model will not call a function and instead generates a\nmessage.\n\n`auto` means the model can pick between generating a message or calling a\nfunction.\n\nSpecifying a particular function via `{\"name\": \"my_function\"}` forces the\nmodel to call that function.\n\n`none` is the default when no functions are present. `auto` is the default\nif functions are present.\n", "oneOf": [ { "type": "string", "description": "`none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function.\n", "enum": [ "none", "auto" ] }, { "type": "object", "description": "Specifying a particular function via `{\"name\": \"my_function\"}` forces the model to call that function.\n", "properties": { "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "name" ] } ] }, "functions": { "deprecated": true, "description": "Deprecated in favor of `tools`.\n\nA list of functions the model may generate JSON inputs for.\n", "type": "array", "minItems": 1, "maxItems": 128, "items": { "type": "object", "deprecated": true, "properties": { "description": { "type": "string", "description": "A description of what the function does, used by the model to choose when and how to call the function." }, "name": { "type": "string", "description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." }, "parameters": { "type": "object", "description": "The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. \n\nOmitting `parameters` defines a function with an empty parameter list.", "additionalProperties": true } }, "required": [ "name" ] } } }, "required": [ "model", "messages" ] } ] } } } }, "responses": { "200": { "description": "OpenAI-compatible chat completion", "headers": { "x-kazzle-ai-billing-event-id": { "description": "Kazzle billing event id for this AI request.", "schema": { "type": "string", "pattern": "^airesp_" } } }, "content": { "application/json": { "schema": { "type": "object", "description": "Represents a chat completion response returned by model, based on the provided input.", "properties": { "id": { "type": "string", "description": "A unique identifier for the chat completion." }, "choices": { "type": "array", "description": "A list of chat completion choices. Can be more than one if `n` is greater than 1.", "items": { "type": "object", "required": [ "finish_reason", "index", "message", "logprobs" ], "properties": { "finish_reason": { "type": "string", "description": "The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,\n`length` if the maximum number of tokens specified in the request was reached,\n`content_filter` if content was omitted due to a flag from our content filters,\n`tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.\n", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ] }, "index": { "type": "integer", "description": "The index of the choice in the list of choices." }, "message": { "type": "object", "description": "A chat completion message generated by the model.", "properties": { "content": { "type": "string", "description": "The contents of the message.", "nullable": true }, "refusal": { "type": "string", "description": "The refusal message generated by the model.", "nullable": true }, "tool_calls": { "type": "array", "description": "The tool calls generated by the model, such as function calls.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the tool call." }, "type": { "type": "string", "enum": [ "function" ], "description": "The type of the tool. Currently, only `function` is supported.", "x-stainless-const": true }, "function": { "type": "object", "description": "The function that the model called.", "properties": { "name": { "type": "string", "description": "The name of the function to call." }, "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." } }, "required": [ "name", "arguments" ] } }, "required": [ "id", "type", "function" ] } }, "annotations": { "type": "array", "description": "Annotations for the message, when applicable, as when using the\n[web search tool](/docs/guides/tools-web-search?api-mode=chat).\n", "items": { "type": "object", "description": "A URL citation when using web search.\n", "required": [ "type", "url_citation" ], "properties": { "type": { "type": "string", "description": "The type of the URL citation. Always `url_citation`.", "enum": [ "url_citation" ], "x-stainless-const": true }, "url_citation": { "type": "object", "description": "A URL citation when using web search.", "required": [ "end_index", "start_index", "url", "title" ], "properties": { "end_index": { "type": "integer", "description": "The index of the last character of the URL citation in the message." }, "start_index": { "type": "integer", "description": "The index of the first character of the URL citation in the message." }, "url": { "type": "string", "description": "The URL of the web resource." }, "title": { "type": "string", "description": "The title of the web resource." } } } } } }, "role": { "type": "string", "enum": [ "assistant" ], "description": "The role of the author of this message.", "x-stainless-const": true }, "function_call": { "type": "object", "deprecated": true, "description": "Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.", "properties": { "arguments": { "type": "string", "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." }, "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "name", "arguments" ] }, "audio": { "type": "object", "nullable": true, "description": "If the audio output modality is requested, this object contains data\nabout the audio response from the model. [Learn more](/docs/guides/audio).\n", "required": [ "id", "expires_at", "data", "transcript" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this audio response." }, "expires_at": { "type": "integer", "description": "The Unix timestamp (in seconds) for when this audio response will\nno longer be accessible on the server for use in multi-turn\nconversations.\n" }, "data": { "type": "string", "description": "Base64 encoded audio bytes generated by the model, in the format\nspecified in the request.\n" }, "transcript": { "type": "string", "description": "Transcript of the audio generated by the model." } } } }, "required": [ "role", "content", "refusal" ] }, "logprobs": { "description": "Log probability information for the choice.", "type": "object", "nullable": true, "properties": { "content": { "description": "A list of message content tokens with log probability information.", "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The token.", "type": "string" }, "logprob": { "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.", "type": "number" }, "bytes": { "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "top_logprobs": { "description": "List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.", "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The token.", "type": "string" }, "logprob": { "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.", "type": "number" }, "bytes": { "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.", "type": "array", "items": { "type": "integer" }, "nullable": true } }, "required": [ "token", "logprob", "bytes" ] } } }, "required": [ "token", "logprob", "bytes", "top_logprobs" ] }, "nullable": true }, "refusal": { "description": "A list of message refusal tokens with log probability information.", "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The token.", "type": "string" }, "logprob": { "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.", "type": "number" }, "bytes": { "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.", "type": "array", "items": { "type": "integer" }, "nullable": true }, "top_logprobs": { "description": "List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned.", "type": "array", "items": { "type": "object", "properties": { "token": { "description": "The token.", "type": "string" }, "logprob": { "description": "The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.", "type": "number" }, "bytes": { "description": "A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.", "type": "array", "items": { "type": "integer" }, "nullable": true } }, "required": [ "token", "logprob", "bytes" ] } } }, "required": [ "token", "logprob", "bytes", "top_logprobs" ] }, "nullable": true } }, "required": [ "content", "refusal" ] } } } }, "created": { "type": "integer", "description": "The Unix timestamp (in seconds) of when the chat completion was created." }, "model": { "type": "string", "description": "The model used for the chat completion." }, "service_tier": { "type": "string", "description": "Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:\n - If set to 'auto', and the Project is Scale tier enabled, the system\n will utilize scale tier credits until they are exhausted.\n - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing).\n - When not set, the default behavior is 'auto'.\n\n When this parameter is set, the response body will include the `service_tier` utilized.\n", "enum": [ "auto", "default", "flex" ], "nullable": true, "default": "auto" }, "system_fingerprint": { "type": "string", "description": "This fingerprint represents the backend configuration that the model runs with.\n\nCan be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.\n" }, "object": { "type": "string", "description": "The object type, which is always `chat.completion`.", "enum": [ "chat.completion" ], "x-stainless-const": true }, "usage": { "type": "object", "description": "Usage statistics for the completion request.", "properties": { "completion_tokens": { "type": "integer", "default": 0, "description": "Number of tokens in the generated completion." }, "prompt_tokens": { "type": "integer", "default": 0, "description": "Number of tokens in the prompt." }, "total_tokens": { "type": "integer", "default": 0, "description": "Total number of tokens used in the request (prompt + completion)." }, "completion_tokens_details": { "type": "object", "description": "Breakdown of tokens used in a completion.", "properties": { "accepted_prediction_tokens": { "type": "integer", "default": 0, "description": "When using Predicted Outputs, the number of tokens in the\nprediction that appeared in the completion.\n" }, "audio_tokens": { "type": "integer", "default": 0, "description": "Audio input tokens generated by the model." }, "reasoning_tokens": { "type": "integer", "default": 0, "description": "Tokens generated by the model for reasoning." }, "rejected_prediction_tokens": { "type": "integer", "default": 0, "description": "When using Predicted Outputs, the number of tokens in the\nprediction that did not appear in the completion. However, like\nreasoning tokens, these tokens are still counted in the total\ncompletion tokens for purposes of billing, output, and context window\nlimits.\n" } } }, "prompt_tokens_details": { "type": "object", "description": "Breakdown of tokens used in the prompt.", "properties": { "audio_tokens": { "type": "integer", "default": 0, "description": "Audio input tokens present in the prompt." }, "cached_tokens": { "type": "integer", "default": 0, "description": "Cached tokens present in the prompt." } } } }, "required": [ "prompt_tokens", "completion_tokens", "total_tokens" ] } }, "required": [ "choices", "created", "id", "model", "object" ], "x-oaiMeta": { "name": "The chat completion object", "group": "chat", "example": "{\n \"id\": \"chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG\",\n \"object\": \"chat.completion\",\n \"created\": 1741570283,\n \"model\": \"gpt-4o-2024-08-06\",\n \"choices\": [\n {\n \"index\": 0,\n \"message\": {\n \"role\": \"assistant\",\n \"content\": \"The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.\",\n \"refusal\": null,\n \"annotations\": []\n },\n \"logprobs\": null,\n \"finish_reason\": \"stop\"\n }\n ],\n \"usage\": {\n \"prompt_tokens\": 1117,\n \"completion_tokens\": 46,\n \"total_tokens\": 1163,\n \"prompt_tokens_details\": {\n \"cached_tokens\": 0,\n \"audio_tokens\": 0\n },\n \"completion_tokens_details\": {\n \"reasoning_tokens\": 0,\n \"audio_tokens\": 0,\n \"accepted_prediction_tokens\": 0,\n \"rejected_prediction_tokens\": 0\n }\n },\n \"service_tier\": \"default\",\n \"system_fingerprint\": \"fp_fc9f1d7035\"\n}\n" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } } } }, "/ai/responses": { "post": { "operationId": "postAiResponses", "summary": "OpenAI Responses API", "description": "OpenAI-compatible Responses API. Forwarded to Cloudflare AI Gateway `compat/responses`; Kazzle changes only the path, auth, and billing header. Structured output follows the OpenAI Responses schema (`text.format`); apps must validate parsed model text before mutating app data.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "metadata": { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be\nuseful for storing additional information about the object in a structured\nformat, and querying for objects via API or the dashboard. \n\nKeys are strings with a maximum length of 64 characters. Values are strings\nwith a maximum length of 512 characters.\n", "additionalProperties": { "type": "string" }, "x-oaiTypeLabel": "map", "nullable": true }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1, "example": 1, "nullable": true, "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.\nWe generally recommend altering this or `top_p` but not both.\n" }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "default": 1, "example": 1, "nullable": true, "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability\nmass. So 0.1 means only the tokens comprising the top 10% probability mass\nare considered.\n\nWe generally recommend altering this or `temperature` but not both.\n" }, "user": { "type": "string", "example": "user-1234", "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).\n" }, "service_tier": { "type": "string", "description": "Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:\n - If set to 'auto', and the Project is Scale tier enabled, the system\n will utilize scale tier credits until they are exhausted.\n - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing).\n - When not set, the default behavior is 'auto'.\n\n When this parameter is set, the response body will include the `service_tier` utilized.\n", "enum": [ "auto", "default", "flex" ], "nullable": true, "default": "auto" } } } ] }, { "type": "object", "properties": { "previous_response_id": { "type": "string", "description": "The unique ID of the previous response to the model. Use this to\ncreate multi-turn conversations. Learn more about \n[conversation state](/docs/guides/conversation-state).\n", "nullable": true }, "model": { "example": "openai/gpt-4o-mini", "anyOf": [ { "example": "openai/gpt-4o-mini", "anyOf": [ { "type": "string" }, { "type": "string" } ], "description": "Model id in `provider/model` form, e.g. `openai/gpt-4o-mini` or `anthropic/claude-3-5-sonnet-latest`. Call `GET /ai/models` for the full list. Bare OpenAI ids like `gpt-4o-mini` are not accepted — always prefix the provider." }, { "type": "string", "title": "ResponsesOnlyModel", "enum": [ "o1-pro", "o1-pro-2025-03-19", "computer-use-preview", "computer-use-preview-2025-03-11" ] } ], "description": "Model id in `provider/model` form, e.g. `openai/gpt-4o-mini` or `anthropic/claude-3-5-sonnet-latest`. Call `GET /ai/models` for the full list. Bare OpenAI ids like `gpt-4o-mini` are not accepted — always prefix the provider." }, "reasoning": { "type": "object", "description": "**o-series models only**\n\nConfiguration options for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n", "title": "Reasoning", "properties": { "effort": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "nullable": true, "description": "**o-series models only** \n\nConstrains effort on reasoning for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently supported values are `low`, `medium`, and `high`. Reducing\nreasoning effort can result in faster responses and fewer tokens used\non reasoning in a response.\n" }, "summary": { "type": "string", "description": "A summary of the reasoning performed by the model. This can be\nuseful for debugging and understanding the model's reasoning process.\nOne of `auto`, `concise`, or `detailed`.\n", "enum": [ "auto", "concise", "detailed" ], "nullable": true }, "generate_summary": { "type": "string", "deprecated": true, "description": "**Deprecated:** use `summary` instead.\n\nA summary of the reasoning performed by the model. This can be\nuseful for debugging and understanding the model's reasoning process.\nOne of `auto`, `concise`, or `detailed`.\n", "enum": [ "auto", "concise", "detailed" ], "nullable": true } } }, "max_output_tokens": { "description": "An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning).\n", "type": "integer", "nullable": true }, "instructions": { "type": "string", "description": "Inserts a system (or developer) message as the first item in the model's context.\n\nWhen using along with `previous_response_id`, the instructions from a previous\nresponse will not be carried over to the next response. This makes it simple\nto swap out system (or developer) messages in new responses.\n", "nullable": true }, "text": { "type": "object", "description": "Configuration options for a text response from the model. Can be plain\ntext or structured JSON data. Learn more:\n- [Text inputs and outputs](/docs/guides/text)\n- [Structured Outputs](/docs/guides/structured-outputs)\n", "properties": { "format": { "description": "An object specifying the format that the model must output.\n\nConfiguring `{ \"type\": \"json_schema\" }` enables Structured Outputs, \nwhich ensures the model will match your supplied JSON schema. Learn more in the \n[Structured Outputs guide](/docs/guides/structured-outputs).\n\nThe default format is `{ \"type\": \"text\" }` with no additional options.\n\n**Not recommended for gpt-4o and newer models:**\n\nSetting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which\nensures the message the model generates is valid JSON. Using `json_schema`\nis preferred for models that support it.\n", "oneOf": [ { "type": "object", "title": "Text", "description": "Default response format. Used to generate text responses.\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `text`.", "enum": [ "text" ], "x-stainless-const": true } }, "required": [ "type" ] }, { "type": "object", "title": "JSON schema", "description": "JSON Schema response format. Used to generate structured JSON responses.\nLearn more about [Structured Outputs](/docs/guides/structured-outputs).\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_schema`.", "enum": [ "json_schema" ], "x-stainless-const": true }, "description": { "type": "string", "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format.\n" }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.\n" }, "schema": { "type": "object", "title": "JSON schema", "description": "The schema for the response format, described as a JSON Schema object.\nLearn how to build JSON schemas [here](https://json-schema.org/).\n", "additionalProperties": true }, "strict": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`. To learn more, read the [Structured Outputs\nguide](/docs/guides/structured-outputs).\n" } }, "required": [ "type", "schema", "name" ] }, { "type": "object", "title": "JSON object", "description": "JSON object response format. An older method of generating JSON responses.\nUsing `json_schema` is recommended for models that support it. Note that the\nmodel will not generate JSON without a system or user message instructing it\nto do so.\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_object`.", "enum": [ "json_object" ], "x-stainless-const": true } }, "required": [ "type" ] } ] } } }, "tools": { "type": "array", "description": "An array of tools the model may call while generating a response. You \ncan specify which tool to use by setting the `tool_choice` parameter.\n\nThe two categories of tools you can provide the model are:\n\n- **Built-in tools**: Tools that are provided by OpenAI that extend the\n model's capabilities, like [web search](/docs/guides/tools-web-search)\n or [file search](/docs/guides/tools-file-search). Learn more about\n [built-in tools](/docs/guides/tools).\n- **Function calls (custom tools)**: Functions that are defined by you,\n enabling the model to call your own code. Learn more about\n [function calling](/docs/guides/function-calling).\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "file_search" ], "description": "The type of the file search tool. Always `file_search`.", "default": "file_search", "x-stainless-const": true }, "vector_store_ids": { "items": { "type": "string" }, "type": "array", "description": "The IDs of the vector stores to search." }, "max_num_results": { "type": "integer", "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive." }, "ranking_options": { "properties": { "ranker": { "type": "string", "enum": [ "auto", "default-2024-11-15" ], "description": "The ranker to use for the file search." }, "score_threshold": { "type": "number", "description": "The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results." } }, "type": "object", "required": [] }, "filters": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": false, "title": "Comparison Filter", "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.\n", "properties": { "type": { "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n" }, "key": { "type": "string", "description": "The key to compare against the value." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against the attribute key; supports string, number, or boolean types." } }, "required": [ "type", "key", "value" ], "x-oaiMeta": { "name": "ComparisonFilter" } }, { "$recursiveAnchor": true, "type": "object", "additionalProperties": false, "title": "Compound Filter", "description": "Combine multiple filters using `and` or `or`.", "properties": { "type": { "type": "string", "description": "Type of operation: `and` or `or`.", "enum": [ "and", "or" ] }, "filters": { "type": "array", "description": "Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "title": "Comparison Filter", "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.\n", "properties": { "type": { "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n" }, "key": { "type": "string", "description": "The key to compare against the value." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against the attribute key; supports string, number, or boolean types." } }, "required": [ "type", "key", "value" ], "x-oaiMeta": { "name": "ComparisonFilter" } }, { "$recursiveRef": "#" } ] } } }, "required": [ "type", "filters" ], "x-oaiMeta": { "name": "CompoundFilter" } } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "vector_store_ids" ], "title": "File search", "description": "A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search)." }, { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the function tool. Always `function`.", "default": "function", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the function to call." }, "description": { "anyOf": [ { "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, { "type": "null" } ] }, "strict": { "anyOf": [ { "type": "boolean", "description": "Whether to enforce strict parameter validation. Default `true`." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name", "strict", "parameters" ], "title": "Function", "description": "Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling)." }, { "properties": { "type": { "type": "string", "enum": [ "web_search_preview", "web_search_preview_2025_03_11" ], "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.", "default": "web_search_preview", "x-stainless-const": true }, "user_location": { "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always `approximate`.", "default": "approximate", "x-stainless-const": true }, "country": { "anyOf": [ { "type": "string", "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "description": "Free text input for the region of the user, e.g. `California`." }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ] }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default." } }, "type": "object", "required": [ "type" ], "title": "Web search preview", "description": "This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search)." }, { "properties": { "type": { "type": "string", "enum": [ "computer_use_preview" ], "description": "The type of the computer use tool. Always `computer_use_preview`.", "default": "computer_use_preview", "x-stainless-const": true }, "environment": { "type": "string", "enum": [ "windows", "mac", "linux", "ubuntu", "browser" ], "description": "The type of computer environment to control." }, "display_width": { "type": "integer", "description": "The width of the computer display." }, "display_height": { "type": "integer", "description": "The height of the computer display." } }, "type": "object", "required": [ "type", "environment", "display_width", "display_height" ], "title": "Computer use preview", "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use)." } ], "discriminator": { "propertyName": "type" } } }, "tool_choice": { "description": "How the model should select which tool (or tools) to use when generating\na response. See the `tools` parameter to see how to specify which tools\nthe model can call.\n", "oneOf": [ { "type": "string", "title": "Tool choice mode", "description": "Controls which (if any) tool is called by the model.\n\n`none` means the model will not call any tool and instead generates a message.\n\n`auto` means the model can pick between generating a message or calling one or\nmore tools.\n\n`required` means the model must call one or more tools.\n", "enum": [ "none", "auto", "required" ] }, { "type": "object", "title": "Hosted tool", "description": "Indicates that the model should use a built-in tool to generate a response.\n[Learn more about built-in tools](/docs/guides/tools).\n", "properties": { "type": { "type": "string", "description": "The type of hosted tool the model should to use. Learn more about\n[built-in tools](/docs/guides/tools).\n\nAllowed values are:\n- `file_search`\n- `web_search_preview`\n- `computer_use_preview`\n", "enum": [ "file_search", "web_search_preview", "computer_use_preview", "web_search_preview_2025_03_11" ] } }, "required": [ "type" ] }, { "type": "object", "title": "Function tool", "description": "Use this option to force the model to call a specific function.\n", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "For function calling, the type is always `function`.", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "type", "name" ] } ] }, "truncation": { "type": "string", "description": "The truncation strategy to use for the model response.\n- `auto`: If the context of this response and previous ones exceeds\n the model's context window size, the model will truncate the \n response to fit the context window by dropping input items in the\n middle of the conversation. \n- `disabled` (default): If a model response will exceed the context window \n size for a model, the request will fail with a 400 error.\n", "enum": [ "auto", "disabled" ], "nullable": true, "default": "disabled" } } }, { "type": "object", "properties": { "input": { "description": "Text, image, or file inputs to the model, used to generate a response.\n\nLearn more:\n- [Text inputs and outputs](/docs/guides/text)\n- [Image inputs](/docs/guides/images)\n- [File inputs](/docs/guides/pdf-files)\n- [Conversation state](/docs/guides/conversation-state)\n- [Function calling](/docs/guides/function-calling)\n", "oneOf": [ { "type": "string", "title": "Text input", "description": "A text input to the model, equivalent to a text input with the \n`user` role.\n" }, { "type": "array", "title": "Input item list", "description": "A list of one or many input items to the model, containing \ndifferent content types.\n", "items": { "oneOf": [ { "type": "object", "title": "Input message", "description": "A message input to the model with a role indicating instruction following\nhierarchy. Instructions given with the `developer` or `system` role take\nprecedence over instructions given with the `user` role. Messages with the\n`assistant` role are presumed to have been generated by the model in previous\ninteractions.\n", "properties": { "role": { "type": "string", "description": "The role of the message input. One of `user`, `assistant`, `system`, or\n`developer`.\n", "enum": [ "user", "assistant", "system", "developer" ] }, "content": { "description": "Text, image, or audio input to the model, used to generate a response.\nCan also contain previous assistant responses.\n", "oneOf": [ { "type": "string", "title": "Text input", "description": "A text input to the model.\n" }, { "type": "array", "title": "Input item content list", "description": "A list of one or many input items to the model, containing different content \ntypes.\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text", "x-stainless-const": true }, "text": { "type": "string", "description": "The text input to the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model." }, { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image", "x-stainless-const": true }, "image_url": { "anyOf": [ { "type": "string", "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "type": "null" } ] }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model." }, { "type": "null" } ] }, "detail": { "type": "string", "enum": [ "low", "high", "auto" ], "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." } }, "type": "object", "required": [ "type", "detail" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](/docs/guides/vision)." }, { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file", "x-stainless-const": true }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model." }, { "type": "null" } ] }, "filename": { "type": "string", "description": "The name of the file to be sent to the model." }, "file_data": { "type": "string", "description": "The content of the file to be sent to the model.\n" } }, "type": "object", "required": [ "type" ], "title": "Input file", "description": "A file input to the model." } ] } } ] }, "type": { "type": "string", "description": "The type of the message input. Always `message`.\n", "enum": [ "message" ], "x-stainless-const": true } }, "required": [ "role", "content" ] }, { "type": "object", "description": "Content item used to generate a response.\n", "oneOf": [ { "type": "object", "title": "Input message", "description": "A message input to the model with a role indicating instruction following\nhierarchy. Instructions given with the `developer` or `system` role take\nprecedence over instructions given with the `user` role.\n", "properties": { "type": { "type": "string", "description": "The type of the message input. Always set to `message`.\n", "enum": [ "message" ], "x-stainless-const": true }, "role": { "type": "string", "description": "The role of the message input. One of `user`, `system`, or `developer`.\n", "enum": [ "user", "system", "developer" ] }, "status": { "type": "string", "description": "The status of item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] }, "content": { "type": "array", "title": "Input item content list", "description": "A list of one or many input items to the model, containing different content \ntypes.\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "input_text" ], "description": "The type of the input item. Always `input_text`.", "default": "input_text", "x-stainless-const": true }, "text": { "type": "string", "description": "The text input to the model." } }, "type": "object", "required": [ "type", "text" ], "title": "Input text", "description": "A text input to the model." }, { "properties": { "type": { "type": "string", "enum": [ "input_image" ], "description": "The type of the input item. Always `input_image`.", "default": "input_image", "x-stainless-const": true }, "image_url": { "anyOf": [ { "type": "string", "description": "The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL." }, { "type": "null" } ] }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model." }, { "type": "null" } ] }, "detail": { "type": "string", "enum": [ "low", "high", "auto" ], "description": "The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`." } }, "type": "object", "required": [ "type", "detail" ], "title": "Input image", "description": "An image input to the model. Learn about [image inputs](/docs/guides/vision)." }, { "properties": { "type": { "type": "string", "enum": [ "input_file" ], "description": "The type of the input item. Always `input_file`.", "default": "input_file", "x-stainless-const": true }, "file_id": { "anyOf": [ { "type": "string", "description": "The ID of the file to be sent to the model." }, { "type": "null" } ] }, "filename": { "type": "string", "description": "The name of the file to be sent to the model." }, "file_data": { "type": "string", "description": "The content of the file to be sent to the model.\n" } }, "type": "object", "required": [ "type" ], "title": "Input file", "description": "A file input to the model." } ] } } }, "required": [ "role", "content" ] }, { "type": "object", "title": "Output message", "description": "An output message from the model.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the output message.\n" }, "type": { "type": "string", "description": "The type of the output message. Always `message`.\n", "enum": [ "message" ], "x-stainless-const": true }, "role": { "type": "string", "description": "The role of the output message. Always `assistant`.\n", "enum": [ "assistant" ], "x-stainless-const": true }, "content": { "type": "array", "description": "The content of the output message.\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "output_text" ], "description": "The type of the output text. Always `output_text`.", "default": "output_text", "x-stainless-const": true }, "text": { "type": "string", "description": "The text output from the model." }, "annotations": { "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "file_citation" ], "description": "The type of the file citation. Always `file_citation`.", "default": "file_citation", "x-stainless-const": true }, "file_id": { "type": "string", "description": "The ID of the file." }, "index": { "type": "integer", "description": "The index of the file in the list of files." } }, "type": "object", "required": [ "type", "file_id", "index" ], "title": "File citation", "description": "A citation to a file." }, { "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The type of the URL citation. Always `url_citation`.", "default": "url_citation", "x-stainless-const": true }, "url": { "type": "string", "description": "The URL of the web resource." }, "start_index": { "type": "integer", "description": "The index of the first character of the URL citation in the message." }, "end_index": { "type": "integer", "description": "The index of the last character of the URL citation in the message." }, "title": { "type": "string", "description": "The title of the web resource." } }, "type": "object", "required": [ "type", "url", "start_index", "end_index", "title" ], "title": "URL citation", "description": "A citation for a web resource used to generate a model response." }, { "type": "object", "title": "File path", "description": "A path to a file.\n", "properties": { "type": { "type": "string", "description": "The type of the file path. Always `file_path`.\n", "enum": [ "file_path" ], "x-stainless-const": true }, "file_id": { "type": "string", "description": "The ID of the file.\n" }, "index": { "type": "integer", "description": "The index of the file in the list of files.\n" } }, "required": [ "type", "file_id", "index" ] } ], "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The annotations of the text output." } }, "type": "object", "required": [ "type", "text", "annotations" ], "title": "Output text", "description": "A text output from the model." }, { "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The type of the refusal. Always `refusal`.", "default": "refusal", "x-stainless-const": true }, "refusal": { "type": "string", "description": "The refusal explanationfrom the model." } }, "type": "object", "required": [ "type", "refusal" ], "title": "Refusal", "description": "A refusal from the model." } ] } }, "status": { "type": "string", "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "id", "type", "role", "content", "status" ] }, { "type": "object", "title": "File search tool call", "description": "The results of a file search tool call. See the \n[file search guide](/docs/guides/tools-file-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the file search tool call.\n" }, "type": { "type": "string", "enum": [ "file_search_call" ], "description": "The type of the file search tool call. Always `file_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "description": "The status of the file search tool call. One of `in_progress`, \n`searching`, `incomplete` or `failed`,\n", "enum": [ "in_progress", "searching", "completed", "incomplete", "failed" ] }, "queries": { "type": "array", "items": { "type": "string" }, "description": "The queries used to search for files.\n" }, "results": { "type": "array", "description": "The results of the file search tool call.\n", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The unique ID of the file.\n" }, "text": { "type": "string", "description": "The text that was retrieved from the file.\n" }, "filename": { "type": "string", "description": "The name of the file.\n" }, "attributes": { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be \nuseful for storing additional information about the object in a structured \nformat, and querying for objects via API or the dashboard. Keys are strings \nwith a maximum length of 64 characters. Values are strings with a maximum \nlength of 512 characters, booleans, or numbers.\n", "maxProperties": 16, "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" } ] }, "x-oaiTypeLabel": "map", "nullable": true }, "score": { "type": "number", "format": "float", "description": "The relevance score of the file - a value between 0 and 1.\n" } } }, "nullable": true } }, "required": [ "id", "type", "status", "queries" ] }, { "type": "object", "title": "Computer tool call", "description": "A tool call to a computer use tool. See the \n[computer use guide](/docs/guides/tools-computer-use) for more information.\n", "properties": { "type": { "type": "string", "description": "The type of the computer call. Always `computer_call`.", "enum": [ "computer_call" ], "default": "computer_call" }, "id": { "type": "string", "description": "The unique ID of the computer call." }, "call_id": { "type": "string", "description": "An identifier used when responding to the tool call with output.\n" }, "action": { "oneOf": [ { "type": "object", "title": "Click", "description": "A click action.\n", "properties": { "type": { "type": "string", "enum": [ "click" ], "default": "click", "description": "Specifies the event type. For a click action, this property is \nalways set to `click`.\n", "x-stainless-const": true }, "button": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ], "description": "Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.\n" }, "x": { "type": "integer", "description": "The x-coordinate where the click occurred.\n" }, "y": { "type": "integer", "description": "The y-coordinate where the click occurred.\n" } }, "required": [ "type", "button", "x", "y" ] }, { "type": "object", "title": "DoubleClick", "description": "A double click action.\n", "properties": { "type": { "type": "string", "enum": [ "double_click" ], "default": "double_click", "description": "Specifies the event type. For a double click action, this property is \nalways set to `double_click`.\n", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the double click occurred.\n" }, "y": { "type": "integer", "description": "The y-coordinate where the double click occurred.\n" } }, "required": [ "type", "x", "y" ] }, { "type": "object", "title": "Drag", "description": "A drag action.\n", "properties": { "type": { "type": "string", "enum": [ "drag" ], "default": "drag", "description": "Specifies the event type. For a drag action, this property is \nalways set to `drag`.\n", "x-stainless-const": true }, "path": { "type": "array", "description": "An array of coordinates representing the path of the drag action. Coordinates will appear as an array\nof objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```\n", "items": { "type": "object", "title": "Coordinate", "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.\n", "properties": { "x": { "type": "integer", "description": "The x-coordinate.\n" }, "y": { "type": "integer", "description": "The y-coordinate.\n" } }, "required": [ "x", "y" ] } } }, "required": [ "type", "path" ] }, { "type": "object", "title": "KeyPress", "description": "A collection of keypresses the model would like to perform.\n", "properties": { "type": { "type": "string", "enum": [ "keypress" ], "default": "keypress", "description": "Specifies the event type. For a keypress action, this property is \nalways set to `keypress`.\n", "x-stainless-const": true }, "keys": { "type": "array", "items": { "type": "string", "description": "One of the keys the model is requesting to be pressed.\n" }, "description": "The combination of keys the model is requesting to be pressed. This is an\narray of strings, each representing a key.\n" } }, "required": [ "type", "keys" ] }, { "type": "object", "title": "Move", "description": "A mouse move action.\n", "properties": { "type": { "type": "string", "enum": [ "move" ], "default": "move", "description": "Specifies the event type. For a move action, this property is \nalways set to `move`.\n", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate to move to.\n" }, "y": { "type": "integer", "description": "The y-coordinate to move to.\n" } }, "required": [ "type", "x", "y" ] }, { "type": "object", "title": "Screenshot", "description": "A screenshot action.\n", "properties": { "type": { "type": "string", "enum": [ "screenshot" ], "default": "screenshot", "description": "Specifies the event type. For a screenshot action, this property is \nalways set to `screenshot`.\n", "x-stainless-const": true } }, "required": [ "type" ] }, { "type": "object", "title": "Scroll", "description": "A scroll action.\n", "properties": { "type": { "type": "string", "enum": [ "scroll" ], "default": "scroll", "description": "Specifies the event type. For a scroll action, this property is \nalways set to `scroll`.\n", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the scroll occurred.\n" }, "y": { "type": "integer", "description": "The y-coordinate where the scroll occurred.\n" }, "scroll_x": { "type": "integer", "description": "The horizontal scroll distance.\n" }, "scroll_y": { "type": "integer", "description": "The vertical scroll distance.\n" } }, "required": [ "type", "x", "y", "scroll_x", "scroll_y" ] }, { "type": "object", "title": "Type", "description": "An action to type in text.\n", "properties": { "type": { "type": "string", "enum": [ "type" ], "default": "type", "description": "Specifies the event type. For a type action, this property is \nalways set to `type`.\n", "x-stainless-const": true }, "text": { "type": "string", "description": "The text to type.\n" } }, "required": [ "type", "text" ] }, { "type": "object", "title": "Wait", "description": "A wait action.\n", "properties": { "type": { "type": "string", "enum": [ "wait" ], "default": "wait", "description": "Specifies the event type. For a wait action, this property is \nalways set to `wait`.\n", "x-stainless-const": true } }, "required": [ "type" ] } ] }, "pending_safety_checks": { "type": "array", "items": { "type": "object", "description": "A pending safety check for the computer call.\n", "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "type": "string", "description": "The type of the pending safety check." }, "message": { "type": "string", "description": "Details about the pending safety check." } }, "required": [ "id", "code", "message" ] }, "description": "The pending safety checks for the computer call.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "id", "action", "call_id", "pending_safety_checks", "status" ] }, { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The ID of the computer tool call output." }, { "type": "null" } ] }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The ID of the computer tool call that produced the output." }, "type": { "type": "string", "enum": [ "computer_call_output" ], "description": "The type of the computer tool call output. Always `computer_call_output`.", "default": "computer_call_output", "x-stainless-const": true }, "output": { "type": "object", "description": "A computer screenshot image used with the computer use tool.\n", "properties": { "type": { "type": "string", "enum": [ "computer_screenshot" ], "default": "computer_screenshot", "description": "Specifies the event type. For a computer screenshot, this property is \nalways set to `computer_screenshot`.\n", "x-stainless-const": true }, "image_url": { "type": "string", "description": "The URL of the screenshot image." }, "file_id": { "type": "string", "description": "The identifier of an uploaded file that contains the screenshot." } }, "required": [ "type" ] }, "acknowledged_safety_checks": { "anyOf": [ { "items": { "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "anyOf": [ { "type": "string", "description": "The type of the pending safety check." }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "description": "Details about the pending safety check." }, { "type": "null" } ] } }, "type": "object", "required": [ "id" ], "description": "A pending safety check for the computer call." }, "type": "array", "description": "The safety checks reported by the API that have been acknowledged by the developer." }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "description": "The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API." }, { "type": "null" } ] } }, "type": "object", "required": [ "call_id", "type", "output" ], "title": "Computer tool call output", "description": "The output of a computer tool call." }, { "type": "object", "title": "Web search tool call", "description": "The results of a web search tool call. See the \n[web search guide](/docs/guides/tools-web-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the web search tool call.\n" }, "type": { "type": "string", "enum": [ "web_search_call" ], "description": "The type of the web search tool call. Always `web_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "description": "The status of the web search tool call.\n", "enum": [ "in_progress", "searching", "completed", "failed" ] } }, "required": [ "id", "type", "status" ] }, { "type": "object", "title": "Function tool call", "description": "A tool call to run a function. See the \n[function calling guide](/docs/guides/function-calling) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the function tool call.\n" }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the function tool call. Always `function_call`.\n", "x-stainless-const": true }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model.\n" }, "name": { "type": "string", "description": "The name of the function to run.\n" }, "arguments": { "type": "string", "description": "A JSON string of the arguments to pass to the function.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "call_id", "name", "arguments" ] }, { "properties": { "id": { "anyOf": [ { "type": "string", "description": "The unique ID of the function tool call output. Populated when this item is returned via API." }, { "type": "null" } ] }, "call_id": { "type": "string", "maxLength": 64, "minLength": 1, "description": "The unique ID of the function tool call generated by the model." }, "type": { "type": "string", "enum": [ "function_call_output" ], "description": "The type of the function tool call output. Always `function_call_output`.", "default": "function_call_output", "x-stainless-const": true }, "output": { "type": "string", "maxLength": 10485760, "description": "A JSON string of the output of the function tool call." }, "status": { "anyOf": [ { "type": "string", "enum": [ "in_progress", "completed", "incomplete" ], "description": "The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API." }, { "type": "null" } ] } }, "type": "object", "required": [ "call_id", "type", "output" ], "title": "Function tool call output", "description": "The output of a function tool call." }, { "type": "object", "description": "A description of the chain of thought used by a reasoning model while generating\na response.\n", "title": "Reasoning", "properties": { "type": { "type": "string", "description": "The type of the object. Always `reasoning`.\n", "enum": [ "reasoning" ], "x-stainless-const": true }, "id": { "type": "string", "description": "The unique identifier of the reasoning content.\n" }, "summary": { "type": "array", "description": "Reasoning text contents.\n", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the object. Always `summary_text`.\n", "enum": [ "summary_text" ], "x-stainless-const": true }, "text": { "type": "string", "description": "A short summary of the reasoning used by the model when generating\nthe response.\n" } }, "required": [ "type", "text" ] } }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "id", "summary", "type" ] } ], "discriminator": { "propertyName": "type" } }, { "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "item_reference" ], "description": "The type of item to reference. Always `item_reference`.", "default": "item_reference", "x-stainless-const": true }, { "type": "null" } ] }, "id": { "type": "string", "description": "The ID of the item to reference." } }, "type": "object", "required": [ "id" ], "title": "Item reference", "description": "An internal identifier for an item to reference." } ], "discriminator": { "propertyName": "type" } } } ] }, "include": { "type": "array", "description": "Specify additional output data to include in the model response. Currently\nsupported values are:\n- `file_search_call.results`: Include the search results of\n the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n", "items": { "type": "string", "description": "Specify additional output data to include in the model response. Currently\nsupported values are:\n- `file_search_call.results`: Include the search results of\n the file search tool call.\n- `message.input_image.image_url`: Include image urls from the input message.\n- `computer_call_output.output.image_url`: Include image urls from the computer call output.\n", "enum": [ "file_search_call.results", "message.input_image.image_url", "computer_call_output.output.image_url" ] }, "nullable": true }, "parallel_tool_calls": { "type": "boolean", "description": "Whether to allow the model to run tool calls in parallel.\n", "default": true, "nullable": true }, "store": { "type": "boolean", "description": "Whether to store the generated model response for later retrieval via\nAPI.\n", "default": true, "nullable": true }, "stream": { "description": "If set to true, the model response data will be streamed to the client\nas it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).\nSee the [Streaming section below](/docs/api-reference/responses-streaming)\nfor more information.\n", "type": "boolean", "nullable": true, "default": false } }, "required": [ "model", "input" ] } ] } } } }, "responses": { "200": { "description": "OpenAI-compatible response", "headers": { "x-kazzle-ai-billing-event-id": { "description": "Kazzle billing event id for this AI request.", "schema": { "type": "string", "pattern": "^airesp_" } } }, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "metadata": { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be\nuseful for storing additional information about the object in a structured\nformat, and querying for objects via API or the dashboard. \n\nKeys are strings with a maximum length of 64 characters. Values are strings\nwith a maximum length of 512 characters.\n", "additionalProperties": { "type": "string" }, "x-oaiTypeLabel": "map", "nullable": true }, "temperature": { "type": "number", "minimum": 0, "maximum": 2, "default": 1, "example": 1, "nullable": true, "description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.\nWe generally recommend altering this or `top_p` but not both.\n" }, "top_p": { "type": "number", "minimum": 0, "maximum": 1, "default": 1, "example": 1, "nullable": true, "description": "An alternative to sampling with temperature, called nucleus sampling,\nwhere the model considers the results of the tokens with top_p probability\nmass. So 0.1 means only the tokens comprising the top 10% probability mass\nare considered.\n\nWe generally recommend altering this or `temperature` but not both.\n" }, "user": { "type": "string", "example": "user-1234", "description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).\n" }, "service_tier": { "type": "string", "description": "Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:\n - If set to 'auto', and the Project is Scale tier enabled, the system\n will utilize scale tier credits until they are exhausted.\n - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.\n - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing).\n - When not set, the default behavior is 'auto'.\n\n When this parameter is set, the response body will include the `service_tier` utilized.\n", "enum": [ "auto", "default", "flex" ], "nullable": true, "default": "auto" } } }, { "type": "object", "properties": { "previous_response_id": { "type": "string", "description": "The unique ID of the previous response to the model. Use this to\ncreate multi-turn conversations. Learn more about \n[conversation state](/docs/guides/conversation-state).\n", "nullable": true }, "model": { "example": "gpt-4o", "anyOf": [ { "example": "gpt-4o", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano", "gpt-4.1-2025-04-14", "gpt-4.1-mini-2025-04-14", "gpt-4.1-nano-2025-04-14", "o4-mini", "o4-mini-2025-04-16", "o3", "o3-2025-04-16", "o3-mini", "o3-mini-2025-01-31", "o1", "o1-2024-12-17", "o1-preview", "o1-preview-2024-09-12", "o1-mini", "o1-mini-2024-09-12", "gpt-4o", "gpt-4o-2024-11-20", "gpt-4o-2024-08-06", "gpt-4o-2024-05-13", "gpt-4o-audio-preview", "gpt-4o-audio-preview-2024-10-01", "gpt-4o-audio-preview-2024-12-17", "gpt-4o-mini-audio-preview", "gpt-4o-mini-audio-preview-2024-12-17", "gpt-4o-search-preview", "gpt-4o-mini-search-preview", "gpt-4o-search-preview-2025-03-11", "gpt-4o-mini-search-preview-2025-03-11", "chatgpt-4o-latest", "gpt-4o-mini", "gpt-4o-mini-2024-07-18", "gpt-4-turbo", "gpt-4-turbo-2024-04-09", "gpt-4-0125-preview", "gpt-4-turbo-preview", "gpt-4-1106-preview", "gpt-4-vision-preview", "gpt-4", "gpt-4-0314", "gpt-4-0613", "gpt-4-32k", "gpt-4-32k-0314", "gpt-4-32k-0613", "gpt-3.5-turbo", "gpt-3.5-turbo-16k", "gpt-3.5-turbo-0301", "gpt-3.5-turbo-0613", "gpt-3.5-turbo-1106", "gpt-3.5-turbo-0125", "gpt-3.5-turbo-16k-0613" ] } ] }, { "type": "string", "title": "ResponsesOnlyModel", "enum": [ "o1-pro", "o1-pro-2025-03-19", "computer-use-preview", "computer-use-preview-2025-03-11" ] } ] }, "reasoning": { "type": "object", "description": "**o-series models only**\n\nConfiguration options for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\n", "title": "Reasoning", "properties": { "effort": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "nullable": true, "description": "**o-series models only** \n\nConstrains effort on reasoning for \n[reasoning models](https://platform.openai.com/docs/guides/reasoning).\nCurrently supported values are `low`, `medium`, and `high`. Reducing\nreasoning effort can result in faster responses and fewer tokens used\non reasoning in a response.\n" }, "summary": { "type": "string", "description": "A summary of the reasoning performed by the model. This can be\nuseful for debugging and understanding the model's reasoning process.\nOne of `auto`, `concise`, or `detailed`.\n", "enum": [ "auto", "concise", "detailed" ], "nullable": true }, "generate_summary": { "type": "string", "deprecated": true, "description": "**Deprecated:** use `summary` instead.\n\nA summary of the reasoning performed by the model. This can be\nuseful for debugging and understanding the model's reasoning process.\nOne of `auto`, `concise`, or `detailed`.\n", "enum": [ "auto", "concise", "detailed" ], "nullable": true } } }, "max_output_tokens": { "description": "An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning).\n", "type": "integer", "nullable": true }, "instructions": { "type": "string", "description": "Inserts a system (or developer) message as the first item in the model's context.\n\nWhen using along with `previous_response_id`, the instructions from a previous\nresponse will not be carried over to the next response. This makes it simple\nto swap out system (or developer) messages in new responses.\n", "nullable": true }, "text": { "type": "object", "description": "Configuration options for a text response from the model. Can be plain\ntext or structured JSON data. Learn more:\n- [Text inputs and outputs](/docs/guides/text)\n- [Structured Outputs](/docs/guides/structured-outputs)\n", "properties": { "format": { "description": "An object specifying the format that the model must output.\n\nConfiguring `{ \"type\": \"json_schema\" }` enables Structured Outputs, \nwhich ensures the model will match your supplied JSON schema. Learn more in the \n[Structured Outputs guide](/docs/guides/structured-outputs).\n\nThe default format is `{ \"type\": \"text\" }` with no additional options.\n\n**Not recommended for gpt-4o and newer models:**\n\nSetting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which\nensures the message the model generates is valid JSON. Using `json_schema`\nis preferred for models that support it.\n", "oneOf": [ { "type": "object", "title": "Text", "description": "Default response format. Used to generate text responses.\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `text`.", "enum": [ "text" ], "x-stainless-const": true } }, "required": [ "type" ] }, { "type": "object", "title": "JSON schema", "description": "JSON Schema response format. Used to generate structured JSON responses.\nLearn more about [Structured Outputs](/docs/guides/structured-outputs).\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_schema`.", "enum": [ "json_schema" ], "x-stainless-const": true }, "description": { "type": "string", "description": "A description of what the response format is for, used by the model to\ndetermine how to respond in the format.\n" }, "name": { "type": "string", "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain\nunderscores and dashes, with a maximum length of 64.\n" }, "schema": { "type": "object", "title": "JSON schema", "description": "The schema for the response format, described as a JSON Schema object.\nLearn how to build JSON schemas [here](https://json-schema.org/).\n", "additionalProperties": true }, "strict": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined\nin the `schema` field. Only a subset of JSON Schema is supported when\n`strict` is `true`. To learn more, read the [Structured Outputs\nguide](/docs/guides/structured-outputs).\n" } }, "required": [ "type", "schema", "name" ] }, { "type": "object", "title": "JSON object", "description": "JSON object response format. An older method of generating JSON responses.\nUsing `json_schema` is recommended for models that support it. Note that the\nmodel will not generate JSON without a system or user message instructing it\nto do so.\n", "properties": { "type": { "type": "string", "description": "The type of response format being defined. Always `json_object`.", "enum": [ "json_object" ], "x-stainless-const": true } }, "required": [ "type" ] } ] } } }, "tools": { "type": "array", "description": "An array of tools the model may call while generating a response. You \ncan specify which tool to use by setting the `tool_choice` parameter.\n\nThe two categories of tools you can provide the model are:\n\n- **Built-in tools**: Tools that are provided by OpenAI that extend the\n model's capabilities, like [web search](/docs/guides/tools-web-search)\n or [file search](/docs/guides/tools-file-search). Learn more about\n [built-in tools](/docs/guides/tools).\n- **Function calls (custom tools)**: Functions that are defined by you,\n enabling the model to call your own code. Learn more about\n [function calling](/docs/guides/function-calling).\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "file_search" ], "description": "The type of the file search tool. Always `file_search`.", "default": "file_search", "x-stainless-const": true }, "vector_store_ids": { "items": { "type": "string" }, "type": "array", "description": "The IDs of the vector stores to search." }, "max_num_results": { "type": "integer", "description": "The maximum number of results to return. This number should be between 1 and 50 inclusive." }, "ranking_options": { "properties": { "ranker": { "type": "string", "enum": [ "auto", "default-2024-11-15" ], "description": "The ranker to use for the file search." }, "score_threshold": { "type": "number", "description": "The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results." } }, "type": "object", "required": [] }, "filters": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": false, "title": "Comparison Filter", "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.\n", "properties": { "type": { "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n" }, "key": { "type": "string", "description": "The key to compare against the value." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against the attribute key; supports string, number, or boolean types." } }, "required": [ "type", "key", "value" ], "x-oaiMeta": { "name": "ComparisonFilter" } }, { "$recursiveAnchor": true, "type": "object", "additionalProperties": false, "title": "Compound Filter", "description": "Combine multiple filters using `and` or `or`.", "properties": { "type": { "type": "string", "description": "Type of operation: `and` or `or`.", "enum": [ "and", "or" ] }, "filters": { "type": "array", "description": "Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "title": "Comparison Filter", "description": "A filter used to compare a specified attribute key to a given value using a defined comparison operation.\n", "properties": { "type": { "type": "string", "default": "eq", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "description": "Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`.\n- `eq`: equals\n- `ne`: not equal\n- `gt`: greater than\n- `gte`: greater than or equal\n- `lt`: less than\n- `lte`: less than or equal\n" }, "key": { "type": "string", "description": "The key to compare against the value." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "The value to compare against the attribute key; supports string, number, or boolean types." } }, "required": [ "type", "key", "value" ], "x-oaiMeta": { "name": "ComparisonFilter" } }, { "$recursiveRef": "#" } ] } } }, "required": [ "type", "filters" ], "x-oaiMeta": { "name": "CompoundFilter" } } ] }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "vector_store_ids" ], "title": "File search", "description": "A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search)." }, { "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "The type of the function tool. Always `function`.", "default": "function", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the function to call." }, "description": { "anyOf": [ { "type": "string", "description": "A description of the function. Used by the model to determine whether or not to call the function." }, { "type": "null" } ] }, "parameters": { "anyOf": [ { "additionalProperties": {}, "type": "object", "description": "A JSON schema object describing the parameters of the function." }, { "type": "null" } ] }, "strict": { "anyOf": [ { "type": "boolean", "description": "Whether to enforce strict parameter validation. Default `true`." }, { "type": "null" } ] } }, "type": "object", "required": [ "type", "name", "strict", "parameters" ], "title": "Function", "description": "Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling)." }, { "properties": { "type": { "type": "string", "enum": [ "web_search_preview", "web_search_preview_2025_03_11" ], "description": "The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.", "default": "web_search_preview", "x-stainless-const": true }, "user_location": { "anyOf": [ { "properties": { "type": { "type": "string", "enum": [ "approximate" ], "description": "The type of location approximation. Always `approximate`.", "default": "approximate", "x-stainless-const": true }, "country": { "anyOf": [ { "type": "string", "description": "The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`." }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string", "description": "Free text input for the region of the user, e.g. `California`." }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "description": "Free text input for the city of the user, e.g. `San Francisco`." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string", "description": "The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`." }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ] }, { "type": "null" } ] }, "search_context_size": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default." } }, "type": "object", "required": [ "type" ], "title": "Web search preview", "description": "This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search)." }, { "properties": { "type": { "type": "string", "enum": [ "computer_use_preview" ], "description": "The type of the computer use tool. Always `computer_use_preview`.", "default": "computer_use_preview", "x-stainless-const": true }, "environment": { "type": "string", "enum": [ "windows", "mac", "linux", "ubuntu", "browser" ], "description": "The type of computer environment to control." }, "display_width": { "type": "integer", "description": "The width of the computer display." }, "display_height": { "type": "integer", "description": "The height of the computer display." } }, "type": "object", "required": [ "type", "environment", "display_width", "display_height" ], "title": "Computer use preview", "description": "A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use)." } ], "discriminator": { "propertyName": "type" } } }, "tool_choice": { "description": "How the model should select which tool (or tools) to use when generating\na response. See the `tools` parameter to see how to specify which tools\nthe model can call.\n", "oneOf": [ { "type": "string", "title": "Tool choice mode", "description": "Controls which (if any) tool is called by the model.\n\n`none` means the model will not call any tool and instead generates a message.\n\n`auto` means the model can pick between generating a message or calling one or\nmore tools.\n\n`required` means the model must call one or more tools.\n", "enum": [ "none", "auto", "required" ] }, { "type": "object", "title": "Hosted tool", "description": "Indicates that the model should use a built-in tool to generate a response.\n[Learn more about built-in tools](/docs/guides/tools).\n", "properties": { "type": { "type": "string", "description": "The type of hosted tool the model should to use. Learn more about\n[built-in tools](/docs/guides/tools).\n\nAllowed values are:\n- `file_search`\n- `web_search_preview`\n- `computer_use_preview`\n", "enum": [ "file_search", "web_search_preview", "computer_use_preview", "web_search_preview_2025_03_11" ] } }, "required": [ "type" ] }, { "type": "object", "title": "Function tool", "description": "Use this option to force the model to call a specific function.\n", "properties": { "type": { "type": "string", "enum": [ "function" ], "description": "For function calling, the type is always `function`.", "x-stainless-const": true }, "name": { "type": "string", "description": "The name of the function to call." } }, "required": [ "type", "name" ] } ] }, "truncation": { "type": "string", "description": "The truncation strategy to use for the model response.\n- `auto`: If the context of this response and previous ones exceeds\n the model's context window size, the model will truncate the \n response to fit the context window by dropping input items in the\n middle of the conversation. \n- `disabled` (default): If a model response will exceed the context window \n size for a model, the request will fail with a 400 error.\n", "enum": [ "auto", "disabled" ], "nullable": true, "default": "disabled" } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this Response.\n" }, "object": { "type": "string", "description": "The object type of this resource - always set to `response`.\n", "enum": [ "response" ], "x-stainless-const": true }, "status": { "type": "string", "description": "The status of the response generation. One of `completed`, `failed`, \n`in_progress`, or `incomplete`.\n", "enum": [ "completed", "failed", "in_progress", "incomplete" ] }, "created_at": { "type": "number", "description": "Unix timestamp (in seconds) of when this Response was created.\n" }, "error": { "type": "object", "description": "An error object returned when the model fails to generate a Response.\n", "nullable": true, "properties": { "code": { "type": "string", "description": "The error code for the response.\n", "enum": [ "server_error", "rate_limit_exceeded", "invalid_prompt", "vector_store_timeout", "invalid_image", "invalid_image_format", "invalid_base64_image", "invalid_image_url", "image_too_large", "image_too_small", "image_parse_error", "image_content_policy_violation", "invalid_image_mode", "image_file_too_large", "unsupported_image_media_type", "empty_image_file", "failed_to_download_image", "image_file_not_found" ] }, "message": { "type": "string", "description": "A human-readable description of the error.\n" } }, "required": [ "code", "message" ] }, "incomplete_details": { "type": "object", "nullable": true, "description": "Details about why the response is incomplete.\n", "properties": { "reason": { "type": "string", "description": "The reason why the response is incomplete.", "enum": [ "max_output_tokens", "content_filter" ] } } }, "output": { "type": "array", "description": "An array of content items generated by the model.\n\n- The length and order of items in the `output` array is dependent\n on the model's response.\n- Rather than accessing the first item in the `output` array and \n assuming it's an `assistant` message with the content generated by\n the model, you might consider using the `output_text` property where\n supported in SDKs.\n", "items": { "anyOf": [ { "type": "object", "title": "Output message", "description": "An output message from the model.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the output message.\n" }, "type": { "type": "string", "description": "The type of the output message. Always `message`.\n", "enum": [ "message" ], "x-stainless-const": true }, "role": { "type": "string", "description": "The role of the output message. Always `assistant`.\n", "enum": [ "assistant" ], "x-stainless-const": true }, "content": { "type": "array", "description": "The content of the output message.\n", "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "output_text" ], "description": "The type of the output text. Always `output_text`.", "default": "output_text", "x-stainless-const": true }, "text": { "type": "string", "description": "The text output from the model." }, "annotations": { "items": { "oneOf": [ { "properties": { "type": { "type": "string", "enum": [ "file_citation" ], "description": "The type of the file citation. Always `file_citation`.", "default": "file_citation", "x-stainless-const": true }, "file_id": { "type": "string", "description": "The ID of the file." }, "index": { "type": "integer", "description": "The index of the file in the list of files." } }, "type": "object", "required": [ "type", "file_id", "index" ], "title": "File citation", "description": "A citation to a file." }, { "properties": { "type": { "type": "string", "enum": [ "url_citation" ], "description": "The type of the URL citation. Always `url_citation`.", "default": "url_citation", "x-stainless-const": true }, "url": { "type": "string", "description": "The URL of the web resource." }, "start_index": { "type": "integer", "description": "The index of the first character of the URL citation in the message." }, "end_index": { "type": "integer", "description": "The index of the last character of the URL citation in the message." }, "title": { "type": "string", "description": "The title of the web resource." } }, "type": "object", "required": [ "type", "url", "start_index", "end_index", "title" ], "title": "URL citation", "description": "A citation for a web resource used to generate a model response." }, { "type": "object", "title": "File path", "description": "A path to a file.\n", "properties": { "type": { "type": "string", "description": "The type of the file path. Always `file_path`.\n", "enum": [ "file_path" ], "x-stainless-const": true }, "file_id": { "type": "string", "description": "The ID of the file.\n" }, "index": { "type": "integer", "description": "The index of the file in the list of files.\n" } }, "required": [ "type", "file_id", "index" ] } ], "discriminator": { "propertyName": "type" } }, "type": "array", "description": "The annotations of the text output." } }, "type": "object", "required": [ "type", "text", "annotations" ], "title": "Output text", "description": "A text output from the model." }, { "properties": { "type": { "type": "string", "enum": [ "refusal" ], "description": "The type of the refusal. Always `refusal`.", "default": "refusal", "x-stainless-const": true }, "refusal": { "type": "string", "description": "The refusal explanationfrom the model." } }, "type": "object", "required": [ "type", "refusal" ], "title": "Refusal", "description": "A refusal from the model." } ] } }, "status": { "type": "string", "description": "The status of the message input. One of `in_progress`, `completed`, or\n`incomplete`. Populated when input items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "id", "type", "role", "content", "status" ] }, { "type": "object", "title": "File search tool call", "description": "The results of a file search tool call. See the \n[file search guide](/docs/guides/tools-file-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the file search tool call.\n" }, "type": { "type": "string", "enum": [ "file_search_call" ], "description": "The type of the file search tool call. Always `file_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "description": "The status of the file search tool call. One of `in_progress`, \n`searching`, `incomplete` or `failed`,\n", "enum": [ "in_progress", "searching", "completed", "incomplete", "failed" ] }, "queries": { "type": "array", "items": { "type": "string" }, "description": "The queries used to search for files.\n" }, "results": { "type": "array", "description": "The results of the file search tool call.\n", "items": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The unique ID of the file.\n" }, "text": { "type": "string", "description": "The text that was retrieved from the file.\n" }, "filename": { "type": "string", "description": "The name of the file.\n" }, "attributes": { "type": "object", "description": "Set of 16 key-value pairs that can be attached to an object. This can be \nuseful for storing additional information about the object in a structured \nformat, and querying for objects via API or the dashboard. Keys are strings \nwith a maximum length of 64 characters. Values are strings with a maximum \nlength of 512 characters, booleans, or numbers.\n", "maxProperties": 16, "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "oneOf": [ { "type": "string", "maxLength": 512 }, { "type": "number" }, { "type": "boolean" } ] }, "x-oaiTypeLabel": "map", "nullable": true }, "score": { "type": "number", "format": "float", "description": "The relevance score of the file - a value between 0 and 1.\n" } } }, "nullable": true } }, "required": [ "id", "type", "status", "queries" ] }, { "type": "object", "title": "Function tool call", "description": "A tool call to run a function. See the \n[function calling guide](/docs/guides/function-calling) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the function tool call.\n" }, "type": { "type": "string", "enum": [ "function_call" ], "description": "The type of the function tool call. Always `function_call`.\n", "x-stainless-const": true }, "call_id": { "type": "string", "description": "The unique ID of the function tool call generated by the model.\n" }, "name": { "type": "string", "description": "The name of the function to run.\n" }, "arguments": { "type": "string", "description": "A JSON string of the arguments to pass to the function.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "call_id", "name", "arguments" ] }, { "type": "object", "title": "Web search tool call", "description": "The results of a web search tool call. See the \n[web search guide](/docs/guides/tools-web-search) for more information.\n", "properties": { "id": { "type": "string", "description": "The unique ID of the web search tool call.\n" }, "type": { "type": "string", "enum": [ "web_search_call" ], "description": "The type of the web search tool call. Always `web_search_call`.\n", "x-stainless-const": true }, "status": { "type": "string", "description": "The status of the web search tool call.\n", "enum": [ "in_progress", "searching", "completed", "failed" ] } }, "required": [ "id", "type", "status" ] }, { "type": "object", "title": "Computer tool call", "description": "A tool call to a computer use tool. See the \n[computer use guide](/docs/guides/tools-computer-use) for more information.\n", "properties": { "type": { "type": "string", "description": "The type of the computer call. Always `computer_call`.", "enum": [ "computer_call" ], "default": "computer_call" }, "id": { "type": "string", "description": "The unique ID of the computer call." }, "call_id": { "type": "string", "description": "An identifier used when responding to the tool call with output.\n" }, "action": { "oneOf": [ { "type": "object", "title": "Click", "description": "A click action.\n", "properties": { "type": { "type": "string", "enum": [ "click" ], "default": "click", "description": "Specifies the event type. For a click action, this property is \nalways set to `click`.\n", "x-stainless-const": true }, "button": { "type": "string", "enum": [ "left", "right", "wheel", "back", "forward" ], "description": "Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`.\n" }, "x": { "type": "integer", "description": "The x-coordinate where the click occurred.\n" }, "y": { "type": "integer", "description": "The y-coordinate where the click occurred.\n" } }, "required": [ "type", "button", "x", "y" ] }, { "type": "object", "title": "DoubleClick", "description": "A double click action.\n", "properties": { "type": { "type": "string", "enum": [ "double_click" ], "default": "double_click", "description": "Specifies the event type. For a double click action, this property is \nalways set to `double_click`.\n", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the double click occurred.\n" }, "y": { "type": "integer", "description": "The y-coordinate where the double click occurred.\n" } }, "required": [ "type", "x", "y" ] }, { "type": "object", "title": "Drag", "description": "A drag action.\n", "properties": { "type": { "type": "string", "enum": [ "drag" ], "default": "drag", "description": "Specifies the event type. For a drag action, this property is \nalways set to `drag`.\n", "x-stainless-const": true }, "path": { "type": "array", "description": "An array of coordinates representing the path of the drag action. Coordinates will appear as an array\nof objects, eg\n```\n[\n { x: 100, y: 200 },\n { x: 200, y: 300 }\n]\n```\n", "items": { "type": "object", "title": "Coordinate", "description": "An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.\n", "properties": { "x": { "type": "integer", "description": "The x-coordinate.\n" }, "y": { "type": "integer", "description": "The y-coordinate.\n" } }, "required": [ "x", "y" ] } } }, "required": [ "type", "path" ] }, { "type": "object", "title": "KeyPress", "description": "A collection of keypresses the model would like to perform.\n", "properties": { "type": { "type": "string", "enum": [ "keypress" ], "default": "keypress", "description": "Specifies the event type. For a keypress action, this property is \nalways set to `keypress`.\n", "x-stainless-const": true }, "keys": { "type": "array", "items": { "type": "string", "description": "One of the keys the model is requesting to be pressed.\n" }, "description": "The combination of keys the model is requesting to be pressed. This is an\narray of strings, each representing a key.\n" } }, "required": [ "type", "keys" ] }, { "type": "object", "title": "Move", "description": "A mouse move action.\n", "properties": { "type": { "type": "string", "enum": [ "move" ], "default": "move", "description": "Specifies the event type. For a move action, this property is \nalways set to `move`.\n", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate to move to.\n" }, "y": { "type": "integer", "description": "The y-coordinate to move to.\n" } }, "required": [ "type", "x", "y" ] }, { "type": "object", "title": "Screenshot", "description": "A screenshot action.\n", "properties": { "type": { "type": "string", "enum": [ "screenshot" ], "default": "screenshot", "description": "Specifies the event type. For a screenshot action, this property is \nalways set to `screenshot`.\n", "x-stainless-const": true } }, "required": [ "type" ] }, { "type": "object", "title": "Scroll", "description": "A scroll action.\n", "properties": { "type": { "type": "string", "enum": [ "scroll" ], "default": "scroll", "description": "Specifies the event type. For a scroll action, this property is \nalways set to `scroll`.\n", "x-stainless-const": true }, "x": { "type": "integer", "description": "The x-coordinate where the scroll occurred.\n" }, "y": { "type": "integer", "description": "The y-coordinate where the scroll occurred.\n" }, "scroll_x": { "type": "integer", "description": "The horizontal scroll distance.\n" }, "scroll_y": { "type": "integer", "description": "The vertical scroll distance.\n" } }, "required": [ "type", "x", "y", "scroll_x", "scroll_y" ] }, { "type": "object", "title": "Type", "description": "An action to type in text.\n", "properties": { "type": { "type": "string", "enum": [ "type" ], "default": "type", "description": "Specifies the event type. For a type action, this property is \nalways set to `type`.\n", "x-stainless-const": true }, "text": { "type": "string", "description": "The text to type.\n" } }, "required": [ "type", "text" ] }, { "type": "object", "title": "Wait", "description": "A wait action.\n", "properties": { "type": { "type": "string", "enum": [ "wait" ], "default": "wait", "description": "Specifies the event type. For a wait action, this property is \nalways set to `wait`.\n", "x-stainless-const": true } }, "required": [ "type" ] } ] }, "pending_safety_checks": { "type": "array", "items": { "type": "object", "description": "A pending safety check for the computer call.\n", "properties": { "id": { "type": "string", "description": "The ID of the pending safety check." }, "code": { "type": "string", "description": "The type of the pending safety check." }, "message": { "type": "string", "description": "Details about the pending safety check." } }, "required": [ "id", "code", "message" ] }, "description": "The pending safety checks for the computer call.\n" }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "type", "id", "action", "call_id", "pending_safety_checks", "status" ] }, { "type": "object", "description": "A description of the chain of thought used by a reasoning model while generating\na response.\n", "title": "Reasoning", "properties": { "type": { "type": "string", "description": "The type of the object. Always `reasoning`.\n", "enum": [ "reasoning" ], "x-stainless-const": true }, "id": { "type": "string", "description": "The unique identifier of the reasoning content.\n" }, "summary": { "type": "array", "description": "Reasoning text contents.\n", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the object. Always `summary_text`.\n", "enum": [ "summary_text" ], "x-stainless-const": true }, "text": { "type": "string", "description": "A short summary of the reasoning used by the model when generating\nthe response.\n" } }, "required": [ "type", "text" ] } }, "status": { "type": "string", "description": "The status of the item. One of `in_progress`, `completed`, or\n`incomplete`. Populated when items are returned via API.\n", "enum": [ "in_progress", "completed", "incomplete" ] } }, "required": [ "id", "summary", "type" ] } ], "discriminator": { "propertyName": "type" } } }, "output_text": { "type": "string", "nullable": true, "description": "SDK-only convenience property that contains the aggregated text output \nfrom all `output_text` items in the `output` array, if any are present. \nSupported in the Python and JavaScript SDKs.\n", "x-oaiSupportedSDKs": [ "python", "javascript" ] }, "usage": { "type": "object", "description": "Represents token usage details including input tokens, output tokens,\na breakdown of output tokens, and the total tokens used.\n", "properties": { "input_tokens": { "type": "integer", "description": "The number of input tokens." }, "input_tokens_details": { "type": "object", "description": "A detailed breakdown of the input tokens.", "properties": { "cached_tokens": { "type": "integer", "description": "The number of tokens that were retrieved from the cache. \n[More on prompt caching](/docs/guides/prompt-caching).\n" } }, "required": [ "cached_tokens" ] }, "output_tokens": { "type": "integer", "description": "The number of output tokens." }, "output_tokens_details": { "type": "object", "description": "A detailed breakdown of the output tokens.", "properties": { "reasoning_tokens": { "type": "integer", "description": "The number of reasoning tokens." } }, "required": [ "reasoning_tokens" ] }, "total_tokens": { "type": "integer", "description": "The total number of tokens used." } }, "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens" ] }, "parallel_tool_calls": { "type": "boolean", "description": "Whether to allow the model to run tool calls in parallel.\n", "default": true } }, "required": [ "id", "object", "created_at", "error", "incomplete_details", "instructions", "model", "tools", "output", "parallel_tool_calls", "metadata", "tool_choice", "temperature", "top_p" ], "x-oaiMeta": { "name": "The response object", "group": "responses", "example": "{\n \"id\": \"resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41\",\n \"object\": \"response\",\n \"created_at\": 1741476777,\n \"status\": \"completed\",\n \"error\": null,\n \"incomplete_details\": null,\n \"instructions\": null,\n \"max_output_tokens\": null,\n \"model\": \"gpt-4o-2024-08-06\",\n \"output\": [\n {\n \"type\": \"message\",\n \"id\": \"msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41\",\n \"status\": \"completed\",\n \"role\": \"assistant\",\n \"content\": [\n {\n \"type\": \"output_text\",\n \"text\": \"The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.\",\n \"annotations\": []\n }\n ]\n }\n ],\n \"parallel_tool_calls\": true,\n \"previous_response_id\": null,\n \"reasoning\": {\n \"effort\": null,\n \"summary\": null\n },\n \"store\": true,\n \"temperature\": 1.0,\n \"text\": {\n \"format\": {\n \"type\": \"text\"\n }\n },\n \"tool_choice\": \"auto\",\n \"tools\": [],\n \"top_p\": 1.0,\n \"truncation\": \"disabled\",\n \"usage\": {\n \"input_tokens\": 328,\n \"input_tokens_details\": {\n \"cached_tokens\": 0\n },\n \"output_tokens\": 52,\n \"output_tokens_details\": {\n \"reasoning_tokens\": 0\n },\n \"total_tokens\": 380\n },\n \"user\": null,\n \"metadata\": {}\n}\n" } } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } } } }, "/ai/images/generations": { "post": { "operationId": "postAiImagesGenerations", "summary": "Image generation", "description": "Dispatches to the image source that owns the model (Cloudflare provider-native for `openai/*` etc., Workers AI for `@cf/*`). Returns standardized `ImageOutput { images[] }`.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Image generation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "b64": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "mimeType" ] } } }, "required": [ "images" ], "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "n": { "type": "integer", "minimum": 1, "maximum": 10 }, "size": { "description": "e.g. \"1024x1024\", \"1024x1536\", \"1536x1024\".", "type": "string" }, "quality": { "type": "string" }, "output_format": { "type": "string", "enum": [ "png", "jpeg", "webp" ] } }, "required": [ "model", "prompt" ], "additionalProperties": {} } } } } } }, "/ai/audio/speech": { "post": { "operationId": "postAiAudioSpeech", "summary": "Text-to-speech", "description": "Dispatches to the speech source. Returns raw audio bytes (Content-Type matches the requested format).", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Audio bytes" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1, "description": "Text to synthesize." }, "voice": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "type": "number", "minimum": 0.25, "maximum": 4 } }, "required": [ "model", "text", "voice" ], "additionalProperties": {} } } } } } }, "/ai/audio/transcriptions": { "post": { "operationId": "postAiAudioTranscriptions", "summary": "Audio transcription", "description": "Send `multipart/form-data` with a `file` part and `model` field. Dispatches to the transcription source. Returns standardized `TranscriptionOutput { text, segments? }`.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Transcription result", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" } }, "required": [ "start", "end", "text" ] } } }, "required": [ "text" ], "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } } } }, "/ai/video/generations": { "post": { "operationId": "postAiVideoGenerations", "summary": "Video generation (async)", "description": "Dispatches to the video source. Returns `AsyncJob { jobId, status, pollUrl }` — poll via `GET /ai/responses/{jobId}`.", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Async job", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed" ] }, "pollUrl": { "type": "string" }, "output": { "type": "object", "properties": {}, "additionalProperties": {} }, "error": { "type": "string" } }, "required": [ "jobId", "status", "pollUrl" ], "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "duration_seconds": { "type": "number", "exclusiveMinimum": 0 }, "aspect_ratio": { "type": "string" } }, "required": [ "model", "prompt" ], "additionalProperties": {} } } } } } }, "/ai/gateway": { "post": { "operationId": "postAiGateway", "summary": "Generic Cloudflare AI Gateway escape hatch", "description": "Forwards `input` to `/` on Cloudflare AI Gateway. Used for provider-native paths and Workers AI calls (`endpoint: \"workers-ai\"`, `model: \"@cf/...\"`).", "tags": [ "AI Proxy" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Provider response (shape varies per endpoint)", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": {} } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "402": { "description": "Insufficient credits or billing not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } }, "502": { "description": "Upstream Cloudflare gateway error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": {} } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "minLength": 1 }, "model": { "type": "string", "minLength": 1 }, "input": {} }, "required": [ "endpoint", "model", "input" ], "additionalProperties": {} } } } } } }, "/tools/run": { "post": { "operationId": "postToolsRun", "summary": "Run a Kazzle tool", "description": "Invoke a Kazzle tool with the same `{ name, input }` envelope the AI uses (nested public input, e.g. `computer: { list: {} }`). Authenticated with a `kzl_` API key; scoped to that key's space. Pass `threadId` only for thread-dependent tools. Targeted device tools (`health`) run when the named `computerId` is online (mux). Untargeted client tools (`tab`) and provider tools (`web_search`) cannot run here. Handlers must not return a required-action card on this route — use a domain error instead (e.g. health `permission_required`).\n\nLarge results are capped: when `truncated` is true, `content` is a slice and `resultId` is set — page with `{ \"name\": \"result\", \"input\": { \"read\": { \"resultId\": \"\", \"offset\": N, \"limit\": M } } }`.", "tags": [ "Tools" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "const": "ai", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "image.generate" }, "prompt": { "type": "string", "minLength": 1, "description": "What to generate. Describe the subject/content — style is handled by the style parameter." }, "target_path": { "type": "string", "minLength": 1, "description": "Path inside the container where the image will be written, e.g. `icon.png`." }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container (app, repo, or storage). Not a computerId." }, "style": { "description": "Art style preset. Injects optimized prompt modifiers. Omit for no style guidance.", "type": "string", "enum": [ "icon", "illustration", "photo", "flat", "pixel-art", "3d" ] }, "width": { "description": "Output width in pixels. Default 1024. Image is resized to exact dimensions after generation.", "type": "number" }, "height": { "description": "Output height in pixels. Default 1024. Image is resized to exact dimensions after generation.", "type": "number" }, "model": { "description": "Image model. Default `openai/gpt-image-1`. Also: `openai/dall-e-3`, `@cf/black-forest-labs/flux-1-schnell`.", "type": "string" } }, "required": [ "action", "prompt", "target_path", "container_drive_item_id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "audio.synthesize" }, "text": { "type": "string", "minLength": 1, "description": "Text to synthesize into speech." }, "target_path": { "type": "string", "minLength": 1, "description": "Path inside the container where the audio will be written, e.g. `narration.mp3`." }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container (app, repo, or storage). Not a computerId." }, "voice": { "description": "Voice id (e.g. `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer` for OpenAI TTS).", "type": "string", "minLength": 1 }, "format": { "description": "Output audio format. Default inferred from `target_path` extension or `mp3`.", "type": "string", "enum": [ "mp3", "opus", "aac", "flac", "wav", "pcm" ] }, "speed": { "description": "Playback speed multiplier.", "type": "number", "minimum": 0.25, "maximum": 4 }, "model": { "description": "TTS model. Default `openai/tts-1`. Also: `openai/tts-1-hd`.", "type": "string" } }, "required": [ "action", "text", "target_path", "container_drive_item_id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "audio.transcribe" }, "source_path": { "type": "string", "minLength": 1, "description": "Path of the audio file to transcribe, inside `source_container_drive_item_id`." }, "source_container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID of the container holding the source audio file." }, "target_path": { "type": "string", "minLength": 1, "description": "Path where the transcript JSON will be written, e.g. `transcript.json`." }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container (app, repo, or storage). Not a computerId." }, "language": { "description": "ISO-639-1 language code hint (e.g. `en`).", "type": "string" }, "prompt": { "description": "Optional context prompt to bias decoding.", "type": "string" }, "model": { "description": "Transcription model. Default `openai/whisper-1`. Also: `@cf/openai/whisper`.", "type": "string" } }, "required": [ "action", "source_path", "source_container_drive_item_id", "target_path", "container_drive_item_id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "video.generate" }, "prompt": { "type": "string", "minLength": 1, "description": "Description of the video to generate." }, "target_path": { "type": "string", "minLength": 1, "description": "Path inside the container where the video will be written, e.g. `clip.mp4`." }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container (app, repo, or storage). Not a computerId." }, "duration_seconds": { "description": "Clip duration in seconds. Provider-specific limits apply.", "type": "number", "exclusiveMinimum": 0 }, "aspect_ratio": { "description": "Aspect ratio, e.g. `16:9`, `9:16`, `1:1`.", "type": "string" }, "model": { "description": "Video model. Default `openai/sora-2`.", "type": "string" } }, "required": [ "action", "prompt", "target_path", "container_drive_item_id" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "api_docs", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "type": "object", "properties": { "source": { "type": "string", "description": "\"kazzle\" for the Kazzle API, or a URL to an openapi.json file" }, "filter": { "type": "string", "description": "Category name (e.g. \"threads\", \"billing\") or specific endpoint (e.g. \"POST /threads\")" }, "detail": { "type": "string", "description": "Detail level: \"index\" (default) or \"full\"", "enum": [ "index", "full" ] } }, "required": [ "source" ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "api_key", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "expires_in": { "description": "Expiry duration: \"1h\", \"24h\", \"7d\", \"30d\", \"90d\". Omit for never.", "type": "string" } }, "required": [ "action", "name" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "revoke" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "action", "name" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "app", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "name": { "type": "string", "minLength": 1, "description": "Display name of the app to create" }, "description": { "type": "string" }, "computerId": { "description": "Computer to create the editable app checkout on. For generated apps, choose a cloud computer by default. Use a device only when the user explicitly asks for device-specific work and it is online.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "template": { "description": "Template ID. Use tpl_list to see required parameters. Defaults to empty.", "type": "string", "enum": [ "empty", "ui", "process", "ui-db", "realtime", "ai" ] }, "databaseId": { "description": "Required for ui-db and realtime templates. Realtime requires sync ready.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "action", "name" ], "additionalProperties": {} }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "include_deleted": { "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "search" }, "query": { "description": "Optional text to match against installable app slugs and publishers in the marketplace. Omit to browse every installable app.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "get" }, "catalogAppId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Catalog app id (apps.id UUID) from app {\"search\":{}} results. Never invent it." } }, "required": [ "action", "catalogAppId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "show" }, "catalogAppId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Catalog app id (apps.id UUID) from app {\"search\":{}} results. Never invent it. Emits an install card in the chat so the user can install the app with one click." } }, "required": [ "action", "catalogAppId" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "appdev", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "code_search" }, "query": { "type": "string", "minLength": 1, "description": "Required search query for semantic app lookup." }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "appId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "App ID whose codebase should be searched. App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs." }, "topK": { "description": "Optional cap on semantic results before pagination is applied.", "type": "number" } }, "required": [ "action", "query", "appId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "visibility" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "isPublic": { "type": "boolean" } }, "required": [ "action", "isPublic" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "store_listing" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "isListedInStore": { "type": "boolean" } }, "required": [ "action", "isListedInStore" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "publish" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "deploy": { "description": "Deploy after publishing (default: true)", "type": "boolean" }, "wait": { "description": "Wait for the release job to finish and return its URL or concrete failure. publish defaults to true; release_status defaults to false.", "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "release_status" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "jobId": { "description": "Optional release job ID returned by publish. Omit to read the newest release for this app.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "wait": { "description": "Wait for the release job to finish and return its URL or concrete failure. publish defaults to true; release_status defaults to false.", "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "draft_start" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "wait": { "description": "Defaults to true and waits for the managed draft preview lifecycle to reach running/stopped or return a concrete error. Do not use terminal sleep for preview readiness; use this wait contract, draft_status, and draft_logs.", "type": "boolean" }, "componentName": { "description": "Optional draft preview component name. Omit to start every UI/process component in the draft.", "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "draft_stop" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "wait": { "description": "Defaults to true and waits for the managed draft preview lifecycle to reach running/stopped or return a concrete error. Do not use terminal sleep for preview readiness; use this wait contract, draft_status, and draft_logs.", "type": "boolean" }, "componentName": { "description": "Optional draft preview component name. Omit to stop every UI/process component in the draft.", "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "draft_restart" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "wait": { "description": "Defaults to true and waits for the managed draft preview lifecycle to reach running/stopped or return a concrete error. Do not use terminal sleep for preview readiness; use this wait contract, draft_status, and draft_logs.", "type": "boolean" }, "componentName": { "description": "Optional draft preview component name. Omit to restart every UI/process component in the draft.", "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "draft_status" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "componentName": { "description": "Optional draft preview component name. Omit to list every managed draft component for the app. When slots_full is present, the result includes concrete slot blockers and the safe next action.", "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "draft_logs" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" }, "componentName": { "description": "Optional draft preview component name. Omit to return logs for every managed draft component for the app.", "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "draft_stop_blockers" }, "appId": { "description": "App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "appName": { "description": "Exact app name. Prefer appId from app.list or tool output when available.", "type": "string" } }, "required": [ "action" ], "additionalProperties": false, "description": "Stop only the safe preview slot blockers returned by draft_status or a SLOTS_FULL draft_start result for this target app. Does not stop guessed app IDs or unrelated apps." }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "check" }, "appId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "App ID to verify. App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs." } }, "required": [ "action", "appId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "link" }, "appId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "App ID to link the current checkout to. Writes .kazzle/link.json so kazzle run can resolve appId after a fresh clone or from any subdirectory. App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs." } }, "required": [ "action", "appId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "clone" }, "appId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "App ID to clone onto a computer. App ID. Use app {\"list\":{}}, app.create output, or draft_status slot blocker output to get this UUID; never invent or derive app IDs." }, "computerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Computer to clone the app onto. Required — pick an online computer with computer { list: {} }. Use this when the app is not cloned onto any computer (e.g. the computer it was on is gone). The app code lives in its repository, so it can be cloned again. Also writes the link file, so no separate link call is needed." } }, "required": [ "action", "appId", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tpl_list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tpl_tree" }, "template": { "type": "string", "minLength": 1 } }, "required": [ "action" ], "additionalProperties": false, "description": "Get the file tree of a canonical template. Reads the read-only canonical template for reference only. This is NOT the checked-out app — to read app files use fs {\"read\":{\"appId\":\"\",\"path\":\"\"}} and to search app code use appdev {\"code_search\":{\"appId\":\"\"}}." }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tpl_read" }, "template": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1, "description": "Path within the canonical template. Reads the read-only canonical template for reference only. This is NOT the checked-out app — to read app files use fs {\"read\":{\"appId\":\"\",\"path\":\"\"}} and to search app code use appdev {\"code_search\":{\"appId\":\"\"}}." } }, "required": [ "action", "path" ], "additionalProperties": false, "description": "Read a file from a canonical template. Reads the read-only canonical template for reference only. This is NOT the checked-out app — to read app files use fs {\"read\":{\"appId\":\"\",\"path\":\"\"}} and to search app code use appdev {\"code_search\":{\"appId\":\"\"}}." }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tpl_search" }, "template": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 } }, "required": [ "action", "query" ], "additionalProperties": false, "description": "Search a canonical template's files. Reads the read-only canonical template for reference only. This is NOT the checked-out app — to read app files use fs {\"read\":{\"appId\":\"\",\"path\":\"\"}} and to search app code use appdev {\"code_search\":{\"appId\":\"\"}}." } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "automation", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "name": { "type": "string", "minLength": 1 }, "scheduleKind": { "default": "cron", "type": "string", "enum": [ "cron", "once" ], "description": "'cron' for a recurring automation, 'once' for a one-off automation that fires a single time and is then deleted." }, "schedule": { "description": "Cron expression. Required when scheduleKind is 'cron'. Minimum interval is environment-specific and at least 60 seconds in production.", "type": "string", "minLength": 1 }, "runAt": { "description": "ISO 8601 datetime for a one-off automation, e.g. 2026-06-09T15:00:00Z. Required when scheduleKind is 'once'. Compute it from the current time in context.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "scheduleTimezone": { "description": "IANA timezone (e.g. America/New_York) the cron schedule is interpreted in, so it fires at the right wall-clock time across DST. For recurring schedules default this to the user's timezone from the current window context (userTimezone), unless the user explicitly asks for a different timezone. Not used for one-off automations.", "type": "string" }, "threadTarget": { "default": "new", "type": "string", "enum": [ "new", "reuse" ] }, "config": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1 }, "autoModel": { "type": "boolean" }, "modelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "ask", "work" ] }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "default": [], "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "fileType": { "type": "string", "enum": [ "image", "pdf", "text", "code", "binary" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "containerId": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "path" ], "additionalProperties": false } }, "notification": { "description": "Notification delivery preferences for this message/automation. priority today; extensible later. Missing → default.", "type": "object", "properties": { "priority": { "description": "How noisy the push for this turn is. low = no sound/quiet; default = normal banner + sound; high = heads-up on Android/desktop (on iOS behaves like default). See documents/notifications.md.", "type": "string", "enum": [ "low", "default", "high" ] } }, "additionalProperties": false } }, "required": [ "prompt", "mode", "files" ], "additionalProperties": false } }, "required": [ "action", "name", "scheduleKind", "threadTarget", "config" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "update" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Internal automation ID. Use it only inside automation tool calls; never mention it to the user." }, "name": { "type": "string", "minLength": 1 }, "scheduleKind": { "type": "string", "enum": [ "cron", "once" ], "description": "'cron' for a recurring automation, 'once' for a one-off automation that fires a single time and is then deleted." }, "schedule": { "description": "Cron expression. Required when scheduleKind is 'cron'. Minimum interval is environment-specific and at least 60 seconds in production.", "type": "string", "minLength": 1 }, "runAt": { "description": "ISO 8601 datetime for a one-off automation, e.g. 2026-06-09T15:00:00Z. Required when scheduleKind is 'once'. Compute it from the current time in context.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "scheduleTimezone": { "description": "IANA timezone (e.g. America/New_York) the cron schedule is interpreted in, so it fires at the right wall-clock time across DST. For recurring schedules default this to the user's timezone from the current window context (userTimezone), unless the user explicitly asks for a different timezone. Not used for one-off automations.", "type": "string" }, "threadTarget": { "type": "string", "enum": [ "new", "reuse" ] }, "config": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1 }, "autoModel": { "type": "boolean" }, "modelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "ask", "work" ] }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "default": [], "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "fileType": { "type": "string", "enum": [ "image", "pdf", "text", "code", "binary" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "containerId": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "path" ], "additionalProperties": false } }, "notification": { "description": "Notification delivery preferences for this message/automation. priority today; extensible later. Missing → default.", "type": "object", "properties": { "priority": { "description": "How noisy the push for this turn is. low = no sound/quiet; default = normal banner + sound; high = heads-up on Android/desktop (on iOS behaves like default). See documents/notifications.md.", "type": "string", "enum": [ "low", "default", "high" ] } }, "additionalProperties": false } }, "required": [ "prompt", "mode", "files" ], "additionalProperties": false } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "enable", "description": "Reactivate a disabled automation so it resumes running on its schedule. Reversible; keeps the automation and its config." }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Internal automation ID. Use it only inside automation tool calls; never mention it to the user." } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "disable", "description": "Turn OFF an automation without removing it: it stops running but stays saved and can be re-enabled later. This is the correct action when the user wants to stop, pause, turn off, or temporarily halt an automation. Prefer this over delete." }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Internal automation ID. Use it only inside automation tool calls; never mention it to the user." } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete", "description": "PERMANENTLY remove an automation and its config. Not reversible. Use only when the user explicitly wants it gone for good. To merely stop it from running, use disable instead." }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Internal automation ID. Use it only inside automation tool calls; never mention it to the user." } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "get" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Internal automation ID. Use it only inside automation tool calls; never mention it to the user." } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "run", "description": "Trigger the automation to execute immediately, once, right now — in addition to its normal schedule. Does not change its enabled/disabled state." }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Internal automation ID. Use it only inside automation tool calls; never mention it to the user." } }, "required": [ "action", "id" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "browser", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "open" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to open or list browsers on. Discover with computer { list: {} }. Required — never inferred." }, "url": { "type": "string" } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "close" }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "sessions" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to open or list browsers on. Discover with computer { list: {} }. Required — never inferred." } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to open or list browsers on. Discover with computer { list: {} }. Required — never inferred." } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "nav" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "url": { "type": "string", "minLength": 1 } }, "required": [ "action", "browserTabId", "url" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "back" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "forward" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "reload" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "screenshot" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "target": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "viewport", "full_page", "element", "clip" ], "description": "What to capture. Default viewport when target is omitted." }, "frameRef": { "description": "Optional frame ref for viewport/full_page/clip. Clip coordinates are relative to that frame.", "type": "string", "minLength": 1 }, "ref": { "description": "Element ref from the latest snapshot. Required when type is element.", "type": "string", "minLength": 1 }, "clip": { "description": "CSS-pixel clip rect. Required when type is clip.", "type": "object", "properties": { "x": { "type": "number", "minimum": 0 }, "y": { "type": "number", "minimum": 0 }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false } }, "required": [ "type" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "format": { "description": "Image format. Default png.", "type": "string", "enum": [ "png", "jpeg" ] }, "quality": { "description": "JPEG quality 0-100. Invalid for png.", "type": "integer", "minimum": 0, "maximum": 100 }, "scale": { "description": "css = CSS pixels; device = physical pixels. Default device.", "type": "string", "enum": [ "css", "device" ] }, "transparentBackground": { "description": "Transparent background. PNG only. Default false.", "type": "boolean" } }, "additionalProperties": false } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "eval" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "function": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Sync or async JavaScript function expression. Runs in the page main world. Must return JSON." }, "target": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page", "frame", "element" ], "description": "Execution context. Omitted target means the main page." }, "ref": { "description": "Snapshot ref. Required for frame and element; forbidden for page.", "type": "string", "minLength": 1 } }, "required": [ "type" ], "additionalProperties": false }, "arguments": { "description": "JSON arguments passed to the function after the optional element/frame context.", "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, "timeoutSeconds": { "description": "Max seconds to wait. Default 30.", "type": "number", "exclusiveMinimum": 0, "maximum": 120 } }, "required": [ "action", "browserTabId", "function" ], "additionalProperties": false, "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] } } }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "pdf" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "paper": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "letter", "legal", "tabloid", "ledger", "a0", "a1", "a2", "a3", "a4", "a5", "a6" ] }, "width": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|in|cm|mm)$" }, "height": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|in|cm|mm)$" } }, "additionalProperties": false }, "landscape": { "type": "boolean" }, "printBackground": { "type": "boolean" }, "margins": { "type": "object", "properties": { "top": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|in|cm|mm)$" }, "right": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|in|cm|mm)$" }, "bottom": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|in|cm|mm)$" }, "left": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|in|cm|mm)$" } }, "additionalProperties": false }, "pageRanges": { "description": "Chromium page ranges, e.g. \"1-3,5\".", "type": "string" }, "scale": { "type": "number", "minimum": 0.1, "maximum": 2 }, "preferCssPageSize": { "type": "boolean" }, "headerFooter": { "type": "object", "properties": { "headerHtml": { "type": "string", "maxLength": 50000 }, "footerHtml": { "type": "string", "maxLength": 50000 } }, "additionalProperties": false }, "tagged": { "type": "boolean" }, "outline": { "type": "boolean" } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "snapshot" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "offset": { "description": "Start index into the full matched set (default 0). Pass the previous result's nextOffset to continue.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "description": "Max items to return in this chunk. Backends apply a sane default cap.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "from": { "description": "Walk from the top (default) or from the bottom of the page (oldest-first scraping).", "type": "string", "enum": [ "start", "end" ] }, "viewport": { "description": "Only scan elements currently in the viewport.", "type": "boolean" } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "click" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "ref": { "description": "Opaque element id from the latest browser.snapshot (e.g. \"e12\"). The preferred way to target elements. Refs are only valid for the most recent snapshot of the current page; re-snapshot after navigation or DOM changes.", "type": "string" }, "selector": { "description": "CSS selector for a visible element. Prefer the \"ref\" from browser.snapshot. Do not invent selectors for elements not present in snapshot/dom output.", "type": "string" }, "text": { "description": "Match a clickable element by visible text (fallback when no ref).", "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "doubleClick": { "description": "Double-click instead of single click.", "type": "boolean" }, "button": { "description": "Mouse button (default left). Use \"right\" to open a context menu.", "type": "string", "enum": [ "left", "right", "middle" ] } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "type" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "text": { "type": "string", "minLength": 1 }, "ref": { "description": "Opaque element id from the latest browser.snapshot (e.g. \"e12\"). The preferred way to target elements. Refs are only valid for the most recent snapshot of the current page; re-snapshot after navigation or DOM changes.", "type": "string" }, "selector": { "description": "CSS selector for a visible element. Prefer the \"ref\" from browser.snapshot. Do not invent selectors for elements not present in snapshot/dom output.", "type": "string" }, "delay": { "type": "number" } }, "required": [ "action", "browserTabId", "text" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "select" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "ref": { "type": "string", "minLength": 1, "description": "Ref of the , listbox, menu, combobox, or its trigger. Omit to read the most relevant open selection surface on the page.", "type": "string" } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "wait" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "seconds": { "type": "number" }, "forChallenge": { "description": "Wait until an anti-bot challenge (CAPTCHA, Cloudflare/Turnstile interstitial, reCAPTCHA, hCaptcha) clears. The browser solves these automatically; do NOT click the checkbox. Resolves instantly if no challenge is present. While solving, the original gated action stays running — only call wait after a terminal timeout or to observe separately.", "type": "boolean" }, "text": { "description": "Wait until this text appears on the page.", "type": "string" }, "textGone": { "description": "Wait until this text disappears from the page.", "type": "string" }, "selector": { "description": "Wait until this CSS selector matches an element. Works for brand-new elements with no prior snapshot.", "type": "string" }, "selectorGone": { "description": "Wait until this CSS selector matches no elements.", "type": "string" }, "networkIdle": { "description": "Wait until there are no in-flight network requests (good after navigation or an action that triggers fetches). Long-lived connections (websockets) are ignored, so pages with a persistent analytics/long-poll socket still go idle.", "type": "boolean" }, "timeoutSeconds": { "description": "Max seconds to wait before giving up (applies to networkIdle and the text/selector conditions). Defaults to 12s. Raise this for slow pages.", "type": "number" }, "ref": { "description": "Opaque element id from the latest browser.snapshot (e.g. \"e12\"). The preferred way to target elements. Refs are only valid for the most recent snapshot of the current page; re-snapshot after navigation or DOM changes.", "type": "string" } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "status" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "download" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "url": { "type": "string", "minLength": 1 }, "browserPath": { "type": "string" } }, "required": [ "action", "browserTabId", "url" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tab_open" }, "sessionId": { "type": "string", "minLength": 1 }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserWindowId": { "type": "string" }, "url": { "type": "string" } }, "required": [ "action", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tab_close" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tab_focus" }, "computerId": { "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "tab_move" }, "computerId": { "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." }, "browserWindowId": { "type": "string", "minLength": 1 }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action", "browserTabId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_open" }, "computerId": { "type": "string" }, "sessionId": { "type": "string", "minLength": 1 }, "url": { "type": "string" } }, "required": [ "action", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_close" }, "computerId": { "type": "string" }, "browserWindowId": { "type": "string", "minLength": 1 } }, "required": [ "action", "browserWindowId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_focus" }, "computerId": { "type": "string" }, "browserWindowId": { "type": "string", "minLength": 1 } }, "required": [ "action", "browserWindowId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_place" }, "computerId": { "type": "string" }, "browserWindowId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "action", "browserWindowId", "x", "y", "width", "height" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "live" }, "computerId": { "description": "Optional computer ID for context. browserTabId or sessionId selects the target.", "type": "string" }, "browserTabId": { "type": "string", "minLength": 1, "description": "Browser tab id (UUID from browser open/tab_open/sessions). NOT a Kazzle tab id (`tab-...`) — that is the viewport; a browser tab is one child type it can hold." } }, "required": [ "action", "browserTabId" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "computer", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "type": { "type": "string", "enum": [ "cloud-computer", "browser-computer" ], "description": "Which computer to create." } }, "required": [ "action", "type" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "wake" }, "computerId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "repair" }, "computerId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "stats" }, "computerId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "emergency_disk_inspect" }, "computerId": { "type": "string", "minLength": 1 }, "path": { "description": "Absolute path to inspect. Defaults to /. Only for disk-full wake recovery.", "type": "string" }, "offset": { "description": "Pagination offset into size-ranked results.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "description": "Page size for size-ranked results.", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "action", "computerId" ], "additionalProperties": false, "description": "List largest paths on a cloud computer that failed to wake because its disk is full. Uses provider filesystem APIs that work when process start cannot. Never for normal Drive or file work." }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "emergency_remove_path" }, "computerId": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1, "description": "Absolute path to remove. Only after emergency_disk_inspect on a disk-full wake failure." } }, "required": [ "action", "computerId", "path" ], "additionalProperties": false, "description": "Remove one path to free disk so a cloud computer can wake. Only after a disk-full wake failure. Never for normal Drive or file work." } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "db", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "name": { "type": "string", "minLength": 1, "description": "Database name" }, "isolationReason": { "description": "Required when active databases already exist. Quote the user requirement that needs a fresh isolated database instead of reusing an existing one.", "type": "string" }, "collection": { "description": "Optional secret-collection slug to scope the auto-created connection-URI secrets into. Use secret action=\"coll_list\" to discover slugs.", "type": "string" }, "environment": { "description": "Optional secret-environment slug within the collection. Requires collection.", "type": "string" } }, "required": [ "action", "name" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "connect" }, "databaseId": { "type": "string", "minLength": 1, "description": "Database ID to connect" }, "appId": { "type": "string", "minLength": 1, "description": "App drive item ID whose kazzle.config.ts should be updated" }, "componentName": { "type": "string", "minLength": 1, "description": "Process component name in kazzle.config.ts that should receive database env vars (usually \"server\"). The action writes DATABASE_URL/DIRECT_DATABASE_URL (and APP_SYNC_* when realtime is ready) into the component's secret collection (auto-creating app-/default if the component has no collection yet) and points the component at it via env: { collection, environment }." } }, "required": [ "action", "databaseId", "appId", "componentName" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "rotate_credentials" }, "databaseId": { "type": "string", "minLength": 1 } }, "required": [ "action", "databaseId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "rename" }, "databaseId": { "type": "string", "minLength": 1 }, "newName": { "type": "string", "minLength": 1 } }, "required": [ "action", "databaseId", "newName" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "databaseId": { "type": "string", "minLength": 1 } }, "required": [ "action", "databaseId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "enable_realtime" }, "databaseId": { "type": "string", "minLength": 1 } }, "required": [ "action", "databaseId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "disable_realtime" }, "databaseId": { "type": "string", "minLength": 1 } }, "required": [ "action", "databaseId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "exec" }, "databaseId": { "type": "string", "minLength": 1 }, "sql": { "type": "string", "minLength": 1, "description": "SQL to execute. Multiple statements separated by semicolons." }, "outputPath": { "description": "Filename to write SELECT results as CSV instead of returning inline.", "type": "string" } }, "required": [ "action", "databaseId", "sql" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "desktop", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "live_session_create" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "name": { "type": "string", "minLength": 1 }, "resolution": { "description": "Display resolution (e.g. \"1920x1080\").", "type": "string" } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "live_session_close" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "live_session_list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "screen_capture" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "displayId": { "description": "Display to capture, from a fresh list_displays call (ids can change across reconnects). Omit for primary.", "type": "string", "minLength": 1 } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list_displays" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_click" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "button": { "type": "string", "enum": [ "left", "right", "middle" ] } }, "required": [ "action", "computerId", "sessionId", "x", "y" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_double_click" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "action", "computerId", "sessionId", "x", "y" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_mouse_down" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "button": { "type": "string", "enum": [ "left", "right", "middle" ] } }, "required": [ "action", "computerId", "sessionId", "x", "y" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_mouse_up" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "button": { "type": "string", "enum": [ "left", "right", "middle" ] } }, "required": [ "action", "computerId", "sessionId", "x", "y" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_type" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "sessionId", "text" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_key" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1, "description": "Key combo (e.g. \"ctrl+c\")." } }, "required": [ "action", "computerId", "sessionId", "key" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_move" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "action", "computerId", "sessionId", "x", "y" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_drag" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "toX": { "type": "number" }, "toY": { "type": "number" } }, "required": [ "action", "computerId", "sessionId", "x", "y", "toX", "toY" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "input_scroll" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 }, "deltaX": { "type": "number" }, "deltaY": { "type": "number" }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "action", "computerId", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "screen_info" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_get_active" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "permissions_check" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." } }, "required": [ "action", "computerId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_start" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "bundleId": { "type": "string", "minLength": 1, "description": "Required app bundle identifier, e.g. com.tinyspeck.slackmacgap. Discover bundleIds via desktop { action: \"list\" } first — do not guess." }, "appName": { "description": "Optional display label only. app_start still requires bundleId.", "type": "string" }, "windowPath": { "type": "array", "items": { "type": "number" } }, "windowTitle": { "type": "string" }, "physicalInput": { "type": "string", "enum": [ "blocked", "ask", "allowed" ] } }, "required": [ "action", "computerId", "bundleId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_stop" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "controlledAppSessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_status" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "controlledAppSessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_inspect" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "depth": { "type": "integer", "minimum": 0, "maximum": 12 } }, "required": [ "action", "computerId", "controlledAppSessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_press" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "elementPath": { "type": "array", "items": { "type": "number" } } }, "required": [ "action", "computerId", "controlledAppSessionId", "elementPath" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_set_value" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "elementPath": { "type": "array", "items": { "type": "number" } }, "value": { "type": "string" } }, "required": [ "action", "computerId", "controlledAppSessionId", "elementPath", "value" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "app_capture" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "computerId", "controlledAppSessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_raise" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "windowPath": { "type": "array", "items": { "type": "number" } } }, "required": [ "action", "computerId", "controlledAppSessionId", "windowPath" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "window_place" }, "computerId": { "type": "string", "minLength": 1, "description": "Computer to target. Discover with computer { list: {} }. Required — desktop actions never infer a machine." }, "controlledAppSessionId": { "type": "string", "minLength": 1 }, "windowPath": { "type": "array", "items": { "type": "number" } }, "sessionId": { "type": "string", "minLength": 1 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "action", "computerId", "sessionId", "x", "y", "width", "height" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "fs", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "read" }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container. Not a computerId." }, "target": { "description": "Optional target label. Use \"container\" when container_drive_item_id is present.", "type": "string", "enum": [ "managed-storage", "container" ] }, "path": { "type": "string", "minLength": 1, "description": "File path inside the container to read, relative to the container root, e.g. \"src/index.ts\"." }, "offset": { "description": "Line-based pagination. First line to read, 1-indexed. Default 1. Text content is returned line-numbered (\"N|line\"); the result reports totalLines and hasMore so you can read the next window (e.g. offset = previous offset + limit).", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "description": "Max lines to return for text files. Default 250, hard cap 5000. Read a focused window; if hasMore is true, re-read with a higher offset to continue. Use grep to locate the right range first instead of reading large files whole.", "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "fromEnd": { "description": "When true, return the last `limit` lines instead of the first (tail). Useful for logs. Default false.", "type": "boolean" } }, "required": [ "action", "container_drive_item_id", "path" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "container_drive_item_id": { "description": "Drive item ID (`drive_items.id`) of the node to list. A folder (or the Drive root) returns the child Drive items inside it (apps, folders, mounts, connected repos, storage); an app/repo/mount/storage container returns its files. Mutually exclusive with `root`. Not a computerId.", "type": "string", "minLength": 1 }, "root": { "description": "Set true to list the top-level Drive items for this space (apps, folders, mounts, connected git repos, storage), each with its id and type — use this to discover what is connected before answering. Mutually exclusive with `container_drive_item_id`.", "type": "boolean" }, "path": { "description": "Only when `container_drive_item_id` is a file container (app/repo/mount/storage): a subdirectory inside it. Ignored for folders and the Drive root.", "type": "string" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "write" }, "container_drive_item_id": { "description": "Drive item ID (`drive_items.id`) of the target container. Not a computerId.", "type": "string" }, "path": { "type": "string", "minLength": 1, "description": "File path inside the container to write, relative to the container root, e.g. \"src/index.ts\". Created if missing." }, "content": { "description": "Full file contents to write. Provide either `content` (whole file) or `editSnippet` (partial edit), not both.", "type": "string" }, "editSnippet": { "description": "Partial edit with context. Use \"// ... existing code ...\" for unchanged sections. Server merges into existing file via Fast Apply.", "type": "string" }, "encoding": { "description": "Content encoding. Default \"utf-8\". Use \"base64\" for binary files (images, icons).", "type": "string", "enum": [ "utf-8", "base64" ] }, "target": { "description": "For app/repo files use \"container\" with container_drive_item_id. For thread files use \"managed-storage\". If container_drive_item_id is present, \"container\" is inferred.", "type": "string", "enum": [ "managed-storage", "container" ] } }, "required": [ "action", "path" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container. Not a computerId." }, "target": { "description": "Optional target label. Use \"container\" when container_drive_item_id is present.", "type": "string", "enum": [ "managed-storage", "container" ] }, "path": { "type": "string", "minLength": 1, "description": "File path inside the container to delete, relative to the container root." } }, "required": [ "action", "container_drive_item_id", "path" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "move" }, "source_container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the source container (move/copy)." }, "source_path": { "type": "string", "minLength": 1, "description": "Source file path to move, relative to the source container root." }, "target_container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container (move/copy)." }, "target_path": { "type": "string", "minLength": 1, "description": "Destination file path, relative to the target container root." } }, "required": [ "action", "source_container_drive_item_id", "source_path", "target_container_drive_item_id", "target_path" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "copy" }, "source_container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the source container (move/copy)." }, "source_path": { "type": "string", "minLength": 1, "description": "Source file path to copy, relative to the source container root." }, "target_container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container (move/copy)." }, "target_path": { "type": "string", "minLength": 1, "description": "Destination file path, relative to the target container root." } }, "required": [ "action", "source_container_drive_item_id", "source_path", "target_container_drive_item_id", "target_path" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "grep" }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the container to search. Required. Grep is scoped to a single container — call once per container if you need to search several." }, "pattern": { "type": "string", "minLength": 1, "description": "Regex pattern (ripgrep syntax). Use literal text for plain string matches." }, "path": { "description": "Optional subdirectory inside the container to limit the search scope. Defaults to the container root.", "type": "string" }, "include": { "description": "Optional filename glob to restrict which files are searched, e.g. \"*.ts\" or \"**/*.{ts,tsx}\".", "type": "string" }, "case_sensitive": { "description": "Default false (case-insensitive).", "type": "boolean" }, "max_results": { "description": "Max matching lines to return. Default 100, hard cap 500.", "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "required": [ "action", "container_drive_item_id", "pattern" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "glob" }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the container to search. Required." }, "pattern": { "type": "string", "minLength": 1, "description": "Filename glob pattern, e.g. \"**/package.json\" or \"**/*.{ts,tsx}\". Search is scoped to one container." }, "max_results": { "description": "Max file paths to return. Default 200, hard cap 1000.", "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "action", "container_drive_item_id", "pattern" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "info" }, "container_drive_item_id": { "type": "string", "minLength": 1, "description": "Drive item ID (`drive_items.id`) of the target container. Not a computerId." }, "path": { "description": "Optional file/folder path inside the container. Omit to get only container-level metadata (where the container lives).", "type": "string" } }, "required": [ "action", "container_drive_item_id" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "git", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1, "description": "Git repository URL. Accepts HTTPS and SSH forms." }, "checkoutComputerId": { "type": "string", "minLength": 1, "description": "Computer ID where the repository should be cloned/checked out. Use computer { action: \"list\" } first if unknown." }, "path": { "description": "Optional Drive path/name for the Git repository. Defaults to the repository name.", "type": "string", "minLength": 1 }, "checkoutPath": { "description": "Optional exact filesystem checkout path on the selected computer. Defaults to a managed path under the space repos folder.", "type": "string", "minLength": 1 }, "branch": { "description": "Optional branch to clone.", "type": "string", "minLength": 1 }, "authMode": { "default": "public", "description": "How to authenticate: public, saved credential, inline PAT, or inline SSH private key.", "type": "string", "enum": [ "public", "credential", "pat", "ssh-key" ] }, "credentialId": { "description": "Existing Git credential ID for authMode=\"credential\".", "type": "string", "minLength": 1 }, "credentialName": { "description": "Name for a newly stored PAT or SSH credential.", "type": "string", "minLength": 1 }, "token": { "description": "Personal access token for authMode=\"pat\". Stored encrypted before connecting.", "type": "string", "minLength": 1 }, "username": { "description": "Optional username for authMode=\"pat\".", "type": "string", "minLength": 1 }, "privateKey": { "description": "SSH private key for authMode=\"ssh-key\". Stored encrypted before connecting.", "type": "string", "minLength": 1 }, "host": { "description": "Optional Git host metadata, e.g. github.com.", "type": "string", "minLength": 1 }, "action": { "type": "string", "const": "connect" } }, "required": [ "repoUrl", "checkoutComputerId", "authMode", "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "status" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "files" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "path": { "type": "string" }, "action": { "type": "string", "const": "diff" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "path", "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "pull" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "push": { "type": "boolean" }, "action": { "type": "string", "const": "commit" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "message", "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "revert" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "push" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "checkout": { "default": true, "type": "boolean" }, "action": { "type": "string", "const": "branch" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "name", "checkout", "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "branch": { "type": "string" }, "action": { "type": "string", "const": "switch" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "branch", "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "branches" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "action", "itemId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "body": { "default": "", "type": "string" }, "base": { "type": "string" }, "action": { "type": "string", "const": "pr" }, "itemId": { "type": "string", "minLength": 1, "description": "Drive item ID of the Git repository or app." } }, "required": [ "title", "body", "base", "action", "itemId" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "http_request", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "type": "object", "properties": { "method": { "type": "string", "description": "HTTP method", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string" }, "headers": { "type": "object", "description": "Request headers. Use secret templates for sensitive values: {\"Authorization\": \"${secret..token}\"}", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "description": "Request body (sent as JSON). Omit for GET/DELETE.", "additionalProperties": { "type": "string" } }, "timeout": { "type": "number", "description": "Timeout in seconds (default 15, max 30)" } }, "required": [ "method", "url" ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "kazzle_docs", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "type": "object", "properties": { "query": { "type": "string", "description": "Search query or exact runbook slug. Exact slugs include build-ui-app, build-realtime-app, build-landing-page, setup-database, and secrets." } }, "required": [ "query" ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "mode_request", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "type": "object", "properties": { "target": { "type": "string", "description": "Target mode.", "enum": [ "work" ] }, "reason": { "type": "string", "description": "Why the escalation is needed (shown to user)." } }, "required": [ "target", "reason" ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "result", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "read" }, "resultId": { "type": "string", "minLength": 1, "description": "Handle returned by a prior tool result that was stored (the result included a resultId)." }, "offset": { "description": "First line to read, 1-indexed. Default 1. Read the next window with offset = previous offset + limit.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "description": "Max lines to return. Default 250, hard cap 5000.", "type": "integer", "exclusiveMinimum": 0, "maximum": 5000 }, "fromEnd": { "description": "When true, return the last `limit` lines instead of the first (tail). Useful for logs.", "type": "boolean" } }, "required": [ "action", "resultId" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "safety", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "policies" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "limits" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "set_policy" }, "toolId": { "type": "string", "minLength": 1, "description": "Exact tool ID (e.g. \"terminal\", \"fs\", \"app\")." }, "policy": { "type": "string", "enum": [ "allow", "ask", "block" ] }, "conditions": { "description": "Field conditions: { field, op, value }. Operators: eq, contains, startsWith, endsWith, matches, gt, lt, gte, lte, oneOf.", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "op": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "field", "op", "value" ], "additionalProperties": false } } }, "required": [ "action", "toolId", "policy" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete_policy" }, "toolId": { "type": "string", "minLength": 1, "description": "Exact tool ID (e.g. \"terminal\", \"fs\", \"app\")." }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "op": { "type": "string", "minLength": 1 }, "value": { "type": "string" } }, "required": [ "field", "op", "value" ], "additionalProperties": false } } }, "required": [ "action", "toolId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "set_limit" }, "counterType": { "type": "string", "minLength": 1 }, "threshold": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "action", "counterType", "threshold" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete_limit" }, "counterType": { "type": "string", "minLength": 1 } }, "required": [ "action", "counterType" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "secret", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "name": { "type": "string", "minLength": 1 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Key-value pairs to store (e.g., { email: \"...\", password: \"...\" })" }, "service": { "type": "string" }, "collection": { "type": "string" }, "environment": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "action", "name", "payload" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collection": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "id": { "type": "string", "minLength": 1 }, "name": { "description": "Human-readable secret name (the name shown by action: \"list\"). Always include it so the approval/activity UI shows which secret is being deleted instead of an opaque id.", "type": "string" } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "move" }, "id": { "type": "string", "minLength": 1 }, "collection": { "type": "string" }, "environment": { "type": "string" } }, "required": [ "action", "id" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "coll_create" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "action", "name" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "coll_list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "env_create" }, "name": { "type": "string", "minLength": 1, "description": "Environment name to create, e.g. \"local\". Required; do not omit it." }, "collection": { "type": "string", "minLength": 1, "description": "Existing collection name or ID. Reuse the app/database collection unless creating a genuinely new resource." } }, "required": [ "action", "name", "collection" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "env_list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "collection": { "type": "string", "minLength": 1, "description": "Collection name or slug to list environments for." } }, "required": [ "action", "collection" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "skill", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "name": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "description": { "description": "Short description of when this skill is relevant.", "type": "string" }, "alwaysActive": { "description": "true = always in context, false = loaded on demand.", "type": "boolean" } }, "required": [ "action", "name", "content" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "load" }, "skillId": { "type": "string", "minLength": 1, "description": "Skill id or exact skill name (from the skills menu) to load." } }, "required": [ "action", "skillId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "unload" }, "skillId": { "type": "string", "minLength": 1, "description": "Skill id or exact skill name to unload when you no longer need it." } }, "required": [ "action", "skillId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "skillId": { "type": "string", "minLength": 1 } }, "required": [ "action", "skillId" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "space_search", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "messages" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "thread_id": { "type": "string" }, "include_files": { "type": "boolean" }, "include_active": { "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "threads" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "include_active": { "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "message" }, "message_id": { "type": "string", "minLength": 1 }, "thread_id": { "type": "string" } }, "required": [ "action", "message_id" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "terminal", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "run" }, "command": { "type": "string", "minLength": 1, "description": "Command to execute. Returns immediately when finished; if still running after the grace window, returns sessionId so you can keep reading with terminal { read: { sessionId } }." }, "computerId": { "description": "Computer to run on. Required unless cwdRef is set (cwdRef resolves the checkout computer).", "type": "string", "minLength": 1 }, "cwd": { "description": "Literal working directory path for this command. Use cwdRef for generated apps instead of guessing checkout paths.", "type": "string" }, "cwdRef": { "description": "Resolve a known object to a working directory. Use { type: \"app\", id: appId, subdir?: \"server\" } for generated app commands.", "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "description": "Reference type to resolve into a working directory. Currently only \"app\" is supported." }, "id": { "type": "string", "minLength": 1, "description": "ID of the referenced object, e.g. an app ID." }, "subdir": { "description": "Optional relative subdirectory under the resolved working directory, e.g. \"server\".", "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false }, "timeoutMs": { "description": "Max ms to wait inline for the command to finish before returning { running, sessionId } (default 10000). Not a hard kill — the command keeps running.", "type": "number" }, "description": { "description": "Imperative label shown to the user, 2-5 words (e.g. \"Install dependencies\", \"Check logs\").", "type": "string" } }, "required": [ "action", "command" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "computerId": { "description": "Computer for the session. Required unless cwdRef is set (cwdRef resolves the checkout computer).", "type": "string", "minLength": 1 }, "shell": { "type": "string" }, "cwd": { "description": "Literal starting directory for the terminal session. Use cwdRef for generated apps instead of guessing checkout paths.", "type": "string" }, "cwdRef": { "description": "Resolve a known object to a starting directory. Use { type: \"app\", id: appId, subdir?: \"server\" } for generated app terminals.", "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "description": "Reference type to resolve into a working directory. Currently only \"app\" is supported." }, "id": { "type": "string", "minLength": 1, "description": "ID of the referenced object, e.g. an app ID." }, "subdir": { "description": "Optional relative subdirectory under the resolved working directory, e.g. \"server\".", "type": "string" } }, "required": [ "type", "id" ], "additionalProperties": false }, "description": { "description": "Imperative label shown to the user, 2-5 words (e.g. \"Install dependencies\", \"Check logs\").", "type": "string" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "write" }, "sessionId": { "type": "string", "minLength": 1 }, "input": { "type": "string", "minLength": 1, "description": "Text to send as stdin. Include \\n to submit." } }, "required": [ "action", "sessionId", "input" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "read" }, "sessionId": { "type": "string", "minLength": 1, "description": "Terminal session from terminal.run or terminal.create. Works for live sessions and finished-run buffers." }, "startLine": { "description": "1-based first line to return. Output is paginated by line; every read response includes \"totalLines\". To get the LAST N lines, pass startLine = totalLines - N + 1 and endLine = totalLines. There are no \"fromEnd\", \"tail\", or \"limit\" fields — use startLine/endLine only.", "type": "number" }, "endLine": { "description": "1-based last line to return (inclusive). Omit to read to the end.", "type": "number" } }, "required": [ "action", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "ctrl" }, "sessionId": { "type": "string", "minLength": 1 }, "signal": { "type": "string", "enum": [ "interrupt", "eof", "suspend" ], "description": "Control signal to send." } }, "required": [ "action", "sessionId", "signal" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "wait" }, "sessionId": { "type": "string", "minLength": 1 }, "pattern": { "type": "string", "minLength": 1, "description": "Regex to wait for in terminal output." }, "timeoutMs": { "description": "Max wait in ms.", "type": "number" } }, "required": [ "action", "sessionId", "pattern" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "action", "sessionId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "action" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "thread", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "oneOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "plan_update" }, "content": { "type": "string", "minLength": 1 }, "clear": { "description": "Set true to close/clear the plan.", "type": "boolean" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "create" }, "title": { "type": "string" }, "prompt": { "type": "string", "minLength": 1, "description": "Initial user message for the new thread." }, "model": { "description": "Model ID for this thread. Defaults to parent model.", "type": "string" }, "computerId": { "type": "string" } }, "required": [ "action", "prompt" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "delete" }, "threadId": { "type": "string", "minLength": 1 } }, "required": [ "action", "threadId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "list" }, "query": { "description": "Case-insensitive substring filter applied across the primary searchable fields of the listed items. Omit to list everything.", "type": "string" }, "limit": { "description": "Page size. Defaults to 50, max 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Zero-based offset into the filtered result set. Use with `limit` to paginate when `hasMore` is true.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "threadId": { "description": "Parent thread to list children of. Defaults to the current thread.", "type": "string" } }, "required": [ "action" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "read" }, "threadId": { "type": "string", "minLength": 1, "description": "Child thread ID to inspect." } }, "required": [ "action", "threadId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "send" }, "threadId": { "type": "string", "minLength": 1, "description": "Child thread ID to send a follow-up to." }, "message": { "type": "string", "minLength": 1, "description": "Follow-up user message for the child thread." } }, "required": [ "action", "threadId", "message" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "wait" }, "threadId": { "type": "string", "minLength": 1, "description": "Child thread ID to wait for." } }, "required": [ "action", "threadId" ], "additionalProperties": false }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "const": "stop" }, "threadId": { "type": "string", "minLength": 1, "description": "Child thread ID to stop." } }, "required": [ "action", "threadId" ], "additionalProperties": false } ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "wait", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "type": "object", "properties": { "seconds": { "type": "number", "description": "How long to pause, in seconds. Use after launching an app or starting a slow operation, before capturing or checking results." } }, "required": [ "seconds" ] } }, "required": [ "name", "input" ] }, { "type": "object", "properties": { "name": { "const": "web_fetch", "description": "Tool name — same value the AI uses for this tool call." }, "threadId": { "type": "string", "description": "Optional thread to scope the call to. Required only by thread-dependent tools (e.g. thread, mode_request, automation create)." }, "input": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } }, "required": [ "name", "input" ] } ], "description": "Invoke a Kazzle tool by name. The `input` shape is the same object the AI passes for that tool call." } } } }, "responses": { "200": { "description": "Tool result (HTTP 200 even on tool error — check `isError`)", "content": { "application/json": { "schema": { "type": "object", "properties": { "toolUseId": { "type": "string" }, "content": { "type": "string" }, "isError": { "type": "boolean" }, "code": { "type": "string" }, "row": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "items": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "total": { "type": "number" }, "resultId": { "type": "string" }, "truncated": { "type": "boolean" }, "totalBytes": { "type": "number" } }, "required": [ "toolUseId", "content" ], "additionalProperties": {} } } } }, "400": { "description": "Invalid body or non-server tool", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "413": { "description": "Request body too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/automations": { "post": { "operationId": "postAutomations", "description": "Create an automation", "tags": [ "automations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "automation": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "automation" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1 }, "schedule": { "type": "string", "minLength": 1 }, "threadTarget": { "type": "string", "enum": [ "new", "reuse" ] }, "config": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1 }, "autoModel": { "type": "boolean" }, "modelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "ask", "work" ] }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "default": [], "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "fileType": { "type": "string", "enum": [ "image", "pdf", "text", "code", "binary" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "containerId": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "path" ] } }, "notification": { "description": "Notification delivery preferences for this message/automation. priority today; extensible later. Missing → default.", "type": "object", "properties": { "priority": { "description": "How noisy the push for this turn is. low = no sound/quiet; default = normal banner + sound; high = heads-up on Android/desktop (on iOS behaves like default). See documents/notifications.md.", "type": "string", "enum": [ "low", "default", "high" ] } } } }, "required": [ "prompt", "mode" ] } }, "required": [ "spaceId", "name", "schedule", "threadTarget", "config" ] } } } } }, "get": { "operationId": "getAutomations", "description": "List automations for a space", "tags": [ "automations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "automations": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "automations" ] } } } } }, "parameters": [ { "in": "query", "name": "spaceId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "in": "query", "name": "enabled", "schema": { "type": "boolean" } } ] } }, "/automations/{id}": { "get": { "operationId": "getAutomationsById", "description": "Get an automation", "tags": [ "automations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "automation": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "automation" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "in": "query", "name": "spaceId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ] }, "patch": { "operationId": "patchAutomationsById", "description": "Update an automation", "tags": [ "automations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "automation": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "automation" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1 }, "schedule": { "type": "string", "minLength": 1 }, "threadTarget": { "type": "string", "enum": [ "new", "reuse" ] }, "config": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1 }, "autoModel": { "type": "boolean" }, "modelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "ask", "work" ] }, "effort": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "files": { "default": [], "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "fileType": { "type": "string", "enum": [ "image", "pdf", "text", "code", "binary" ] }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "containerId": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "path" ] } }, "notification": { "description": "Notification delivery preferences for this message/automation. priority today; extensible later. Missing → default.", "type": "object", "properties": { "priority": { "description": "How noisy the push for this turn is. low = no sound/quiet; default = normal banner + sound; high = heads-up on Android/desktop (on iOS behaves like default). See documents/notifications.md.", "type": "string", "enum": [ "low", "default", "high" ] } } } }, "required": [ "prompt", "mode" ] } }, "required": [ "spaceId" ] } } } } }, "delete": { "operationId": "deleteAutomationsById", "description": "Delete an automation", "tags": [ "automations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "spaceId" ] } } } } } }, "/automations/{id}/enable": { "post": { "operationId": "postAutomationsByIdEnable", "summary": "Enable automation", "description": "Enables an automation so its schedule/trigger becomes active. Body: `{ spaceId }`.", "tags": [ "automations" ], "responses": { "200": { "description": "Enabled; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not a member of this space" } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "spaceId" ] } } } } } }, "/automations/{id}/disable": { "post": { "operationId": "postAutomationsByIdDisable", "summary": "Disable automation", "description": "Disables an automation so it stops running on its schedule/trigger. Body: `{ spaceId }`.", "tags": [ "automations" ], "responses": { "200": { "description": "Disabled; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not a member of this space" } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "spaceId" ] } } } } } }, "/automations/{id}/run": { "post": { "operationId": "postAutomationsByIdRun", "description": "Run an automation immediately", "tags": [ "automations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "outcome": { "type": "string" } }, "required": [ "ok", "outcome" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "spaceId" ] } } } } } }, "/threads": { "post": { "operationId": "postThreads", "summary": "Create thread", "description": "Creates a new conversation thread in a space. Body: `{ title, spaceId, prompt?, model?, visibility? }`. Returns the new thread id.", "tags": [ "Threads" ], "responses": { "200": { "description": "Thread created; returns `{ id }`" }, "400": { "description": "title and spaceId required" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not a member of this space" } } } }, "/threads/{id}/search": { "get": { "operationId": "getThreadsByIdSearch", "summary": "Search within a thread", "description": "Full-text search over a thread's message segments (text, thinking, summary, error, tool calls). Query params: `query`, `cursor?`, `limit?`. Returns paginated results with a `nextCursor`.", "tags": [ "Threads" ], "responses": { "200": { "description": "Search results; returns `{ results[], nextCursor, exhausted }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not a member of this space" }, "404": { "description": "Thread not found" } }, "parameters": [ { "in": "query", "name": "query", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "includeExpanded", "schema": { "type": "string", "enum": [ "0", "1" ] } }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/threads/{id}/messages/{messageId}/location": { "get": { "operationId": "getThreadsByIdMessagesByMessageIdLocation", "summary": "Resolve message turn order", "description": "Returns `{ turnOrder }` for open-to-hit / Find when the message is not yet in the local SQLite window.", "tags": [ "Threads" ], "responses": { "200": { "description": "`{ turnOrder }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not a member of this space" }, "404": { "description": "Thread or message not found" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "messageId", "required": true } ] } }, "/threads/{id}": { "delete": { "operationId": "deleteThreadsById", "summary": "Delete thread", "description": "Hard-deletes a thread and its messages. Only the thread owner may delete.", "tags": [ "Threads" ], "responses": { "200": { "description": "Thread deleted; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Not the thread owner" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/transcribe": { "post": { "operationId": "postTranscribe", "description": "Transcribe an audio file via OpenAI Whisper", "tags": [ "transcribe" ], "responses": { "200": { "description": "Transcription result", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } } } }, "500": { "description": "Transcription failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/spaces/{spaceId}/databases": { "post": { "operationId": "postSpacesBySpaceIdDatabases", "description": "Create a new database for this space", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name", "provider" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "get": { "operationId": "getSpacesBySpaceIdDatabases", "description": "List databases in a space", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "databases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name", "provider" ] } } }, "required": [ "databases" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}/credentials/regenerate": { "post": { "operationId": "postSpacesBySpaceIdDatabasesByDatabaseIdCredentialsRegenerate", "description": "Regenerate credentials for a database (resets password)", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "dbUri": { "type": "string" } }, "required": [ "provider", "dbUri" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}/connect-app": { "post": { "operationId": "postSpacesBySpaceIdDatabasesByDatabaseIdConnectApp", "description": "Connect a database to an app component", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "content": { "type": "string" } }, "required": [ "success", "content" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" }, "componentName": { "type": "string" } }, "required": [ "appId", "componentName" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}": { "patch": { "operationId": "patchSpacesBySpaceIdDatabasesByDatabaseId", "description": "Rename a database", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "newName": { "type": "string" } }, "required": [ "newName" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdDatabasesByDatabaseId", "description": "Soft-delete a database", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}/restore": { "patch": { "operationId": "patchSpacesBySpaceIdDatabasesByDatabaseIdRestore", "description": "Restore a soft-deleted database", "tags": [ "databases" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}/sync/enable": { "post": { "operationId": "postSpacesBySpaceIdDatabasesByDatabaseIdSyncEnable", "summary": "Enable database sync", "description": "Enables realtime sync (PowerSync) for a space database.", "tags": [ "databases" ], "responses": { "200": { "description": "Enabled; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "500": { "description": "Failed to enable sync" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}/sync/disable": { "post": { "operationId": "postSpacesBySpaceIdDatabasesByDatabaseIdSyncDisable", "summary": "Disable database sync", "description": "Disables realtime sync (PowerSync) for a space database.", "tags": [ "databases" ], "responses": { "200": { "description": "Disabled; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "500": { "description": "Failed to disable sync" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/{spaceId}/databases/{databaseId}/sync/retry": { "post": { "operationId": "postSpacesBySpaceIdDatabasesByDatabaseIdSyncRetry", "summary": "Retry database sync", "description": "Retries setting up realtime sync (PowerSync) for a space database after a failure.", "tags": [ "databases" ], "responses": { "200": { "description": "Retried; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "500": { "description": "Failed to retry sync" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "databaseId", "required": true } ] } }, "/spaces/capacity": { "get": { "operationId": "getSpacesCapacity", "description": "Whether the signed-in user can create a new space (cap + waitlist gate)", "tags": [ "spaces" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "canCreate": { "type": "boolean" } }, "required": [ "canCreate" ] } } } } } } }, "/spaces": { "post": { "operationId": "postSpaces", "description": "Create a new space", "tags": [ "spaces" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "identifier": { "type": "string" } }, "required": [ "id", "identifier" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "userId": { "type": "string" }, "identifier": { "type": "string" }, "locale": { "type": "string" }, "deviceId": { "type": "string" } }, "required": [ "name", "userId" ] } } } } } }, "/spaces/{spaceId}": { "delete": { "operationId": "deleteSpacesBySpaceId", "description": "Soft-delete a space", "tags": [ "spaces" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/apps/{appId}/start": { "post": { "operationId": "postSpacesBySpaceIdAppsByAppIdStart", "description": "Start an app dev server in the sandbox", "tags": [ "spaces" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "appId", "required": true } ] } }, "/spaces/{spaceId}/apps/{appId}/stop": { "post": { "operationId": "postSpacesBySpaceIdAppsByAppIdStop", "description": "Stop an app dev server in the sandbox", "tags": [ "spaces" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "appId", "required": true } ] } }, "/spaces/{spaceId}/drive/upload": { "post": { "operationId": "postSpacesBySpaceIdDriveUpload", "description": "Upload a file to Drive", "tags": [ "drive" ], "responses": { "200": { "description": "Upload successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string" }, "path": { "type": "string" }, "size": { "type": "number" }, "contentType": { "type": "string" } }, "required": [ "containerId", "path", "size", "contentType" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/drive/retry-clone/{driveItemId}": { "post": { "operationId": "postSpacesBySpaceIdDriveRetryCloneByDriveItemId", "description": "Retry a failed repo clone", "tags": [ "drive" ], "responses": { "200": { "description": "Retry initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "driveItemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/drive/{itemId}": { "delete": { "operationId": "deleteSpacesBySpaceIdDriveByItemId", "description": "Permanently delete a Drive item", "tags": [ "drive" ], "responses": { "200": { "description": "Item deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "permanent": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "permanent", "schema": { "type": "string" } } ] } }, "/spaces/{spaceId}/drive/revert": { "post": { "operationId": "postSpacesBySpaceIdDriveRevert", "summary": "Revert file edits", "description": "Revert all file edits from a message onwards", "tags": [ "drive" ], "responses": { "200": { "description": "Revert result" }, "500": { "description": "Revert failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "force": { "type": "boolean" } }, "required": [ "threadId", "messageId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/drive/{itemId}/clone-to-computer": { "post": { "operationId": "postSpacesBySpaceIdDriveByItemIdCloneToComputer", "summary": "Clone item to computer", "description": "Clone a drive item to a different computer", "tags": [ "drive" ], "responses": { "200": { "description": "Cloned; returns `{ success, checkoutComputerId, checkoutPath, errors? }`" }, "400": { "description": "Computer offline or not connected" }, "404": { "description": "Drive item not found" }, "500": { "description": "Clone failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string", "minLength": 1 } }, "required": [ "computerId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "itemId", "required": true } ] } }, "/spaces/{spaceId}/drive/mounts": { "post": { "operationId": "postSpacesBySpaceIdDriveMounts", "description": "Create a local folder mount", "tags": [ "drive-mount" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "path": { "type": "string" }, "uri": { "type": "string" }, "computerId": { "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/drive/mounts/{mountId}": { "delete": { "operationId": "deleteSpacesBySpaceIdDriveMountsByMountId", "description": "Delete a mount", "tags": [ "drive-mount" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "mountId", "required": true } ] } }, "/spaces/{spaceId}/drive/ops/move": { "post": { "operationId": "postSpacesBySpaceIdDriveOpsMove", "summary": "Move across containers", "description": "Move a file/folder across containers", "tags": [ "drive" ], "responses": { "200": { "description": "Moved; returns `{ success: true }`" }, "500": { "description": "Move failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceContainerId": { "type": "string", "minLength": 1 }, "sourcePath": { "type": "string", "minLength": 1 }, "targetContainerId": { "type": "string", "minLength": 1 }, "targetPath": { "type": "string", "minLength": 1 } }, "required": [ "sourceContainerId", "sourcePath", "targetContainerId", "targetPath" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/drive/ops/copy": { "post": { "operationId": "postSpacesBySpaceIdDriveOpsCopy", "summary": "Copy across containers", "description": "Copy a file/folder across containers", "tags": [ "drive" ], "responses": { "200": { "description": "Copied; returns `{ success: true }`" }, "500": { "description": "Copy failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceContainerId": { "type": "string", "minLength": 1 }, "sourcePath": { "type": "string", "minLength": 1 }, "targetContainerId": { "type": "string", "minLength": 1 }, "targetPath": { "type": "string", "minLength": 1 } }, "required": [ "sourceContainerId", "sourcePath", "targetContainerId", "targetPath" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/changes/undo/{threadId}/apply": { "post": { "operationId": "postSpacesBySpaceIdChangesUndoByThreadIdApply", "summary": "Undo file changes from a message", "tags": [ "changes" ], "responses": { "200": { "description": "File changes undone" } }, "parameters": [ { "in": "path", "name": "threadId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "messageId" ] } } } } } }, "/spaces/{spaceId}/changes/undo/{threadId}/redo": { "post": { "operationId": "postSpacesBySpaceIdChangesUndoByThreadIdRedo", "summary": "Redo file changes", "tags": [ "changes" ], "responses": { "200": { "description": "Newest file changes restored" } }, "parameters": [ { "in": "path", "name": "threadId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/changes/storage/{changeId}/manifest": { "get": { "operationId": "getSpacesBySpaceIdChangesStorageByChangeIdManifest", "summary": "Storage change manifest", "tags": [ "changes" ], "responses": { "200": { "description": "Manifest" } }, "parameters": [ { "in": "path", "name": "changeId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/changes/storage/{changeId}/snapshot": { "get": { "operationId": "getSpacesBySpaceIdChangesStorageByChangeIdSnapshot", "summary": "Storage change snapshot bytes", "tags": [ "changes" ], "responses": { "200": { "description": "Base64 snapshot" } }, "parameters": [ { "in": "path", "name": "changeId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "in": "query", "name": "path", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "version", "schema": { "type": "string", "enum": [ "before", "after" ] }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/changes/storage/{changeId}/restore": { "post": { "operationId": "postSpacesBySpaceIdChangesStorageByChangeIdRestore", "summary": "Restore storage change", "tags": [ "changes" ], "responses": { "200": { "description": "Restore result" } }, "parameters": [ { "in": "path", "name": "changeId", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "all" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "paths" }, "paths": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type", "paths" ] } ] } }, "required": [ "scope" ] } } } } } }, "/spaces/{spaceId}/fs": { "get": { "operationId": "getSpacesBySpaceIdFs", "summary": "List directory", "description": "List directory contents", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "parameters": [ { "in": "query", "name": "containerId", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "path", "schema": { "default": "", "type": "string" } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/tree": { "get": { "operationId": "getSpacesBySpaceIdFsTree", "summary": "Build directory tree", "description": "Build directory tree with budget", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "parameters": [ { "in": "query", "name": "containerId", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "path", "schema": { "default": "", "type": "string" } }, { "in": "query", "name": "budget", "schema": { "type": "string" } }, { "in": "query", "name": "minDepth", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/search": { "get": { "operationId": "getSpacesBySpaceIdFsSearch", "summary": "Search files", "description": "Search files by name or content", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "parameters": [ { "in": "query", "name": "containerId", "schema": { "type": "string" } }, { "in": "query", "name": "query", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "in": "query", "name": "mode", "schema": { "type": "string" } }, { "in": "query", "name": "maxResults", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/create": { "post": { "operationId": "postSpacesBySpaceIdFsCreate", "summary": "Create file or directory", "description": "Create a file or directory", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "file", "dir" ] } }, "required": [ "containerId", "path", "type" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/delete": { "post": { "operationId": "postSpacesBySpaceIdFsDelete", "summary": "Delete file or directory", "description": "Soft-delete a file or directory", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1 } }, "required": [ "containerId", "path" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/restore": { "post": { "operationId": "postSpacesBySpaceIdFsRestore", "summary": "Restore deleted file", "description": "Restore a soft-deleted file", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string", "minLength": 1 }, "path": { "type": "string", "minLength": 1 } }, "required": [ "containerId", "path" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/rename": { "post": { "operationId": "postSpacesBySpaceIdFsRename", "summary": "Rename file or directory", "description": "Rename/move a file or directory", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string", "minLength": 1 }, "oldPath": { "type": "string", "minLength": 1 }, "newPath": { "type": "string", "minLength": 1 } }, "required": [ "containerId", "oldPath", "newPath" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/move": { "post": { "operationId": "postSpacesBySpaceIdFsMove", "summary": "Batch-move files", "description": "Batch-move files within a container", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string", "minLength": 1 }, "items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "oldPath": { "type": "string" }, "newPath": { "type": "string" } }, "required": [ "oldPath", "newPath" ] } } }, "required": [ "containerId", "items" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/fs/{containerDriveItemId}": { "get": { "operationId": "getSpacesBySpaceIdFsByContainerDriveItemId", "summary": "Read or list container resource", "description": "Reads a file's bytes, or lists a directory when the path is empty or ends in `/`. Routes to the owning computer filesystem or object storage via the Container interface.", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "containerDriveItemId", "required": true } ] } }, "/spaces/{spaceId}/fs/{containerDriveItemId}/{path}": { "get": { "operationId": "getSpacesBySpaceIdFsByContainerDriveItemIdByPath", "summary": "Read or list container resource at path", "description": "Reads a file's bytes at the given path, or lists the directory when the path ends in `/`.", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid path or container not found" }, "401": { "description": "Not authenticated" }, "404": { "description": "Directory or file not found" }, "500": { "description": "Operation failed" }, "503": { "description": "Computer offline" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "containerDriveItemId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "path", "required": true } ] }, "head": { "operationId": "headSpacesBySpaceIdFsByContainerDriveItemIdByPath", "summary": "Stat container resource", "description": "Returns content-type and content-length headers for a container path without the body.", "tags": [ "drive-fs" ], "responses": { "200": { "description": "Resource headers" }, "404": { "description": "Not found" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "containerDriveItemId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "path", "required": true } ] } }, "/spaces/{spaceId}/broadcast/subscribe": { "get": { "operationId": "getSpacesBySpaceIdBroadcastSubscribe", "tags": [ "broadcast" ], "description": "Subscribe to real-time space events via SSE", "responses": {}, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/secrets": { "get": { "operationId": "getSpacesBySpaceIdSecrets", "description": "List all secrets for a space", "tags": [ "secrets" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secrets": { "type": "array", "items": {} } }, "required": [ "secrets" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "post": { "operationId": "postSpacesBySpaceIdSecrets", "description": "Create a new secret", "tags": [ "secrets" ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "bodyMode": { "type": "string", "enum": [ "string", "json", "fields" ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "payload", "metadata" ] }, "type": { "type": "string", "enum": [ "username", "email", "password", "current-password", "new-password", "otp", "totp-secret", "name", "given-name", "family-name", "phone", "birthday", "organization", "street", "street-2", "city", "region", "postal-code", "country", "cc-name", "cc-number", "cc-exp", "cc-exp-month", "cc-exp-year", "cc-csc", "url", "text", "note", "date", "secret" ] }, "match": { "type": "string", "enum": [ "default", "exact", "never" ] } }, "required": [ "key", "source", "type" ] } }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "service": { "type": "string" }, "expiresAt": { "type": "number" }, "collectionId": { "type": "string" }, "environmentId": { "type": "string" } }, "required": [ "type", "name", "payload" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/secrets/{secretId}/reveal": { "get": { "operationId": "getSpacesBySpaceIdSecretsBySecretIdReveal", "description": "Reveal a secret payload", "tags": [ "secrets" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": {} }, "required": [ "payload" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "secretId", "required": true } ] } }, "/spaces/{spaceId}/secrets/{secretId}": { "put": { "operationId": "putSpacesBySpaceIdSecretsBySecretId", "description": "Update a secret", "tags": [ "secrets" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "bodyMode": { "type": "string", "enum": [ "string", "json", "fields" ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "payload", "metadata" ] }, "type": { "type": "string", "enum": [ "username", "email", "password", "current-password", "new-password", "otp", "totp-secret", "name", "given-name", "family-name", "phone", "birthday", "organization", "street", "street-2", "city", "region", "postal-code", "country", "cc-name", "cc-number", "cc-exp", "cc-exp-month", "cc-exp-year", "cc-csc", "url", "text", "note", "date", "secret" ] }, "match": { "type": "string", "enum": [ "default", "exact", "never" ] } }, "required": [ "key", "source", "type" ] } }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "expiresAt": { "type": "number" } }, "required": [ "payload" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "secretId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdSecretsBySecretId", "description": "Delete a secret", "tags": [ "secrets" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "secretId", "required": true } ] } }, "/spaces/{spaceId}/secrets/{secretId}/scope": { "patch": { "operationId": "patchSpacesBySpaceIdSecretsBySecretIdScope", "description": "Move a secret into a different collection or environment (or to space-level)", "tags": [ "secrets" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "environmentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "collectionId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "secretId", "required": true } ] } }, "/spaces/{spaceId}/secrets/collections": { "get": { "operationId": "getSpacesBySpaceIdSecretsCollections", "summary": "List secret collections", "description": "Lists the secret collections in a space. Collections group secrets and own environments.", "tags": [ "secrets" ], "responses": { "200": { "description": "Collections; returns `{ collections[] }`" }, "500": { "description": "Failed to list collections" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "post": { "operationId": "postSpacesBySpaceIdSecretsCollections", "summary": "Create secret collection", "description": "Creates a secret collection in the space. Body: `{ name, slug? }`.", "tags": [ "secrets" ], "responses": { "201": { "description": "Collection created" }, "400": { "description": "Name is required" }, "500": { "description": "Failed to create collection" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/secrets/collections/{collectionId}": { "patch": { "operationId": "patchSpacesBySpaceIdSecretsCollectionsByCollectionId", "summary": "Rename secret collection", "description": "Renames a collection (name and/or slug). Body: `{ name?, slug? }`.", "tags": [ "secrets" ], "responses": { "200": { "description": "Renamed; returns `{ success: true }`" }, "400": { "description": "Name or slug is required" }, "500": { "description": "Failed to rename collection" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "collectionId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdSecretsCollectionsByCollectionId", "summary": "Delete secret collection", "description": "Deletes a collection and its environments.", "tags": [ "secrets" ], "responses": { "200": { "description": "Deleted; returns `{ success: true }`" }, "500": { "description": "Failed to delete collection" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "collectionId", "required": true } ] } }, "/spaces/{spaceId}/secrets/collections/{collectionId}/environments": { "get": { "operationId": "getSpacesBySpaceIdSecretsCollectionsByCollectionIdEnvironments", "summary": "List collection environments", "description": "Lists environments within a collection (e.g. dev, staging, prod scopes for secrets).", "tags": [ "secrets" ], "responses": { "200": { "description": "Environments; returns `{ environments[] }`" }, "500": { "description": "Failed to list environments" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "collectionId", "required": true } ] }, "post": { "operationId": "postSpacesBySpaceIdSecretsCollectionsByCollectionIdEnvironments", "summary": "Create collection environment", "description": "Creates an environment within a collection. Body: `{ name, slug? }`.", "tags": [ "secrets" ], "responses": { "201": { "description": "Environment created" }, "400": { "description": "Name is required" }, "500": { "description": "Failed to create environment" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" } }, "required": [ "name" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "collectionId", "required": true } ] } }, "/spaces/{spaceId}/secrets/collections/{collectionId}/environments/{environmentId}": { "patch": { "operationId": "patchSpacesBySpaceIdSecretsCollectionsByCollectionIdEnvironmentsByEnvironmentId", "summary": "Rename collection environment", "description": "Renames an environment (name and/or slug). Body: `{ name?, slug? }`.", "tags": [ "secrets" ], "responses": { "200": { "description": "Renamed; returns `{ success: true }`" }, "400": { "description": "Name or slug is required" }, "500": { "description": "Failed to rename environment" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "collectionId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "environmentId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdSecretsCollectionsByCollectionIdEnvironmentsByEnvironmentId", "summary": "Delete collection environment", "description": "Deletes an environment within a collection.", "tags": [ "secrets" ], "responses": { "200": { "description": "Deleted; returns `{ success: true }`" }, "500": { "description": "Failed to delete environment" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "collectionId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "environmentId", "required": true } ] } }, "/spaces/{spaceId}/git/credentials": { "get": { "operationId": "getSpacesBySpaceIdGitCredentials", "description": "List git credentials for a space", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "service": { "type": "string" }, "host": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "service" ] } } }, "required": [ "credentials" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/credentials/ssh-key": { "post": { "operationId": "postSpacesBySpaceIdGitCredentialsSshKey", "description": "Store an SSH key credential", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "privateKey": { "type": "string" }, "host": { "type": "string" } }, "required": [ "name", "privateKey" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/credentials/pat": { "post": { "operationId": "postSpacesBySpaceIdGitCredentialsPat", "description": "Store a personal access token credential", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "token": { "type": "string" }, "host": { "type": "string" }, "username": { "type": "string" } }, "required": [ "name", "token" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/credentials/{credentialId}": { "delete": { "operationId": "deleteSpacesBySpaceIdGitCredentialsByCredentialId", "description": "Delete a git credential", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "credentialId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/connect": { "post": { "operationId": "postSpacesBySpaceIdGitConnect", "description": "Connect a Git repository to Drive", "tags": [ "git" ], "responses": { "200": { "description": "Git repository connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repoUrl": { "type": "string", "minLength": 1, "description": "Git repository URL. Accepts HTTPS and SSH forms." }, "checkoutComputerId": { "type": "string", "minLength": 1, "description": "Computer ID where the repository should be cloned/checked out. Use computer { action: \"list\" } first if unknown." }, "path": { "description": "Optional Drive path/name for the Git repository. Defaults to the repository name.", "type": "string", "minLength": 1 }, "checkoutPath": { "description": "Optional exact filesystem checkout path on the selected computer. Defaults to a managed path under the space repos folder.", "type": "string", "minLength": 1 }, "branch": { "description": "Optional branch to clone.", "type": "string", "minLength": 1 }, "authMode": { "default": "public", "description": "How to authenticate: public, saved credential, inline PAT, or inline SSH private key.", "type": "string", "enum": [ "public", "credential", "pat", "ssh-key" ] }, "credentialId": { "description": "Existing Git credential ID for authMode=\"credential\".", "type": "string", "minLength": 1 }, "credentialName": { "description": "Name for a newly stored PAT or SSH credential.", "type": "string", "minLength": 1 }, "token": { "description": "Personal access token for authMode=\"pat\". Stored encrypted before connecting.", "type": "string", "minLength": 1 }, "username": { "description": "Optional username for authMode=\"pat\".", "type": "string", "minLength": 1 }, "privateKey": { "description": "SSH private key for authMode=\"ssh-key\". Stored encrypted before connecting.", "type": "string", "minLength": 1 }, "host": { "description": "Optional Git host metadata, e.g. github.com.", "type": "string", "minLength": 1 } }, "required": [ "repoUrl", "checkoutComputerId" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/github/install-url": { "get": { "operationId": "getSpacesBySpaceIdGitGithubInstallUrl", "description": "Get the GitHub App installation URL", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/github/sync-installations": { "post": { "operationId": "postSpacesBySpaceIdGitGithubSyncInstallations", "description": "Sync GitHub App installations to credentials", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "synced": { "type": "number" }, "credentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "service": { "type": "string", "const": "github-app" }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "name" ] } } }, "required": [ "synced", "credentials" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/github/repos": { "get": { "operationId": "getSpacesBySpaceIdGitGithubRepos", "description": "List repositories for a GitHub App credential", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "repos": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "fullName": { "type": "string" }, "private": { "type": "boolean" }, "defaultBranch": { "type": "string" }, "cloneUrl": { "type": "string" }, "htmlUrl": { "type": "string" } }, "required": [ "name", "fullName", "private", "defaultBranch", "cloneUrl", "htmlUrl" ], "additionalProperties": {} } } }, "required": [ "repos" ] } } } } }, "parameters": [ { "in": "query", "name": "credentialId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/status": { "get": { "operationId": "getSpacesBySpaceIdGitByItemIdStatus", "description": "Get git status for a drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "type": "string" }, "commitHash": { "type": "string" }, "commitsAhead": { "type": "number" }, "uncommittedCount": { "type": "number" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "status": { "type": "string" } }, "required": [ "path", "status" ] } } }, "additionalProperties": {} } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/pull": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdPull", "description": "Pull latest changes for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "success", "conflicts" ] }, "output": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "status": { "type": "string" }, "conflictMarkerCount": { "type": "number" } }, "required": [ "path", "status", "conflictMarkerCount" ] } } }, "required": [ "kind", "output" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/abort-merge": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdAbortMerge", "description": "Abort an in-progress merge for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": {} }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/commit-merge": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdCommitMerge", "description": "Commit a resolved merge for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string" }, "status": {} }, "required": [ "output" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/commit": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdCommit", "description": "Commit changes for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string" }, "status": {} }, "required": [ "output" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "files": { "type": "array", "items": { "type": "string" } }, "push": { "type": "boolean" } }, "required": [ "message" ] } } } } } }, "/spaces/{spaceId}/git/{itemId}/revert": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdRevert", "description": "Revert uncommitted changes for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": {} }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/push": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdPush", "description": "Push committed changes for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string" } }, "required": [ "output" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/git/{itemId}/branch": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdBranch", "description": "Create a new git branch", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string" } }, "required": [ "output" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "checkout": { "default": true, "type": "boolean" } }, "required": [ "name" ] } } } } } }, "/spaces/{spaceId}/git/{itemId}/switch": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdSwitch", "description": "Switch to a different git branch", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "output": { "type": "string" } }, "required": [ "output" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "type": "string" } }, "required": [ "branch" ] } } } } } }, "/spaces/{spaceId}/git/{itemId}/pr": { "post": { "operationId": "postSpacesBySpaceIdGitByItemIdPr", "description": "Create a pull request for a git drive item", "tags": [ "git" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "number": { "type": "number" } }, "additionalProperties": {} } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "itemId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "default": "", "type": "string" }, "base": { "type": "string" } }, "required": [ "title", "base" ] } } } } } }, "/git/github/callback": { "get": { "operationId": "getGitGithubCallback", "description": "GitHub OAuth callback (popup auto-close)", "tags": [ "git" ], "responses": { "200": { "description": "HTML popup that auto-closes", "content": { "text/html": { "schema": { "type": "string" } } } } }, "parameters": [ { "in": "query", "name": "code", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "state", "schema": { "type": "string" }, "required": true } ] } }, "/app-icons/{appId}": { "get": { "operationId": "getAppIconsByAppId", "summary": "Get app icon", "description": "Returns the icon image bytes for a catalog app, addressed by its catalog app id.", "tags": [ "Apps" ], "responses": { "200": { "description": "Icon image bytes" }, "400": { "description": "Invalid app id" }, "404": { "description": "Icon not found" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "appId", "required": true } ] } }, "/apps/secrets": { "get": { "operationId": "getAppsSecrets", "tags": [ "apps" ], "summary": "List install secret names", "responses": { "200": { "description": "Secret names", "content": { "application/json": { "schema": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" } } }, "required": [ "names" ] } } } } } } }, "/apps/secrets/{name}": { "get": { "operationId": "getAppsSecretsByName", "tags": [ "apps" ], "summary": "Read an install secret", "responses": { "200": { "description": "Secret value", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } } } }, "404": { "description": "Secret not found" } }, "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "required": true } ] }, "put": { "operationId": "putAppsSecretsByName", "tags": [ "apps" ], "summary": "Store an install secret", "responses": { "204": { "description": "Secret stored" } }, "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } }, "required": [ "value" ] } } } } }, "delete": { "operationId": "deleteAppsSecretsByName", "tags": [ "apps" ], "summary": "Delete an install secret", "responses": { "204": { "description": "Secret deleted" } }, "parameters": [ { "in": "path", "name": "name", "schema": { "type": "string" }, "required": true } ] } }, "/apps/metadata": { "get": { "operationId": "getAppsMetadata", "tags": [ "apps" ], "summary": "Read install metadata", "responses": { "200": { "description": "Install metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "metadata" ] } } } } } }, "put": { "operationId": "putAppsMetadata", "tags": [ "apps" ], "summary": "Merge install metadata", "responses": { "200": { "description": "Merged install metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "metadata" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } } } }, "/apps/create": { "post": { "operationId": "postAppsCreate", "description": "Create a new app (drive item + git repo)", "tags": [ "apps" ], "responses": { "200": { "description": "App created", "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string" } }, "required": [ "appId" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "template": { "type": "string", "enum": [ "empty", "ui", "process", "ui-db", "realtime", "ai" ] }, "computerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "name", "spaceId" ] } } } } } }, "/apps/{driveItemId}/publish": { "post": { "operationId": "postAppsByDriveItemIdPublish", "description": "Push main, publish skill content, and queue production deploy", "tags": [ "apps" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deployed": { "type": "boolean" }, "deploySkipped": { "type": "boolean" }, "deployQueued": { "type": "boolean" }, "deployJobId": { "type": "string" }, "deployError": { "type": "string" }, "url": { "type": "string" }, "targetAppId": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "query", "name": "deploy", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/deploy": { "post": { "operationId": "postAppsByDriveItemIdDeploy", "description": "Queue a production deploy for an already published commit without publishing again", "tags": [ "apps" ], "responses": { "200": { "description": "Deploy queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deployQueued": { "type": "boolean" }, "deployJobId": { "type": "string" }, "publishedCommitHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "ok", "deployQueued", "deployJobId", "publishedCommitHash" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publishedCommitHash": { "type": "string", "minLength": 1 }, "fromJobId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/production-lifecycle": { "post": { "operationId": "postAppsByDriveItemIdProductionLifecycle", "description": "Pause or resume every production component for an app", "tags": [ "apps" ], "responses": { "200": { "description": "Lifecycle updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "action": { "type": "string", "enum": [ "pause", "resume" ] }, "componentCount": { "type": "number" } }, "required": [ "ok", "action", "componentCount" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "pause", "resume" ] } }, "required": [ "action" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/check-deploy": { "get": { "operationId": "getAppsByDriveItemIdCheckDeploy", "description": "Check if deployed app is reachable", "tags": [ "apps" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reachable": { "type": "boolean" } }, "required": [ "reachable" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/sync-config": { "post": { "operationId": "postAppsByDriveItemIdSyncConfig", "description": "Repair drive_items.app_config from the checkout kazzle.config.ts", "tags": [ "apps" ], "responses": { "200": { "description": "App config repair result", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "no-checkout", "missing-or-invalid", "unreachable", "error" ] }, "message": { "type": "string" } }, "required": [ "ok", "reason" ] } ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/visibility": { "patch": { "operationId": "patchAppsByDriveItemIdVisibility", "description": "Toggle app public visibility", "tags": [ "apps" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "isPublic": { "type": "boolean" } }, "required": [ "ok", "isPublic" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isPublic": { "type": "boolean" } }, "required": [ "isPublic" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/store-listing": { "patch": { "operationId": "patchAppsByDriveItemIdStoreListing", "description": "Toggle whether an app is listed in the Kazzle Store", "tags": [ "apps" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "isListedInStore": { "type": "boolean" } }, "required": [ "ok", "isListedInStore" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isListedInStore": { "type": "boolean" } }, "required": [ "isListedInStore" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/slug": { "patch": { "operationId": "patchAppsByDriveItemIdSlug", "description": "Change the app public URL slug", "tags": [ "apps" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "slug": { "type": "string" } }, "required": [ "ok", "slug" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$" } }, "required": [ "slug" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/domain": { "get": { "operationId": "getAppsByDriveItemIdDomain", "description": "Get the custom domain for an app", "tags": [ "apps" ], "responses": { "200": { "description": "Domain state", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hostname": { "type": "string" }, "flyAppName": { "type": "string" }, "componentName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_dns", "pending_certificate", "active", "error" ] }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "traffic", "ownership", "acme" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "validationError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "hostname", "flyAppName", "componentName", "status", "dnsRecords", "validationError", "lastCheckedAt" ] }, { "type": "null" } ] } }, "required": [ "domain" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] }, "post": { "operationId": "postAppsByDriveItemIdDomain", "description": "Attach a custom domain to the released primary UI", "tags": [ "apps" ], "responses": { "200": { "description": "Domain created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hostname": { "type": "string" }, "flyAppName": { "type": "string" }, "componentName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_dns", "pending_certificate", "active", "error" ] }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "traffic", "ownership", "acme" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "validationError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "hostname", "flyAppName", "componentName", "status", "dnsRecords", "validationError", "lastCheckedAt" ] } }, "required": [ "ok", "domain" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1 } }, "required": [ "hostname" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] }, "delete": { "operationId": "deleteAppsByDriveItemIdDomain", "description": "Remove the custom domain from the app", "tags": [ "apps" ], "responses": { "200": { "description": "Domain removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/domain/check": { "post": { "operationId": "postAppsByDriveItemIdDomainCheck", "description": "Refresh DNS and certificate status for the custom domain", "tags": [ "apps" ], "responses": { "200": { "description": "Domain status refreshed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "domain": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "hostname": { "type": "string" }, "flyAppName": { "type": "string" }, "componentName": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_dns", "pending_certificate", "active", "error" ] }, "dnsRecords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "TXT" ] }, "name": { "type": "string" }, "value": { "type": "string" }, "purpose": { "type": "string", "enum": [ "traffic", "ownership", "acme" ] } }, "required": [ "type", "name", "value", "purpose" ] } }, "validationError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "hostname", "flyAppName", "componentName", "status", "dnsRecords", "validationError", "lastCheckedAt" ] } }, "required": [ "ok", "domain" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{catalogAppId}/install": { "post": { "operationId": "postAppsByCatalogAppIdInstall", "description": "Install a catalog app into a space (managed install)", "tags": [ "apps" ], "responses": { "200": { "description": "Installed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "driveItemId": { "type": "string" }, "reused": { "type": "boolean" } }, "required": [ "ok", "driveItemId", "reused" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "spaceId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "catalogAppId", "required": true } ] } }, "/apps/{driveItemId}/uninstall": { "post": { "operationId": "postAppsByDriveItemIdUninstall", "description": "Uninstall a managed app (hard-delete the install)", "tags": [ "apps" ], "responses": { "200": { "description": "Uninstalled", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/delete": { "post": { "operationId": "postAppsByDriveItemIdDelete", "description": "Delete an owned app permanently (catalog + repo + deploy + install)", "tags": [ "apps" ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/launch-identity": { "post": { "operationId": "postAppsByDriveItemIdLaunchIdentity", "description": "Mint a {user,space,install} identity token to launch an app UI inside Kazzle", "tags": [ "apps" ], "responses": { "200": { "description": "Minted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "token": { "type": "string" }, "expiresIn": { "type": "number" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "ok", "token", "expiresIn", "url" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "spaceId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/logs/{logSourceId}": { "get": { "operationId": "getAppsByDriveItemIdLogsByLogSourceId", "description": "Stream logs for an app log source. Source ids are app_runtimes.id or process_runs.id.", "tags": [ "apps" ], "responses": { "200": { "description": "Log stream response" } }, "parameters": [ { "in": "query", "name": "follow", "schema": { "type": "string" } }, { "in": "query", "name": "componentName", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "logSourceId", "required": true } ] } }, "/apps/{driveItemId}/deploy-jobs/{jobId}/logs": { "get": { "operationId": "getAppsByDriveItemIdDeployJobsByJobIdLogs", "description": "Stream a deploy job's logs: the stored tail first (scroll-back history), then live output until the job finishes. Logs are not synced via PowerSync.", "tags": [ "apps" ], "responses": { "200": { "description": "Deploy log stream response" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "jobId", "required": true } ] } }, "/apps/{driveItemId}/component/start": { "post": { "operationId": "postAppsByDriveItemIdComponentStart", "description": "Start a component", "tags": [ "apps-component" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "query", "name": "wait", "schema": { "type": "string" } }, { "in": "query", "name": "componentName", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/component/stop": { "post": { "operationId": "postAppsByDriveItemIdComponentStop", "description": "Stop a component", "tags": [ "apps-component" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "query", "name": "wait", "schema": { "type": "string" } }, { "in": "query", "name": "componentName", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/component/restart": { "post": { "operationId": "postAppsByDriveItemIdComponentRestart", "description": "Restart a component", "tags": [ "apps-component" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "query", "name": "wait", "schema": { "type": "string" } }, { "in": "query", "name": "componentName", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/component/logs": { "get": { "operationId": "getAppsByDriveItemIdComponentLogs", "description": "Get component logs (supports SSE streaming with follow=true)", "tags": [ "apps-component" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "log": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "query", "name": "follow", "schema": { "type": "string" } }, { "in": "query", "name": "componentName", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/process/enable": { "post": { "operationId": "postAppsByDriveItemIdProcessEnable", "description": "Enable a scheduled or triggered process", "tags": [ "apps-process" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/process/disable": { "post": { "operationId": "postAppsByDriveItemIdProcessDisable", "description": "Disable a scheduled or triggered process", "tags": [ "apps-process" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/process/run": { "post": { "operationId": "postAppsByDriveItemIdProcessRun", "description": "Trigger a one-off process run", "tags": [ "apps-process" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "runId": { "type": "string" }, "error": { "type": "string" }, "output": {} }, "required": [ "ok" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": {} } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/apps/{driveItemId}/process/runs": { "get": { "operationId": "getAppsByDriveItemIdProcessRuns", "description": "List process run history", "tags": [ "apps-process" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "runs": { "type": "array", "items": {} } }, "required": [ "ok", "runs" ] } } } } }, "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "driveItemId", "required": true } ] } }, "/auth/send-code": { "post": { "operationId": "postAuthSendCode", "description": "Send a sign-in verification code", "tags": [ "auth" ], "responses": { "200": { "description": "Code delivered", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ] } } } } } }, "/auth/app-cookie": { "post": { "operationId": "postAuthAppCookie", "description": "Plant the active account's .kazzle.app cookie from the caller's session (Bearer)", "tags": [ "auth" ], "responses": { "200": { "description": "Cookie planted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "userId": { "type": "string" } }, "required": [ "ok", "userId" ] } } } } } } }, "/auth/clear": { "get": { "operationId": "getAuthClear", "description": "Clear the auth cookie on .kazzle.app", "tags": [ "auth" ], "responses": { "200": { "description": "Cookie cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } } } } }, "/webhooks": { "get": { "operationId": "getWebhooks", "tags": [ "webhooks" ], "description": "Webhook service health check", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] } } } } } } }, "/webhooks/polar": { "post": { "operationId": "postWebhooksPolar", "description": "Receive and verify Polar billing webhooks", "tags": [ "webhooks" ], "responses": { "200": { "description": "Webhook received", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" } }, "required": [ "received" ] } } } } } } }, "/webhooks/billing/reconcile": { "post": { "operationId": "postWebhooksBillingReconcile", "description": "Refresh a space balance from Polar after an app-written ledger event", "tags": [ "webhooks" ], "responses": { "200": { "description": "Balance refresh result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "updated", "unchanged", "pending", "failed" ] }, "availableMicro": { "type": "number" } }, "required": [ "status" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "spaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "appId", "spaceId" ] } } } } } }, "/webhooks/billing/revenuecat": { "post": { "operationId": "postWebhooksBillingRevenuecat", "description": "Receive RevenueCat billing webhooks for mobile IAP", "tags": [ "webhooks" ], "responses": { "200": { "description": "Webhook received", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" } }, "required": [ "received" ] } } } } } } }, "/webhooks/{spaceId}/{appId}/{componentName}/{triggerName}": { "post": { "operationId": "postWebhooksBySpaceIdByAppIdByComponentNameByTriggerName", "tags": [ "webhooks" ], "description": "Fire a named webhook trigger on a process app component", "responses": { "200": { "description": "Trigger fired", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "runId": { "type": "string" }, "component": { "type": "string" }, "trigger": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "appId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "componentName", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "triggerName", "schema": { "type": "string" }, "required": true } ] } }, "/sync/generation": { "get": { "operationId": "getSyncGeneration", "tags": [ "sync" ], "description": "Active PowerSync sync-config generation fingerprint", "responses": { "200": { "description": "Current sync config generation", "content": { "application/json": { "schema": { "type": "object", "properties": { "generation": { "type": "string", "minLength": 1 } }, "required": [ "generation" ] } } } } } } }, "/sync": { "post": { "operationId": "postSync", "tags": [ "sync" ], "description": "App sync upload queue — batched CRUD operations", "responses": { "200": { "description": "Sync result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "discarded": { "type": "boolean" }, "code": { "type": "string" }, "error": { "type": "string" } }, "required": [ "ok" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "errors": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "itemId", "error" ] } } }, "required": [ "ok", "errors" ] } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ops": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "op": { "type": "string", "enum": [ "PUT", "PATCH", "DELETE" ] }, "table": { "type": "string" }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "op", "table" ] } } } } } } } } }, "/preview/secrets": { "post": { "operationId": "postPreviewSecrets", "description": "Vault a sensitive field value from a drive preview form submission", "tags": [ "preview" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "secretId": { "type": "string" } }, "required": [ "secretId" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "field": { "type": "string", "minLength": 1 }, "value": {}, "ttl": { "type": "string" }, "spaceId": { "type": "string", "minLength": 1 } }, "required": [ "name", "field", "value", "spaceId" ] } } } } } }, "/api-keys": { "post": { "operationId": "postApiKeys", "description": "Create a new API key", "tags": [ "api-keys" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "key", "name" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "spaceId": { "type": "string" }, "description": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "name", "spaceId" ] } } } } }, "get": { "operationId": "getApiKeys", "description": "List all API keys for a space", "tags": [ "api-keys" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": {} } }, "required": [ "keys" ] } } } } }, "parameters": [ { "in": "query", "name": "spaceId", "schema": { "type": "string" }, "required": true } ] } }, "/api-keys/{id}/plaintext": { "get": { "operationId": "getApiKeysByIdPlaintext", "description": "Get decrypted API key plaintext", "tags": [ "api-keys" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "spaceId", "schema": { "type": "string" }, "required": true } ] } }, "/api-keys/{id}/deactivate": { "post": { "operationId": "postApiKeysByIdDeactivate", "description": "Deactivate an API key", "tags": [ "api-keys" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string" } }, "required": [ "spaceId" ] } } } } } }, "/api-keys/{id}/activate": { "post": { "operationId": "postApiKeysByIdActivate", "description": "Activate an API key", "tags": [ "api-keys" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string" } }, "required": [ "spaceId" ] } } } } } }, "/api-keys/{id}": { "delete": { "operationId": "deleteApiKeysById", "description": "Delete an API key permanently", "tags": [ "api-keys" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spaceId": { "type": "string" } }, "required": [ "spaceId" ] } } } } } }, "/spaces/{spaceId}/computers": { "get": { "operationId": "getSpacesBySpaceIdComputers", "summary": "List computers", "description": "List all computers in a space", "tags": [ "computers" ], "responses": { "200": { "description": "Computer rows for the space" }, "500": { "description": "Internal error" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/create": { "post": { "operationId": "postSpacesBySpaceIdComputersCreate", "description": "Create a new computer in the space", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" } }, "required": [ "computerId" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "blaxel-sandbox", "kernel-computer" ] } }, "required": [ "type" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/add-remote": { "post": { "operationId": "postSpacesBySpaceIdComputersAddRemote", "description": "Add a remote computer with a linking token", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" }, "linkingToken": { "type": "string" }, "expiresAt": { "type": "number" } }, "required": [ "computerId", "linkingToken", "expiresAt" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "platform": { "type": "string" } }, "required": [ "label" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/diagnostics": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdDiagnostics", "description": "Record desktop app fallback diagnostics for a computer", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger": { "type": "string", "enum": [ "server-link-unusable", "local-daemon-unreachable", "credential-push-failed", "daemon-bootstrap-failed" ] }, "observedAt": { "type": "number" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "trigger", "observedAt", "payload" ] } } } } } }, "/spaces/{spaceId}/computers/{computerId}": { "get": { "operationId": "getSpacesBySpaceIdComputersByComputerId", "summary": "Get computer", "description": "Get a computer by ID", "tags": [ "computers" ], "responses": { "200": { "description": "Computer row" }, "404": { "description": "Computer not found" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "patch": { "operationId": "patchSpacesBySpaceIdComputersByComputerId", "summary": "Update computer", "description": "Update a computer (label, desktop_enabled)", "tags": [ "computers" ], "responses": { "200": { "description": "Updated computer row" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "desktop_enabled": { "type": "boolean" } } } } } } }, "delete": { "operationId": "deleteSpacesBySpaceIdComputersByComputerId", "description": "Delete a computer", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/uninstall": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdUninstall", "description": "Schedule device deletion — only if zero memberships remain", "tags": [ "computers" ], "responses": { "200": { "description": "Device scheduled for deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "409": { "description": "Memberships still exist" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/stats": { "get": { "operationId": "getSpacesBySpaceIdComputersByComputerIdStats", "summary": "Get computer stats", "description": "Get CPU, memory, and disk usage for a computer", "tags": [ "computers" ], "responses": { "200": { "description": "Resource usage stats" }, "400": { "description": "Computer does not support stats" }, "500": { "description": "Internal error" }, "503": { "description": "Computer not connected" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/wake": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdWake", "description": "Wake a specific computer by ID", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "ok", "id" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/repair": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdRepair", "description": "Repair a specific computer by ID", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/stop": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdStop", "description": "Stop a specific computer", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/ensure-latest": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdEnsureLatest", "description": "Ask a daemon-backed computer to update to the latest available app or daemon version", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": {} }, "required": [ "result" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "kazzle", "daemon" ] } } } } } } } }, "/spaces/{spaceId}/computers/{computerId}/ensure-latest-app": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdEnsureLatestApp", "description": "Compatibility alias for installed clients; use /ensure-latest for new computer update calls", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": {} }, "required": [ "result" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/check-updates": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdCheckUpdates", "description": "Ask a daemon-backed computer to check for app or daemon updates without installing them", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": {} }, "required": [ "result" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "kazzle", "daemon" ] } } } } } } } }, "/spaces/{spaceId}/computers/{computerId}/check-app-updates": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdCheckAppUpdates", "description": "Compatibility alias for installed clients; use /check-updates for new computer update checks", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": {} }, "required": [ "result" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/unlink": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdUnlink", "description": "Unlink a computer (revoke machine token and mark the lifecycle unlinked)", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/destroy": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdDestroy", "description": "Schedule computer deletion", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/screenshot": { "get": { "operationId": "getSpacesBySpaceIdComputersByComputerIdScreenshot", "summary": "Screenshot computer desktop", "description": "Take a screenshot of the computer desktop", "tags": [ "computers" ], "responses": { "200": { "description": "Screenshot data" }, "400": { "description": "Computer does not support desktop" }, "404": { "description": "Live session not found" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "sessionId", "schema": { "type": "string", "minLength": 1 }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/terminals/reconcile": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdTerminalsReconcile", "description": "Reconcile managed terminal processes for a computer", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/live-sessions": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdLiveSessions", "summary": "Create live session", "description": "Create a live session on a computer (virtual display)", "tags": [ "computers" ], "responses": { "200": { "description": "Created live session" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "resolution": { "type": "string" } } } } } } } }, "/spaces/{spaceId}/computers/{computerId}/live-sessions/{sessionId}": { "get": { "operationId": "getSpacesBySpaceIdComputersByComputerIdLiveSessionsBySessionId", "summary": "Get live session", "description": "Get an active live session on a computer", "tags": [ "computers" ], "responses": { "200": { "description": "Live session" }, "401": { "description": "Authentication required" }, "404": { "description": "Live session not found" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "sessionId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdComputersByComputerIdLiveSessionsBySessionId", "description": "End a live session on a computer", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "computerId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "sessionId", "required": true } ] } }, "/spaces/{spaceId}/computers/terminals/{sessionId}": { "delete": { "operationId": "deleteSpacesBySpaceIdComputersTerminalsBySessionId", "description": "Kill and delete a terminal session", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "sessionId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/terminals/{sessionId}/input": { "post": { "operationId": "postSpacesBySpaceIdComputersTerminalsBySessionIdInput", "description": "Write input to an active terminal session", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "sessionId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": [ "data" ] } } } } } }, "/spaces/{spaceId}/computers/register": { "post": { "operationId": "postSpacesBySpaceIdComputersRegister", "summary": "Register client computer", "description": "Auto-register an Electron client computer on startup", "tags": [ "computers" ], "responses": { "200": { "description": "Registered computer" }, "401": { "description": "Authentication required" }, "500": { "description": "Internal error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" }, "label": { "type": "string" }, "deviceId": { "type": "string" }, "appVersion": { "type": "string" }, "config": { "type": "object", "properties": { "canRunProcesses": { "type": "boolean" }, "canHostRepos": { "type": "boolean" }, "canHostAppDev": { "type": "boolean" }, "git": { "type": "object", "properties": { "clone": { "type": "boolean" } }, "required": [ "clone" ] }, "lifecycle": { "type": "object", "properties": { "canWake": { "type": "boolean" }, "canStop": { "type": "boolean" } }, "required": [ "canWake", "canStop" ] }, "terminals": { "type": "object", "properties": { "show": { "type": "boolean" }, "canCreate": { "type": "boolean" }, "canConnect": { "type": "boolean" }, "canEnable": { "type": "boolean" }, "canCreateSession": { "type": "boolean" }, "canEdit": { "type": "boolean" } }, "required": [ "show" ] }, "browsers": { "type": "object", "properties": { "show": { "type": "boolean" }, "canCreate": { "type": "boolean" }, "canConnect": { "type": "boolean" }, "canEnable": { "type": "boolean" }, "canCreateSession": { "type": "boolean" }, "canEdit": { "type": "boolean" } }, "required": [ "show" ] }, "desktop": { "type": "object", "properties": { "available": { "type": "boolean" }, "canEnable": { "type": "boolean" }, "view": { "type": "object", "properties": { "screenshot": { "type": "boolean" }, "displays": { "type": "boolean" } }, "required": [ "screenshot", "displays" ] }, "input": { "type": "object", "properties": { "physical": { "type": "boolean" } }, "required": [ "physical" ] }, "app": { "type": "object", "properties": { "controlled": { "type": "boolean" } }, "required": [ "controlled" ] }, "workspace": { "type": "object", "properties": { "virtual": { "type": "boolean" }, "create": { "type": "boolean" } }, "required": [ "virtual", "create" ] }, "window": { "type": "object", "properties": { "place": { "type": "boolean" }, "multiDisplay": { "type": "boolean" } }, "required": [ "place", "multiDisplay" ] } }, "required": [ "available", "view", "input", "app", "workspace", "window" ] }, "snapshots": { "type": "object", "properties": { "show": { "type": "boolean" }, "canEnable": { "type": "boolean" } }, "required": [ "show", "canEnable" ] }, "workspacePath": { "type": "object", "properties": { "show": { "type": "boolean" }, "canEdit": { "type": "boolean" } }, "required": [ "show", "canEdit" ] }, "apps": { "type": "object", "properties": { "show": { "type": "boolean" } }, "required": [ "show" ] }, "deviceMethods": { "type": "object", "properties": { "protocolVersion": { "type": "number" }, "runtime": { "type": "string", "enum": [ "daemon", "mobile" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "runtimeVersion": { "type": "string" }, "buildSha": { "type": "string" }, "builtAt": { "type": "string" } }, "required": [ "protocolVersion", "runtime", "methods" ] } }, "required": [ "canRunProcesses", "terminals", "browsers", "desktop" ] }, "capabilities": { "type": "object", "properties": { "terminal": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] }, "fs": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] }, "process": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] }, "git": { "type": "object", "properties": { "clone": { "type": "boolean" } }, "required": [ "clone" ] }, "browser": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] }, "snapshot": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] }, "desktop": { "type": "object", "properties": { "available": { "type": "boolean" }, "view": { "type": "object", "properties": { "screenshot": { "type": "boolean" }, "displays": { "type": "boolean" } }, "required": [ "screenshot", "displays" ] }, "input": { "type": "object", "properties": { "physical": { "type": "boolean" } }, "required": [ "physical" ] }, "app": { "type": "object", "properties": { "controlled": { "type": "boolean" } }, "required": [ "controlled" ] }, "workspace": { "type": "object", "properties": { "virtual": { "type": "boolean" }, "create": { "type": "boolean" } }, "required": [ "virtual", "create" ] }, "window": { "type": "object", "properties": { "place": { "type": "boolean" }, "multiDisplay": { "type": "boolean" } }, "required": [ "place", "multiDisplay" ] } }, "required": [ "available", "view", "input", "app", "workspace", "window" ] }, "deviceMethods": { "type": "object", "properties": { "protocolVersion": { "type": "number" }, "runtime": { "type": "string", "enum": [ "daemon", "mobile" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "runtimeVersion": { "type": "string" }, "buildSha": { "type": "string" }, "builtAt": { "type": "string" } }, "required": [ "protocolVersion", "runtime", "methods" ] } } } }, "required": [ "platform", "label", "deviceId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/computers/{computerId}/rpc": { "post": { "operationId": "postSpacesBySpaceIdComputersByComputerIdRpc", "description": "Generic RPC proxy to daemon via server-link WebSocket", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": {} }, "required": [ "result" ] } } } } }, "parameters": [ { "in": "path", "name": "computerId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "method" ] } } } } } }, "/computers/link": { "post": { "operationId": "postComputersLink", "description": "Link a remote computer using a linking token (kl_*)", "tags": [ "computers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" }, "machineToken": { "type": "string" }, "spaceId": { "type": "string" }, "spaceName": { "type": "string" }, "spaceLogoPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "logoPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "logoPath" ] } } }, "required": [ "computerId", "machineToken", "spaceId", "spaceName", "spaceLogoPath", "spaces" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 } }, "required": [ "token", "platform", "label", "deviceId" ] } } } } } }, "/computers/cleanup-tokens": { "post": { "operationId": "postComputersCleanupTokens", "description": "Clean up expired linking tokens (called by cron or server startup)", "tags": [ "computers" ], "responses": {} } }, "/computers/{computerId}/sync-token": { "post": { "operationId": "postComputersByComputerIdSyncToken", "description": "Issue an app-sync-compatible JWT for a machine-token-authenticated computer", "tags": [ "computers" ], "responses": {}, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "computerId", "required": true } ] } }, "/computers/{computerId}/auth/bootstrap": { "post": { "operationId": "postComputersByComputerIdAuthBootstrap", "description": "Bootstrap a computer session using HMAC token (kd_*). Returns session + JWT.", "tags": [ "computers" ], "responses": {}, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "computerId", "required": true } ] } }, "/computers/auth/refresh": { "post": { "operationId": "postComputersAuthRefresh", "description": "Refresh a computer JWT using the session token. Returns a new JWT.", "tags": [ "computers" ], "responses": {} } }, "/spaces/{spaceId}/browsers/tabs/{browserTabId}/focus": { "post": { "operationId": "postSpacesBySpaceIdBrowsersTabsByBrowserTabIdFocus", "description": "Focus a browser tab on its owning computer/provider", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "browserTabId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/profiles": { "get": { "operationId": "getSpacesBySpaceIdBrowsersProfiles", "summary": "List browser profiles", "description": "List all browser profiles for the space", "tags": [ "browsers" ], "responses": { "200": { "description": "Browser profile rows" }, "500": { "description": "Internal error" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/profiles/{profileId}": { "get": { "operationId": "getSpacesBySpaceIdBrowsersProfilesByProfileId", "summary": "Get browser profile", "description": "Get a specific profile with its active sessions", "tags": [ "browsers" ], "responses": { "200": { "description": "Profile with active sessions" }, "404": { "description": "Profile not found" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "profileId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdBrowsersProfilesByProfileId", "description": "Delete a profile (cascades sessions + tabs)", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "profileId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/extension/connect": { "post": { "operationId": "postSpacesBySpaceIdBrowsersExtensionConnect", "description": "Connect a browser extension — creates/finds profile and starts session", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "id": { "type": "string" }, "computerId": { "type": "string" }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "providerRef": { "type": "string" } }, "required": [ "id", "computerId", "spaceId", "name", "provider", "providerRef" ] }, "session": { "type": "object", "properties": { "id": { "type": "string" }, "profileId": { "type": "string" }, "computerId": { "type": "string" }, "spaceId": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "profileId", "computerId", "spaceId", "provider", "status" ] } }, "required": [ "profile", "session" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" }, "browser": { "type": "string" }, "profilePath": { "type": "string" } }, "required": [ "computerId", "browser" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/extension/disconnect": { "post": { "operationId": "postSpacesBySpaceIdBrowsersExtensionDisconnect", "description": "Disconnect browser extension — ends session and deletes profile", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profileId": { "type": "string" } }, "required": [ "profileId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/extension/command": { "post": { "operationId": "postSpacesBySpaceIdBrowsersExtensionCommand", "description": "Send a command to a connected browser extension", "tags": [ "browsers" ], "responses": {}, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/sessions": { "get": { "operationId": "getSpacesBySpaceIdBrowsersSessions", "summary": "List browser sessions", "description": "List all active browser sessions for the space", "tags": [ "browsers" ], "responses": { "200": { "description": "Active browser sessions" }, "500": { "description": "Internal error" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "post": { "operationId": "postSpacesBySpaceIdBrowsersSessions", "description": "Create a new browser session on a computer", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" }, "sessionId": { "type": "string" }, "url": { "type": "string" } }, "required": [ "computerId", "sessionId", "url" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" } }, "required": [ "computerId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/sessions/{sessionId}": { "delete": { "operationId": "deleteSpacesBySpaceIdBrowsersSessionsBySessionId", "description": "End a browser session", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "sessionId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/sessions/{sessionId}/tabs": { "get": { "operationId": "getSpacesBySpaceIdBrowsersSessionsBySessionIdTabs", "summary": "List session tabs", "description": "Get tabs for a browser session", "tags": [ "browsers" ], "responses": { "200": { "description": "Tab rows for the session" }, "500": { "description": "Internal error" } }, "parameters": [ { "in": "path", "name": "sessionId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/verification/availability": { "get": { "operationId": "getSpacesBySpaceIdBrowsersVerificationAvailability", "description": "Whether automatic challenge verification is available in this Kazzle environment", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" } }, "required": [ "available" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/tabs/{browserTabId}/challenge/solve": { "post": { "operationId": "postSpacesBySpaceIdBrowsersTabsByBrowserTabIdChallengeSolve", "description": "Solve a Turnstile/reCAPTCHA v2 challenge on a browser tab via CapSolver", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "providerTaskId": { "type": "string" }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "skipped": { "type": "boolean" }, "reason": { "type": "string" }, "durationMs": { "type": "number" } } } } } } }, "parameters": [ { "in": "path", "name": "browserTabId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeType": { "type": "string", "enum": [ "turnstile", "recaptcha_v2", "recaptcha_v3", "recaptcha_enterprise", "hcaptcha" ] }, "siteKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "pageUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "action": { "type": "string", "maxLength": 200 }, "cData": { "type": "string", "maxLength": 2000 }, "pageData": { "type": "string", "maxLength": 5000 }, "isInvisible": { "type": "boolean" }, "idempotencyKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "navigationGeneration": { "type": "string", "maxLength": 200 }, "frameId": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "challengeType", "siteKey", "pageUrl", "idempotencyKey" ] } } } } } }, "/spaces/{spaceId}/browsers/tabs/{browserTabId}/challenge/clear": { "post": { "operationId": "postSpacesBySpaceIdBrowsersTabsByBrowserTabIdChallengeClear", "description": "Acknowledge that a browser challenge cleared on the page (prices CapSolver billing)", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "priced": { "type": "boolean" }, "attemptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "priced", "attemptId" ] } } } } }, "parameters": [ { "in": "path", "name": "browserTabId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attemptId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "navigationGeneration": { "type": "string", "maxLength": 200 }, "frameId": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "attemptId" ] } } } } } }, "/spaces/{spaceId}/browsers/tabs/{browserTabId}/challenge/abandon": { "post": { "operationId": "postSpacesBySpaceIdBrowsersTabsByBrowserTabIdChallengeAbandon", "description": "Abandon an in-flight browser challenge (navigation / close / timeout)", "tags": [ "browsers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "abandoned": { "type": "boolean" } }, "required": [ "abandoned" ] } } } } }, "parameters": [ { "in": "path", "name": "browserTabId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 200 } } } } } } } }, "/spaces/{spaceId}/browsers/profiles/{profileId}/proxy/enable": { "post": { "operationId": "postSpacesBySpaceIdBrowsersProfilesByProfileIdProxyEnable", "summary": "Enable browser proxy", "description": "Allocate a sticky proxy assignment for this profile and apply it", "tags": [ "browsers" ], "responses": { "200": { "description": "Proxy status", "content": { "application/json": { "schema": { "type": "object", "properties": { "proxyConfig": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "country": { "type": "string" }, "assignmentRef": { "type": "string" } }, "required": [ "provider", "country" ] }, { "type": "null" } ] }, "proxyState": { "type": "string" }, "proxyReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proxyCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "proxyConfig", "proxyState", "proxyReason", "proxyCheckedAt" ] } } } } }, "parameters": [ { "in": "path", "name": "profileId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[a-z]{2}$" } } } } } } } }, "/spaces/{spaceId}/browsers/profiles/{profileId}/proxy/disable": { "post": { "operationId": "postSpacesBySpaceIdBrowsersProfilesByProfileIdProxyDisable", "summary": "Disable browser proxy", "description": "Clear desired proxy and browse directly", "tags": [ "browsers" ], "responses": { "200": { "description": "Proxy status", "content": { "application/json": { "schema": { "type": "object", "properties": { "proxyConfig": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "country": { "type": "string" }, "assignmentRef": { "type": "string" } }, "required": [ "provider", "country" ] }, { "type": "null" } ] }, "proxyState": { "type": "string" }, "proxyReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proxyCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "proxyConfig", "proxyState", "proxyReason", "proxyCheckedAt" ] } } } } }, "parameters": [ { "in": "path", "name": "profileId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/profiles/{profileId}/proxy/retry": { "post": { "operationId": "postSpacesBySpaceIdBrowsersProfilesByProfileIdProxyRetry", "summary": "Retry browser proxy", "description": "Re-apply the desired proxy after a fallback", "tags": [ "browsers" ], "responses": { "200": { "description": "Proxy status", "content": { "application/json": { "schema": { "type": "object", "properties": { "proxyConfig": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "country": { "type": "string" }, "assignmentRef": { "type": "string" } }, "required": [ "provider", "country" ] }, { "type": "null" } ] }, "proxyState": { "type": "string" }, "proxyReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proxyCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "proxyConfig", "proxyState", "proxyReason", "proxyCheckedAt" ] } } } } }, "parameters": [ { "in": "path", "name": "profileId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/profiles/{profileId}/proxy/rotate": { "post": { "operationId": "postSpacesBySpaceIdBrowsersProfilesByProfileIdProxyRotate", "summary": "Rotate browser proxy identity", "description": "Allocate a new sticky proxy assignment for this profile (new egress identity)", "tags": [ "browsers" ], "responses": { "200": { "description": "Proxy status", "content": { "application/json": { "schema": { "type": "object", "properties": { "proxyConfig": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string" }, "country": { "type": "string" }, "assignmentRef": { "type": "string" } }, "required": [ "provider", "country" ] }, { "type": "null" } ] }, "proxyState": { "type": "string" }, "proxyReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "proxyCheckedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "proxyConfig", "proxyState", "proxyReason", "proxyCheckedAt" ] } } } } }, "parameters": [ { "in": "path", "name": "profileId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/import/detect": { "post": { "operationId": "postSpacesBySpaceIdBrowsersImportDetect", "summary": "Detect browsers", "description": "Detect installed browsers and their profiles on the user device. Runs on the user's daemon (`computerId`). Body: `{ computerId }`.", "tags": [ "browser-import" ], "responses": { "200": { "description": "Detected browsers and profiles" }, "401": { "description": "Not authenticated" }, "500": { "description": "Detect failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" } }, "required": [ "computerId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/import/scan": { "post": { "operationId": "postSpacesBySpaceIdBrowsersImportScan", "summary": "Scan browser profile", "description": "Dry-run scan via daemon — returns item counts without importing. Body: `{ computerId, browser, profile, include?, masterPassword?, passwordsCsvPath? }`.", "tags": [ "browser-import" ], "responses": { "200": { "description": "Import counts; returns `{ counts }`" }, "401": { "description": "Not authenticated" }, "500": { "description": "Scan failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" }, "browser": { "type": "string" }, "profile": { "type": "string" }, "include": { "type": "array", "items": { "type": "string" } }, "masterPassword": { "type": "string" }, "passwordsCsvPath": { "type": "string" } }, "required": [ "computerId", "browser", "profile" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/browsers/import/run": { "post": { "operationId": "postSpacesBySpaceIdBrowsersImportRun", "summary": "Run browser import", "description": "Run the actual import — daemon reads + decrypts the profile locally, server runs the ingest pipeline. Cookies are returned to the desktop app for local cookie-jar write. Body: `{ computerId, browser, profile, include?, masterPassword?, passwordsCsvPath? }`.", "tags": [ "browser-import" ], "responses": { "200": { "description": "Import result" }, "401": { "description": "Not authenticated" }, "500": { "description": "Import failed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "computerId": { "type": "string" }, "browser": { "type": "string" }, "profile": { "type": "string" }, "include": { "type": "array", "items": { "type": "string" } }, "masterPassword": { "type": "string" }, "passwordsCsvPath": { "type": "string" } }, "required": [ "computerId", "browser", "profile" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/billing/{spaceId}/setup": { "post": { "operationId": "postBillingBySpaceIdSetup", "description": "Set up billing for a space (idempotent)", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "initialCredits": { "type": "number" } } } } } } } }, "/billing/{spaceId}/top-up": { "post": { "operationId": "postBillingBySpaceIdTopUp", "description": "Create a Polar checkout session for wallet top-up", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "amount" ] } } } } } }, "/billing/{spaceId}/subscribe": { "post": { "operationId": "postBillingBySpaceIdSubscribe", "description": "Create a Polar checkout session for a subscription plan", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "changed": { "type": "boolean" } } } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planKey": { "type": "string", "enum": [ "basic", "pro", "ultra" ] } }, "required": [ "planKey" ] } } } } } }, "/billing/{spaceId}/change-plan": { "post": { "operationId": "postBillingBySpaceIdChangePlan", "description": "Change an existing Polar subscription to a different plan", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planKey": { "type": "string", "enum": [ "basic", "pro", "ultra" ] } }, "required": [ "planKey" ] } } } } } }, "/billing/checkout-success": { "get": { "operationId": "getBillingCheckoutSuccess", "description": "Handle Polar checkout success redirect", "tags": [ "billing" ], "responses": {}, "parameters": [ { "in": "query", "name": "amount", "schema": { "type": "number" } } ] } }, "/billing/checkout-cancel": { "get": { "operationId": "getBillingCheckoutCancel", "description": "Handle checkout cancellation redirect", "tags": [ "billing" ], "responses": {} } }, "/billing/{spaceId}/portal": { "post": { "operationId": "postBillingBySpaceIdPortal", "description": "Get a Polar customer portal URL", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnUrl": { "type": "string" } } } } } } } }, "/billing/{spaceId}/enforcement": { "post": { "operationId": "postBillingBySpaceIdEnforcement", "description": "Toggle billing enforcement for a space", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "disabled": { "type": "boolean" } }, "required": [ "ok", "disabled" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "type": "boolean" } }, "required": [ "disabled" ] } } } } } }, "/billing/{spaceId}/usage": { "get": { "operationId": "getBillingBySpaceIdUsage", "description": "Get usage summary + paginated events for a billing period", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalMicro": { "type": "number" }, "periodStart": { "type": "number" }, "periodEnd": { "type": "number" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "totalMicro": { "type": "number" }, "eventCount": { "type": "number" } }, "required": [ "category", "totalMicro", "eventCount" ] } }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "eventCode": { "type": "string" }, "costMicro": { "type": "number" }, "properties": {}, "threadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number" } }, "required": [ "id", "category", "eventCode", "costMicro", "properties", "threadId", "createdAt" ] } }, "eventsTotal": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "totalMicro", "periodStart", "periodEnd", "categories", "events", "eventsTotal", "limit", "offset" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "periodStart", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "in": "query", "name": "periodEnd", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "in": "query", "name": "category", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ] } }, "/billing/{spaceId}/reconcile": { "post": { "operationId": "postBillingBySpaceIdReconcile", "description": "Reconcile billing: refresh balances and self-heal subscription rows without recomputing IAP credits", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "balance": { "type": "number" } }, "required": [ "ok", "balance" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ] } }, "/billing/ai-rates": { "get": { "operationId": "getBillingAiRates", "description": "Per-model AI usage rates (all modalities) for the Usage rates table", "tags": [ "billing" ], "responses": { "200": { "description": "AI rates", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "pricingRates": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "credits": { "type": "string" }, "creditsPerUnit": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "label", "credits", "creditsPerUnit", "unit" ] } } }, "required": [ "id", "name", "provider", "pricingRates" ] } } }, "required": [ "models" ] } } } } } } }, "/billing/{spaceId}/spend-limit": { "post": { "operationId": "postBillingBySpaceIdSpendLimit", "description": "Set or clear monthly spend limit", "tags": [ "billing" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "ok", "limit" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "limit" ] } } } } } }, "/spaces/{spaceId}/skills/{id}/init": { "post": { "operationId": "postSpacesBySpaceIdSkillsByIdInit", "description": "Initialize a skill folder in managed storage", "tags": [ "skills" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "containerId": { "type": "string" }, "filePath": { "type": "string" } }, "required": [ "ok" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/spaces/{spaceId}/storages": { "get": { "operationId": "getSpacesBySpaceIdStorages", "description": "List all storages for a space", "tags": [ "storages" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": {} } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "post": { "operationId": "postSpacesBySpaceIdStorages", "description": "Create a new storage", "tags": [ "storages" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string" }, "bucket": { "type": "string" }, "prefix": { "type": "string" }, "credentialsId": { "type": "string" }, "endpoint": { "type": "string" }, "region": { "type": "string" } }, "required": [ "provider" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/storages/{storageId}": { "get": { "operationId": "getSpacesBySpaceIdStoragesByStorageId", "description": "Get a storage by ID", "tags": [ "storages" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": {} } } } }, "parameters": [ { "in": "path", "name": "storageId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdStoragesByStorageId", "description": "Delete a storage", "tags": [ "storages" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "storageId", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/storages/test-connection": { "post": { "operationId": "postSpacesBySpaceIdStoragesTestConnection", "description": "Test a storage connection", "tags": [ "storages" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": {} } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bucket": { "type": "string" }, "endpoint": { "type": "string" }, "region": { "type": "string" }, "accessKeyId": { "type": "string" }, "secretAccessKey": { "type": "string" } }, "required": [ "bucket", "accessKeyId", "secretAccessKey" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/storages/{containerId}/presigned-url": { "get": { "operationId": "getSpacesBySpaceIdStoragesByContainerIdPresignedUrl", "description": "Get a presigned URL for a storage container", "tags": [ "storages" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } }, "parameters": [ { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "path", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "op", "schema": { "type": "string", "enum": [ "get", "put" ] }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/containers/{containerId}/write": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdWrite", "description": "Write file contents to a container", "tags": [ "containers" ], "responses": { "200": { "description": "Write successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "content": { "default": "", "type": "string" }, "encoding": { "default": "utf-8", "type": "string" } }, "required": [ "path" ] } } } } } }, "/spaces/{spaceId}/containers/{containerId}/delete": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdDelete", "description": "Delete a file from a container", "tags": [ "containers" ], "responses": { "200": { "description": "Delete successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } }, "required": [ "path" ] } } } } } }, "/spaces/{spaceId}/containers/{containerId}/mkdir": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdMkdir", "description": "Create a directory in a container", "tags": [ "containers" ], "responses": { "200": { "description": "Directory created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } }, "required": [ "path" ] } } } } } }, "/spaces/{spaceId}/containers/{containerId}/rename": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdRename", "description": "Rename/move a file in a container", "tags": [ "containers" ], "responses": { "200": { "description": "Rename successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 } }, "required": [ "from", "to" ] } } } } } }, "/spaces/{spaceId}/containers/{containerId}/list": { "get": { "operationId": "getSpacesBySpaceIdContainersByContainerIdList", "summary": "List container directory", "description": "List directory contents in a container", "tags": [ "containers" ], "responses": { "200": { "description": "Directory entries" }, "500": { "description": "List failed" } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true }, { "in": "query", "name": "path", "schema": { "default": "", "type": "string" } } ] } }, "/spaces/{spaceId}/containers/{containerId}/soft-delete": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdSoftDelete", "description": "Soft-delete a file (move to trash)", "tags": [ "containers" ], "responses": { "200": { "description": "Soft-delete successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } }, "required": [ "path" ] } } } } } }, "/spaces/{spaceId}/containers/{containerId}/trash": { "get": { "operationId": "getSpacesBySpaceIdContainersByContainerIdTrash", "summary": "List container trash", "description": "List soft-deleted items in trash", "tags": [ "containers" ], "responses": { "200": { "description": "Trash items; returns `{ items, managedExternally }`" }, "500": { "description": "List failed" }, "501": { "description": "Trash not supported for this container" } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ] } }, "/spaces/{spaceId}/containers/{containerId}/trash/restore": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdTrashRestore", "description": "Restore a soft-deleted file from trash", "tags": [ "containers" ], "responses": { "200": { "description": "Restore successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } }, "required": [ "path" ] } } } } } }, "/spaces/{spaceId}/containers/{containerId}/trash/permanent-delete": { "post": { "operationId": "postSpacesBySpaceIdContainersByContainerIdTrashPermanentDelete", "description": "Permanently delete a file from trash", "tags": [ "containers" ], "responses": { "200": { "description": "Permanent delete successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "in": "path", "name": "spaceId", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "containerId", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } }, "required": [ "path" ] } } } } } }, "/spaces/{spaceId}/thread-files/upload": { "post": { "operationId": "postSpacesBySpaceIdThreadFilesUpload", "tags": [ "thread-files" ], "description": "Upload a file attachment to a thread (multipart)", "responses": { "200": { "description": "Uploaded file metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "fileName": { "type": "string" } }, "required": [ "containerId", "path", "mimeType", "fileName" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/thread-files/upload-base64": { "post": { "operationId": "postSpacesBySpaceIdThreadFilesUploadBase64", "tags": [ "thread-files" ], "description": "Upload a file attachment to a thread from a base64 JSON body", "responses": { "200": { "description": "Uploaded file metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "containerId": { "type": "string" }, "path": { "type": "string" }, "mimeType": { "type": "string" }, "fileName": { "type": "string" } }, "required": [ "containerId", "path", "mimeType", "fileName" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string", "minLength": 1 }, "base64": { "type": "string", "minLength": 1 }, "threadId": { "type": "string" } }, "required": [ "fileName", "mimeType", "base64" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/thread-files/content": { "get": { "operationId": "getSpacesBySpaceIdThreadFilesContent", "summary": "Stream thread file", "tags": [ "thread-files" ], "description": "Streams the bytes of a thread attachment from managed storage. Query param: `path` (container-relative). Served immutable + cacheable.", "responses": { "200": { "description": "File bytes" }, "400": { "description": "Missing path or spaceId" }, "401": { "description": "Not authenticated" }, "500": { "description": "Read failed" } }, "parameters": [ { "in": "query", "name": "path", "schema": { "type": "string" }, "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/support/messenger-jwt": { "get": { "operationId": "getSupportMessengerJwt", "summary": "Intercom messenger JWT", "description": "Returns a short-lived HS256 JWT identifying the authenticated user to the Intercom messenger (identity verification).", "tags": [ "Support" ], "responses": { "200": { "description": "Signed messenger token; returns `{ token }`" }, "401": { "description": "Not authenticated" }, "500": { "description": "Intercom secret not configured" } } } }, "/support/report": { "post": { "operationId": "postSupportReport", "summary": "Send support report", "description": "Creates an Intercom conversation from the authenticated user with the provided message. Body: `{ message }`.", "tags": [ "Support" ], "responses": { "200": { "description": "Report sent; returns `{ ok: true, conversationId }`" }, "400": { "description": "Message is required" }, "401": { "description": "Not authenticated" }, "404": { "description": "Intercom contact not found" }, "500": { "description": "Intercom not configured" }, "502": { "description": "Intercom request failed" } } } }, "/push/register": { "post": { "operationId": "postPushRegister", "summary": "Register push token", "description": "Registers a device push notification token for the authenticated user. Body: `{ token, platform, bundleId, computerId? }`.", "tags": [ "Push" ], "responses": { "200": { "description": "Token registered; returns `{ success: true }`" }, "400": { "description": "Missing token, platform, or bundleId" }, "401": { "description": "Not authenticated" } } }, "delete": { "operationId": "deletePushRegister", "summary": "Unregister push token", "description": "Removes a previously registered device push token. Body: `{ token }`.", "tags": [ "Push" ], "responses": { "200": { "description": "Token removed; returns `{ success: true }`" }, "400": { "description": "Missing token" }, "401": { "description": "Not authenticated" } } } }, "/spaces/{spaceId}/invitations": { "post": { "operationId": "postSpacesBySpaceIdInvitations", "summary": "Create space invitation", "description": "Admin invites a user to the space by email with a role. Sends an invitation email (skipped for test addresses). Expires after 7 days. Body: `{ email, role }`.", "tags": [ "Spaces" ], "responses": { "200": { "description": "Invitation created; returns `{ id }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Admin access required" }, "409": { "description": "Invitation already pending for this email" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "email", "role" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] }, "get": { "operationId": "getSpacesBySpaceIdInvitations", "summary": "List pending invitations", "description": "Admin lists pending (not yet accepted or revoked) invitations for the space.", "tags": [ "Spaces" ], "responses": { "200": { "description": "Pending invitations; returns `{ invitations[] }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Admin access required" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/invitations/{id}": { "delete": { "operationId": "deleteSpacesBySpaceIdInvitationsById", "summary": "Revoke invitation", "description": "Admin revokes a pending invitation by id (marks it revoked).", "tags": [ "Spaces" ], "responses": { "200": { "description": "Invitation revoked; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Admin access required" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/spaces/{spaceId}/members": { "get": { "operationId": "getSpacesBySpaceIdMembers", "summary": "List space members", "description": "Lists all memberships (user id + role) for the space.", "tags": [ "Spaces" ], "responses": { "200": { "description": "Members; returns `{ members[] }`" }, "401": { "description": "Not authenticated" }, "403": { "description": "Member access required" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true } ] } }, "/spaces/{spaceId}/members/{id}": { "patch": { "operationId": "patchSpacesBySpaceIdMembersById", "summary": "Change member role", "description": "Admin changes a member's role between admin and member. Refuses to demote the last admin. Body: `{ role }`.", "tags": [ "Spaces" ], "responses": { "200": { "description": "Role changed; returns `{ success: true }`" }, "400": { "description": "Cannot demote the last admin" }, "401": { "description": "Not authenticated" }, "403": { "description": "Admin access required" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "role" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] }, "delete": { "operationId": "deleteSpacesBySpaceIdMembersById", "summary": "Remove space member", "description": "Removes a member. Members can remove themselves; removing others requires admin. Refuses to remove the last admin. Disables that user's automations in the space.", "tags": [ "Spaces" ], "responses": { "200": { "description": "Member removed; returns `{ success: true }`" }, "400": { "description": "Cannot remove the last admin" }, "401": { "description": "Not authenticated" }, "403": { "description": "Admin access required" }, "404": { "description": "Membership not found" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "spaceId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } }, "/invitations/accept": { "post": { "operationId": "postInvitationsAccept", "summary": "Accept invitations", "description": "Accepts all pending invitations matching the authenticated user's email, creating space memberships and seeding bookmark roots. Returns the list of space ids joined.", "tags": [ "Spaces" ], "responses": { "200": { "description": "Invitations accepted; returns `{ accepted: spaceId[] }`" }, "400": { "description": "Could not resolve user email" }, "401": { "description": "Not authenticated" } } } }, "/account/avatar": { "post": { "operationId": "postAccountAvatar", "summary": "Upload account avatar", "description": "Uploads the authenticated user's profile image as `multipart/form-data` with a `file` part. Stores it in object storage and returns the stored key.", "tags": [ "Account" ], "responses": { "200": { "description": "Avatar stored; returns `{ key }`" }, "400": { "description": "No file provided" }, "401": { "description": "Not authenticated" }, "500": { "description": "Upload failed" } } }, "get": { "operationId": "getAccountAvatar", "summary": "Download account avatar", "description": "Proxy-downloads the authenticated user's avatar image bytes from object storage.", "tags": [ "Account" ], "responses": { "200": { "description": "Avatar image bytes" }, "401": { "description": "Not authenticated" }, "404": { "description": "No avatar set" }, "500": { "description": "Download failed" } } } }, "/account": { "delete": { "operationId": "deleteAccount", "summary": "Delete account", "description": "Permanently deletes the authenticated user. Spaces where the user is the sole admin are soft-deleted; otherwise the membership is removed. Cascades user-owned rows (push tokens, API keys, settings, browser history, automations) and the auth user.", "tags": [ "Account" ], "responses": { "200": { "description": "Account deleted; returns `{ success: true }`" }, "401": { "description": "Not authenticated" }, "500": { "description": "Deletion failed" } } } }, "/unfurl": { "post": { "operationId": "postUnfurl", "summary": "Unfurl a link", "description": "Fetches an external URL and extracts OpenGraph metadata (title, description, image, site name, favicon) for link previews. Results are cached in Redis for 24h. SSRF-safe: private/loopback URLs are rejected. Body: `{ url }`.", "tags": [ "Unfurl" ], "responses": { "200": { "description": "Unfurl metadata `{ title, description, image, siteName, favicon, url }` (fields may be null)" }, "400": { "description": "Invalid or private URL" }, "401": { "description": "Not authenticated" } } } } } }