{ "openapi": "3.1.2", "info": { "title": "v0 API", "description": "Development documentation", "version": "2.0.0" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false }, "Chat": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Unique chat identifier." }, "title": { "description": "Chat title, if generated.", "type": "string" }, "privacy": { "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ], "description": "Visibility setting of the chat." }, "createdAt": { "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))$", "description": "ISO timestamp of when the chat was created." }, "updatedAt": { "description": "ISO timestamp of when the chat was last updated.", "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))$" }, "authorId": { "type": "string", "description": "ID of the user who created the chat." }, "vercelProjectId": { "description": "Associated Vercel project ID, if any.", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "User-defined key-value metadata." }, "writePermission": { "type": "boolean", "description": "Whether the caller has write access to this chat." } }, "required": [ "id", "privacy", "createdAt", "authorId", "metadata", "writePermission" ], "additionalProperties": false }, "ChatWithUsage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chat": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique chat identifier." }, "title": { "description": "Chat title, if generated.", "type": "string" }, "privacy": { "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ], "description": "Visibility setting of the chat." }, "createdAt": { "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))$", "description": "ISO timestamp of when the chat was created." }, "updatedAt": { "description": "ISO timestamp of when the chat was last updated.", "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))$" }, "authorId": { "type": "string", "description": "ID of the user who created the chat." }, "vercelProjectId": { "description": "Associated Vercel project ID, if any.", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "User-defined key-value metadata." }, "writePermission": { "type": "boolean", "description": "Whether the caller has write access to this chat." } }, "required": [ "id", "privacy", "createdAt", "authorId", "metadata", "writePermission" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost for prompt." } }, "required": [ "chat", "usage" ], "additionalProperties": false, "description": "A chat response that also reports the usage." }, "AsyncChat": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chatId": { "type": "string", "description": "Unique chat identifier." }, "messageId": { "type": "string", "description": "ID of the assistant message that will receive the response. Poll this message by ID and check its finishReason field to detect completion." } }, "required": [ "chatId", "messageId" ], "additionalProperties": false }, "ChatStreamEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique chat identifier." }, "title": { "description": "Chat title, if generated.", "type": "string" }, "privacy": { "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ], "description": "Visibility setting of the chat." }, "createdAt": { "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))$", "description": "ISO timestamp of when the chat was created." }, "updatedAt": { "description": "ISO timestamp of when the chat was last updated.", "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))$" }, "authorId": { "type": "string", "description": "ID of the user who created the chat." }, "vercelProjectId": { "description": "Associated Vercel project ID, if any.", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "User-defined key-value metadata." }, "writePermission": { "type": "boolean", "description": "Whether the caller has write access to this chat." }, "object": { "type": "string", "enum": [ "chat" ], "description": "Discriminator: a chat-state snapshot." } }, "required": [ "id", "privacy", "createdAt", "authorId", "metadata", "writePermission", "object" ], "additionalProperties": false, "description": "Initial and final chat-state event. Emitted once at stream open with the freshly-created chat, and once at stream close with the chat including the completed assistant message." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Chat ID." }, "object": { "type": "string", "enum": [ "chat.title" ], "description": "Discriminator." }, "delta": { "type": "string", "description": "Full title string at this point in the stream." } }, "required": [ "id", "object", "delta" ], "additionalProperties": false, "description": "Emitted when the chat title is (re)generated." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Assistant message ID." }, "object": { "type": "string", "enum": [ "message.parts.chunk" ], "description": "Discriminator." }, "delta": { "description": "jsondiffpatch delta to apply against the running public `Message.parts` array. Apply each delta in order to reconstruct the complete current parts snapshot." } }, "required": [ "id", "object", "delta" ], "additionalProperties": false, "description": "Incremental update to the assistant message content." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Assistant message ID this usage applies to." }, "object": { "type": "string", "enum": [ "message.usage" ], "description": "Discriminator." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not generated tokens." } }, "required": [ "id", "object", "usage" ], "additionalProperties": false, "description": "Final token usage and credit cost for the assistant message produced by this stream. Emitted once after the message finishes generating, before the closing state event." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Assistant message ID or chat ID, depending on what is in scope when the error is raised." }, "object": { "type": "string", "enum": [ "error" ], "description": "Discriminator." }, "message": { "type": "string", "description": "Human-readable stream error message." }, "code": { "description": "Optional machine-readable stream error code.", "type": "string" } }, "required": [ "id", "object", "message" ], "additionalProperties": false, "description": "Emitted when a stream error occurs after the SSE response begins." } ], "description": "A single Server-Sent Events payload emitted by streaming chat endpoints. Each SSE event is `data: \\n\\n` where the JSON conforms to one of the union members." }, "Message": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier." }, "chatId": { "type": "string", "description": "ID of the chat this message belongs to." }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who produced this message." }, "createdAt": { "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))$", "description": "ISO timestamp when the message was created." }, "updatedAt": { "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))$", "description": "ISO timestamp when the message was last updated." }, "content": { "type": "string", "description": "The trailing prose of the message — the agent’s closing summary, or the user’s message text. Empty string when there is no closing prose." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Markdown prose written by the agent or user." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A block of text output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "text": { "type": "string", "description": "The agent's reasoning trace." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Extended thinking output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-read" ] }, "paths": { "type": "array", "items": { "type": "string" }, "description": "The file paths the agent read in this step." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "paths" ], "additionalProperties": false, "description": "Files read by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-edit" ] }, "operation": { "type": "string", "enum": [ "create", "update", "delete", "rename", "patch" ], "description": "The type of file edit performed." }, "path": { "type": "string", "description": "The target file path." }, "toPath": { "description": "The new path when operation is \"rename\".", "type": "string" }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "operation", "path" ], "additionalProperties": false, "description": "The agent created, modified, deleted, renamed, or patched a file." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "scope": { "type": "string", "enum": [ "repo", "web" ], "description": "Whether the agent searched the repository or the web." }, "query": { "type": "string", "description": "The search query." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "scope", "query" ], "additionalProperties": false, "description": "The agent searched for something." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bash" ] }, "command": { "type": "string", "description": "The shell command that was executed." }, "output": { "description": "Combined stdout/stderr captured from the terminal. May be empty if the command produced no output.", "type": "string" }, "exitCode": { "description": "Process exit code, when available. Reserved for future use; currently always omitted.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isDangerous": { "description": "True if the command was flagged as potentially dangerous and required explicit user approval.", "type": "boolean" }, "timeoutMs": { "description": "Command timeout in milliseconds, when configured.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "command" ], "additionalProperties": false, "description": "The agent ran a shell command." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "name": { "type": "string", "description": "The name of the tool that was invoked (e.g. an MCP tool name or built-in tool identifier)." }, "input": { "description": "The arguments passed to the tool. Schema depends on the specific tool." }, "output": { "description": "The result returned by the tool. Schema depends on the specific tool." }, "status": { "type": "string", "enum": [ "ok", "error" ], "description": "Whether the tool call succeeded or returned an error." }, "suggestedPermissions": { "description": "Present when the agent is blocked waiting for you to approve this tool call (for example, running a setup or migration script). Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task to approve. Omitted once the tool has run.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ], "description": "Permission grant type." }, "toolName": { "type": "string", "description": "The tool this permission authorizes." }, "input": { "description": "The tool input this permission authorizes. Pass back unchanged when resolving." }, "taskNameActive": { "description": "Internal label for the in-progress task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskNameComplete": { "description": "Internal label for the completed task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userMessage": { "description": "Optional message associated with the permission.", "type": "string" } }, "required": [ "type", "toolName" ], "additionalProperties": false, "description": "A permission the agent is waiting for you to grant. Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task." } }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "status" ], "additionalProperties": false, "description": "The agent invoked a tool (MCP, integration, or other dynamic tool). For shell commands, use the \"bash\" part instead." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-action" ] }, "name": { "type": "string", "description": "Stable identifier for the action (e.g. \"generate_image\", \"manage_todos\", \"diagnostics\"). See documentation for the registry of known names." }, "summary": { "type": "string", "description": "A short human-readable summary of what happened. Always populated so clients can render something even without knowing the action name." }, "data": { "description": "Structured payload for input-requesting actions. Present on `ask_user_questions`, `exit_plan_mode`, `get_or_request_integration`, and `configure_vercel_connect` parts when the agent is waiting on you; narrow by the part `name`. Omitted for actions that do not carry structured data.", "anyOf": [ { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Question identifier. Pass back as `questionId` when resolving with an `answered-questions` task." }, "question": { "type": "string", "description": "The full question text." }, "header": { "type": "string", "description": "Short label for the question." }, "multiSelect": { "type": "boolean", "description": "Whether more than one option may be selected." }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Option identifier." }, "label": { "type": "string", "description": "Display label. Pass matching labels back in `selectedLabels` when resolving." }, "description": { "description": "Optional longer explanation of the option.", "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, "description": "The available answer options." } }, "required": [ "id", "question", "header", "multiSelect", "options" ], "additionalProperties": false }, "description": "The questions the agent is waiting for answers to. Resolve with an `answered-questions` task." } }, "required": [ "questions" ], "additionalProperties": false, "description": "Structured payload for an `ask_user_questions` agent action." }, { "type": "object", "properties": { "plan": { "type": "string", "description": "The full proposed plan, as Markdown." }, "summary": { "description": "A concise summary of the plan, when available.", "type": "string" }, "path": { "type": "string", "description": "The path the plan applies to." } }, "required": [ "plan", "path" ], "additionalProperties": false, "description": "Structured payload for an `exit_plan_mode` agent action." }, { "type": "object", "properties": { "requestedIntegrations": { "type": "array", "items": { "type": "string" }, "description": "Integration names the agent is asking you to connect (for example, \"Neon\"). Pass these back in `connectedIntegrationNames` when resolving with a `confirmed-steps` task." }, "requestedMcpPresets": { "type": "array", "items": { "type": "string" }, "description": "MCP preset names the agent is asking you to add. Pass these back in `connectedMcpPresetNames` when resolving with a `confirmed-steps` task." } }, "required": [ "requestedIntegrations", "requestedMcpPresets" ], "additionalProperties": false, "description": "Structured payload for a `get_or_request_integration` agent action." }, { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "setup-required" ], "description": "The agent is waiting for connector setup to be completed in a browser." }, "requestId": { "type": "string", "description": "Setup request identifier. Pass as `requestId` to GET /chats/{chatId}/connect/status to poll for completion." }, "service": { "type": "string", "description": "The service being connected (for example, \"linear\")." }, "serviceIconUrl": { "description": "Icon URL for the service, hosted on vercel.com.", "type": "string", "format": "uri" }, "connectorName": { "type": "string", "description": "Display name of the connector being created." }, "setupUrl": { "type": "string", "format": "uri", "description": "Open this vercel.com URL in a browser to complete connector setup. Requires a vercel.com session for a member of the team." }, "environments": { "type": "array", "items": { "type": "string", "enum": [ "production", "preview", "development" ], "description": "Vercel environment the connector is attached to." }, "description": "Environments the connector will be attached to." }, "triggerPath": { "description": "Webhook trigger path that will be registered on the connector, when requested.", "type": "string" }, "createdProject": { "description": "Vercel project auto-created for this chat during setup, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "requestId", "service", "connectorName", "setupUrl", "environments" ], "additionalProperties": false, "description": "Connector setup is pending. Complete setup at `setupUrl`, poll GET /chats/{chatId}/connect/status until `ready`, then resolve with a `vercel-connect-setup` task." }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ], "description": "The Connect action finished; no user input is needed." }, "action": { "type": "string", "enum": [ "list", "create", "attach" ], "description": "The Connect action that ran." }, "summary": { "type": "string", "description": "Human-readable result summary." }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Connector identifier." }, "name": { "type": "string", "description": "Connector display name." }, "service": { "description": "Connected service identifier.", "type": "string" }, "attachedToProject": { "type": "boolean", "description": "Whether the connector is attached to the chat’s Vercel project." } }, "required": [ "id", "name", "attachedToProject" ], "additionalProperties": false }, "description": "Connectors involved in the action." }, "createdProject": { "description": "Vercel project created during the action, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "action", "summary", "connectors" ], "additionalProperties": false, "description": "The Connect action finished; no user input is needed." } ], "description": "Structured payload for a `configure_vercel_connect` agent action." } ] }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "summary" ], "additionalProperties": false, "description": "A typed escape hatch for agent actions that don’t fit the other part types. Forward-compatible: new action types may appear without API version changes." } ], "description": "A single entry in the ordered narrative of a message. Iterate `parts` in order to render the full transcript." }, "description": "Ordered list of parts that make up the message. Iterate to render the full narrative including thinking, file operations, tool calls, and prose." }, "finishReason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "content-filter", "tool-calls", "error", "other" ], "description": "The reason why message generation finished, including standard completion reasons and error states." }, { "type": "null" } ], "description": "Why generation ended. Null while the agent is still generating; once non-null, the message is final and safe to consume." }, "restorable": { "type": "boolean", "description": "True when this is an assistant message that produced restorable code and is not the currently active code." }, "attachments": { "description": "Files attached to this message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the attachment." }, "name": { "description": "Original filename, when available.", "type": "string" }, "contentType": { "description": "MIME type.", "type": "string" }, "size": { "description": "Size in bytes.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false } }, "authorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the user who authored a user message; null for assistant messages." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not yet generated tokens." } }, "required": [ "id", "chatId", "role", "createdAt", "updatedAt", "content", "parts", "finishReason", "restorable", "authorId", "usage" ], "additionalProperties": false, "description": "A single message in a chat." }, "MessageListResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier." }, "chatId": { "type": "string", "description": "ID of the chat this message belongs to." }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who produced this message." }, "createdAt": { "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))$", "description": "ISO timestamp when the message was created." }, "updatedAt": { "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))$", "description": "ISO timestamp when the message was last updated." }, "content": { "type": "string", "description": "The trailing prose of the message — the agent’s closing summary, or the user’s message text. Empty string when there is no closing prose." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Markdown prose written by the agent or user." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A block of text output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "text": { "type": "string", "description": "The agent's reasoning trace." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Extended thinking output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-read" ] }, "paths": { "type": "array", "items": { "type": "string" }, "description": "The file paths the agent read in this step." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "paths" ], "additionalProperties": false, "description": "Files read by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-edit" ] }, "operation": { "type": "string", "enum": [ "create", "update", "delete", "rename", "patch" ], "description": "The type of file edit performed." }, "path": { "type": "string", "description": "The target file path." }, "toPath": { "description": "The new path when operation is \"rename\".", "type": "string" }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "operation", "path" ], "additionalProperties": false, "description": "The agent created, modified, deleted, renamed, or patched a file." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "scope": { "type": "string", "enum": [ "repo", "web" ], "description": "Whether the agent searched the repository or the web." }, "query": { "type": "string", "description": "The search query." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "scope", "query" ], "additionalProperties": false, "description": "The agent searched for something." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bash" ] }, "command": { "type": "string", "description": "The shell command that was executed." }, "output": { "description": "Combined stdout/stderr captured from the terminal. May be empty if the command produced no output.", "type": "string" }, "exitCode": { "description": "Process exit code, when available. Reserved for future use; currently always omitted.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isDangerous": { "description": "True if the command was flagged as potentially dangerous and required explicit user approval.", "type": "boolean" }, "timeoutMs": { "description": "Command timeout in milliseconds, when configured.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "command" ], "additionalProperties": false, "description": "The agent ran a shell command." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "name": { "type": "string", "description": "The name of the tool that was invoked (e.g. an MCP tool name or built-in tool identifier)." }, "input": { "description": "The arguments passed to the tool. Schema depends on the specific tool." }, "output": { "description": "The result returned by the tool. Schema depends on the specific tool." }, "status": { "type": "string", "enum": [ "ok", "error" ], "description": "Whether the tool call succeeded or returned an error." }, "suggestedPermissions": { "description": "Present when the agent is blocked waiting for you to approve this tool call (for example, running a setup or migration script). Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task to approve. Omitted once the tool has run.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ], "description": "Permission grant type." }, "toolName": { "type": "string", "description": "The tool this permission authorizes." }, "input": { "description": "The tool input this permission authorizes. Pass back unchanged when resolving." }, "taskNameActive": { "description": "Internal label for the in-progress task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskNameComplete": { "description": "Internal label for the completed task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userMessage": { "description": "Optional message associated with the permission.", "type": "string" } }, "required": [ "type", "toolName" ], "additionalProperties": false, "description": "A permission the agent is waiting for you to grant. Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task." } }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "status" ], "additionalProperties": false, "description": "The agent invoked a tool (MCP, integration, or other dynamic tool). For shell commands, use the \"bash\" part instead." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-action" ] }, "name": { "type": "string", "description": "Stable identifier for the action (e.g. \"generate_image\", \"manage_todos\", \"diagnostics\"). See documentation for the registry of known names." }, "summary": { "type": "string", "description": "A short human-readable summary of what happened. Always populated so clients can render something even without knowing the action name." }, "data": { "description": "Structured payload for input-requesting actions. Present on `ask_user_questions`, `exit_plan_mode`, `get_or_request_integration`, and `configure_vercel_connect` parts when the agent is waiting on you; narrow by the part `name`. Omitted for actions that do not carry structured data.", "anyOf": [ { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Question identifier. Pass back as `questionId` when resolving with an `answered-questions` task." }, "question": { "type": "string", "description": "The full question text." }, "header": { "type": "string", "description": "Short label for the question." }, "multiSelect": { "type": "boolean", "description": "Whether more than one option may be selected." }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Option identifier." }, "label": { "type": "string", "description": "Display label. Pass matching labels back in `selectedLabels` when resolving." }, "description": { "description": "Optional longer explanation of the option.", "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, "description": "The available answer options." } }, "required": [ "id", "question", "header", "multiSelect", "options" ], "additionalProperties": false }, "description": "The questions the agent is waiting for answers to. Resolve with an `answered-questions` task." } }, "required": [ "questions" ], "additionalProperties": false, "description": "Structured payload for an `ask_user_questions` agent action." }, { "type": "object", "properties": { "plan": { "type": "string", "description": "The full proposed plan, as Markdown." }, "summary": { "description": "A concise summary of the plan, when available.", "type": "string" }, "path": { "type": "string", "description": "The path the plan applies to." } }, "required": [ "plan", "path" ], "additionalProperties": false, "description": "Structured payload for an `exit_plan_mode` agent action." }, { "type": "object", "properties": { "requestedIntegrations": { "type": "array", "items": { "type": "string" }, "description": "Integration names the agent is asking you to connect (for example, \"Neon\"). Pass these back in `connectedIntegrationNames` when resolving with a `confirmed-steps` task." }, "requestedMcpPresets": { "type": "array", "items": { "type": "string" }, "description": "MCP preset names the agent is asking you to add. Pass these back in `connectedMcpPresetNames` when resolving with a `confirmed-steps` task." } }, "required": [ "requestedIntegrations", "requestedMcpPresets" ], "additionalProperties": false, "description": "Structured payload for a `get_or_request_integration` agent action." }, { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "setup-required" ], "description": "The agent is waiting for connector setup to be completed in a browser." }, "requestId": { "type": "string", "description": "Setup request identifier. Pass as `requestId` to GET /chats/{chatId}/connect/status to poll for completion." }, "service": { "type": "string", "description": "The service being connected (for example, \"linear\")." }, "serviceIconUrl": { "description": "Icon URL for the service, hosted on vercel.com.", "type": "string", "format": "uri" }, "connectorName": { "type": "string", "description": "Display name of the connector being created." }, "setupUrl": { "type": "string", "format": "uri", "description": "Open this vercel.com URL in a browser to complete connector setup. Requires a vercel.com session for a member of the team." }, "environments": { "type": "array", "items": { "type": "string", "enum": [ "production", "preview", "development" ], "description": "Vercel environment the connector is attached to." }, "description": "Environments the connector will be attached to." }, "triggerPath": { "description": "Webhook trigger path that will be registered on the connector, when requested.", "type": "string" }, "createdProject": { "description": "Vercel project auto-created for this chat during setup, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "requestId", "service", "connectorName", "setupUrl", "environments" ], "additionalProperties": false, "description": "Connector setup is pending. Complete setup at `setupUrl`, poll GET /chats/{chatId}/connect/status until `ready`, then resolve with a `vercel-connect-setup` task." }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ], "description": "The Connect action finished; no user input is needed." }, "action": { "type": "string", "enum": [ "list", "create", "attach" ], "description": "The Connect action that ran." }, "summary": { "type": "string", "description": "Human-readable result summary." }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Connector identifier." }, "name": { "type": "string", "description": "Connector display name." }, "service": { "description": "Connected service identifier.", "type": "string" }, "attachedToProject": { "type": "boolean", "description": "Whether the connector is attached to the chat’s Vercel project." } }, "required": [ "id", "name", "attachedToProject" ], "additionalProperties": false }, "description": "Connectors involved in the action." }, "createdProject": { "description": "Vercel project created during the action, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "action", "summary", "connectors" ], "additionalProperties": false, "description": "The Connect action finished; no user input is needed." } ], "description": "Structured payload for a `configure_vercel_connect` agent action." } ] }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "summary" ], "additionalProperties": false, "description": "A typed escape hatch for agent actions that don’t fit the other part types. Forward-compatible: new action types may appear without API version changes." } ], "description": "A single entry in the ordered narrative of a message. Iterate `parts` in order to render the full transcript." }, "description": "Ordered list of parts that make up the message. Iterate to render the full narrative including thinking, file operations, tool calls, and prose." }, "finishReason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "content-filter", "tool-calls", "error", "other" ], "description": "The reason why message generation finished, including standard completion reasons and error states." }, { "type": "null" } ], "description": "Why generation ended. Null while the agent is still generating; once non-null, the message is final and safe to consume." }, "restorable": { "type": "boolean", "description": "True when this is an assistant message that produced restorable code and is not the currently active code." }, "attachments": { "description": "Files attached to this message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the attachment." }, "name": { "description": "Original filename, when available.", "type": "string" }, "contentType": { "description": "MIME type.", "type": "string" }, "size": { "description": "Size in bytes.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false } }, "authorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the user who authored a user message; null for assistant messages." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not yet generated tokens." } }, "required": [ "id", "chatId", "role", "createdAt", "updatedAt", "content", "parts", "finishReason", "restorable", "authorId", "usage" ], "additionalProperties": false, "description": "A single message in a chat." }, "description": "The messages in this page, newest first." }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page, or null if there are no more messages." } }, "required": [ "messages", "cursor" ], "additionalProperties": false }, "AsyncMessage": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageId": { "type": "string", "description": "ID of the assistant message that will receive the response. Poll GET /chats/:chatId/messages/:messageId and check `finishReason` for completion." } }, "required": [ "messageId" ], "additionalProperties": false, "description": "Acknowledgement that an async message has been queued." }, "MessageStreamEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier." }, "chatId": { "type": "string", "description": "ID of the chat this message belongs to." }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who produced this message." }, "createdAt": { "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))$", "description": "ISO timestamp when the message was created." }, "updatedAt": { "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))$", "description": "ISO timestamp when the message was last updated." }, "content": { "type": "string", "description": "The trailing prose of the message — the agent’s closing summary, or the user’s message text. Empty string when there is no closing prose." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Markdown prose written by the agent or user." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A block of text output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "text": { "type": "string", "description": "The agent's reasoning trace." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Extended thinking output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-read" ] }, "paths": { "type": "array", "items": { "type": "string" }, "description": "The file paths the agent read in this step." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "paths" ], "additionalProperties": false, "description": "Files read by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-edit" ] }, "operation": { "type": "string", "enum": [ "create", "update", "delete", "rename", "patch" ], "description": "The type of file edit performed." }, "path": { "type": "string", "description": "The target file path." }, "toPath": { "description": "The new path when operation is \"rename\".", "type": "string" }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "operation", "path" ], "additionalProperties": false, "description": "The agent created, modified, deleted, renamed, or patched a file." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "scope": { "type": "string", "enum": [ "repo", "web" ], "description": "Whether the agent searched the repository or the web." }, "query": { "type": "string", "description": "The search query." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "scope", "query" ], "additionalProperties": false, "description": "The agent searched for something." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bash" ] }, "command": { "type": "string", "description": "The shell command that was executed." }, "output": { "description": "Combined stdout/stderr captured from the terminal. May be empty if the command produced no output.", "type": "string" }, "exitCode": { "description": "Process exit code, when available. Reserved for future use; currently always omitted.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isDangerous": { "description": "True if the command was flagged as potentially dangerous and required explicit user approval.", "type": "boolean" }, "timeoutMs": { "description": "Command timeout in milliseconds, when configured.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "command" ], "additionalProperties": false, "description": "The agent ran a shell command." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "name": { "type": "string", "description": "The name of the tool that was invoked (e.g. an MCP tool name or built-in tool identifier)." }, "input": { "description": "The arguments passed to the tool. Schema depends on the specific tool." }, "output": { "description": "The result returned by the tool. Schema depends on the specific tool." }, "status": { "type": "string", "enum": [ "ok", "error" ], "description": "Whether the tool call succeeded or returned an error." }, "suggestedPermissions": { "description": "Present when the agent is blocked waiting for you to approve this tool call (for example, running a setup or migration script). Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task to approve. Omitted once the tool has run.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ], "description": "Permission grant type." }, "toolName": { "type": "string", "description": "The tool this permission authorizes." }, "input": { "description": "The tool input this permission authorizes. Pass back unchanged when resolving." }, "taskNameActive": { "description": "Internal label for the in-progress task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskNameComplete": { "description": "Internal label for the completed task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userMessage": { "description": "Optional message associated with the permission.", "type": "string" } }, "required": [ "type", "toolName" ], "additionalProperties": false, "description": "A permission the agent is waiting for you to grant. Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task." } }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "status" ], "additionalProperties": false, "description": "The agent invoked a tool (MCP, integration, or other dynamic tool). For shell commands, use the \"bash\" part instead." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-action" ] }, "name": { "type": "string", "description": "Stable identifier for the action (e.g. \"generate_image\", \"manage_todos\", \"diagnostics\"). See documentation for the registry of known names." }, "summary": { "type": "string", "description": "A short human-readable summary of what happened. Always populated so clients can render something even without knowing the action name." }, "data": { "description": "Structured payload for input-requesting actions. Present on `ask_user_questions`, `exit_plan_mode`, `get_or_request_integration`, and `configure_vercel_connect` parts when the agent is waiting on you; narrow by the part `name`. Omitted for actions that do not carry structured data.", "anyOf": [ { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Question identifier. Pass back as `questionId` when resolving with an `answered-questions` task." }, "question": { "type": "string", "description": "The full question text." }, "header": { "type": "string", "description": "Short label for the question." }, "multiSelect": { "type": "boolean", "description": "Whether more than one option may be selected." }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Option identifier." }, "label": { "type": "string", "description": "Display label. Pass matching labels back in `selectedLabels` when resolving." }, "description": { "description": "Optional longer explanation of the option.", "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, "description": "The available answer options." } }, "required": [ "id", "question", "header", "multiSelect", "options" ], "additionalProperties": false }, "description": "The questions the agent is waiting for answers to. Resolve with an `answered-questions` task." } }, "required": [ "questions" ], "additionalProperties": false, "description": "Structured payload for an `ask_user_questions` agent action." }, { "type": "object", "properties": { "plan": { "type": "string", "description": "The full proposed plan, as Markdown." }, "summary": { "description": "A concise summary of the plan, when available.", "type": "string" }, "path": { "type": "string", "description": "The path the plan applies to." } }, "required": [ "plan", "path" ], "additionalProperties": false, "description": "Structured payload for an `exit_plan_mode` agent action." }, { "type": "object", "properties": { "requestedIntegrations": { "type": "array", "items": { "type": "string" }, "description": "Integration names the agent is asking you to connect (for example, \"Neon\"). Pass these back in `connectedIntegrationNames` when resolving with a `confirmed-steps` task." }, "requestedMcpPresets": { "type": "array", "items": { "type": "string" }, "description": "MCP preset names the agent is asking you to add. Pass these back in `connectedMcpPresetNames` when resolving with a `confirmed-steps` task." } }, "required": [ "requestedIntegrations", "requestedMcpPresets" ], "additionalProperties": false, "description": "Structured payload for a `get_or_request_integration` agent action." }, { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "setup-required" ], "description": "The agent is waiting for connector setup to be completed in a browser." }, "requestId": { "type": "string", "description": "Setup request identifier. Pass as `requestId` to GET /chats/{chatId}/connect/status to poll for completion." }, "service": { "type": "string", "description": "The service being connected (for example, \"linear\")." }, "serviceIconUrl": { "description": "Icon URL for the service, hosted on vercel.com.", "type": "string", "format": "uri" }, "connectorName": { "type": "string", "description": "Display name of the connector being created." }, "setupUrl": { "type": "string", "format": "uri", "description": "Open this vercel.com URL in a browser to complete connector setup. Requires a vercel.com session for a member of the team." }, "environments": { "type": "array", "items": { "type": "string", "enum": [ "production", "preview", "development" ], "description": "Vercel environment the connector is attached to." }, "description": "Environments the connector will be attached to." }, "triggerPath": { "description": "Webhook trigger path that will be registered on the connector, when requested.", "type": "string" }, "createdProject": { "description": "Vercel project auto-created for this chat during setup, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "requestId", "service", "connectorName", "setupUrl", "environments" ], "additionalProperties": false, "description": "Connector setup is pending. Complete setup at `setupUrl`, poll GET /chats/{chatId}/connect/status until `ready`, then resolve with a `vercel-connect-setup` task." }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ], "description": "The Connect action finished; no user input is needed." }, "action": { "type": "string", "enum": [ "list", "create", "attach" ], "description": "The Connect action that ran." }, "summary": { "type": "string", "description": "Human-readable result summary." }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Connector identifier." }, "name": { "type": "string", "description": "Connector display name." }, "service": { "description": "Connected service identifier.", "type": "string" }, "attachedToProject": { "type": "boolean", "description": "Whether the connector is attached to the chat’s Vercel project." } }, "required": [ "id", "name", "attachedToProject" ], "additionalProperties": false }, "description": "Connectors involved in the action." }, "createdProject": { "description": "Vercel project created during the action, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "action", "summary", "connectors" ], "additionalProperties": false, "description": "The Connect action finished; no user input is needed." } ], "description": "Structured payload for a `configure_vercel_connect` agent action." } ] }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "summary" ], "additionalProperties": false, "description": "A typed escape hatch for agent actions that don’t fit the other part types. Forward-compatible: new action types may appear without API version changes." } ], "description": "A single entry in the ordered narrative of a message. Iterate `parts` in order to render the full transcript." }, "description": "Ordered list of parts that make up the message. Iterate to render the full narrative including thinking, file operations, tool calls, and prose." }, "finishReason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "content-filter", "tool-calls", "error", "other" ], "description": "The reason why message generation finished, including standard completion reasons and error states." }, { "type": "null" } ], "description": "Why generation ended. Null while the agent is still generating; once non-null, the message is final and safe to consume." }, "restorable": { "type": "boolean", "description": "True when this is an assistant message that produced restorable code and is not the currently active code." }, "attachments": { "description": "Files attached to this message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the attachment." }, "name": { "description": "Original filename, when available.", "type": "string" }, "contentType": { "description": "MIME type.", "type": "string" }, "size": { "description": "Size in bytes.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false } }, "authorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the user who authored a user message; null for assistant messages." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not yet generated tokens." }, "object": { "type": "string", "enum": [ "message" ], "description": "Discriminator: a message snapshot." } }, "required": [ "id", "chatId", "role", "createdAt", "updatedAt", "content", "parts", "finishReason", "restorable", "authorId", "usage", "object" ], "additionalProperties": false, "description": "Initial and final message-state event. Emitted once at stream open with the freshly-created assistant message (empty parts, null finishReason), and once at stream close with the completed message." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Assistant message ID." }, "object": { "type": "string", "enum": [ "message.parts.chunk" ], "description": "Discriminator." }, "delta": { "description": "jsondiffpatch delta to apply against the running public `Message.parts` array. Apply each delta in order to reconstruct the complete current parts snapshot." } }, "required": [ "id", "object", "delta" ], "additionalProperties": false, "description": "Incremental update to the assistant message content." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Assistant message ID this usage applies to." }, "object": { "type": "string", "enum": [ "message.usage" ], "description": "Discriminator." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not generated tokens." } }, "required": [ "id", "object", "usage" ], "additionalProperties": false, "description": "Final token usage and credit cost for the assistant message produced by this stream. Emitted once after the message finishes generating, before the closing state event." }, { "type": "object", "properties": { "id": { "type": "string", "description": "Assistant message ID or chat ID, depending on what is in scope when the error is raised." }, "object": { "type": "string", "enum": [ "error" ], "description": "Discriminator." }, "message": { "type": "string", "description": "Human-readable stream error message." }, "code": { "description": "Optional machine-readable stream error code.", "type": "string" } }, "required": [ "id", "object", "message" ], "additionalProperties": false, "description": "Emitted when a stream error occurs after the SSE response begins." } ], "description": "A single Server-Sent Events payload emitted by the streaming send-message endpoint. Each SSE event is `data: \\n\\n` where the JSON conforms to one of the union members." }, "Files": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Project-relative file path, e.g. \"app/page.tsx\"." }, "content": { "type": "string", "description": "Content of the file." }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "description": "How `content` is encoded. `utf8` for text files; `base64` for binary files." } }, "required": [ "path", "content", "encoding" ], "additionalProperties": false, "description": "A single source file in the chat." }, "description": "All source files in the chat." } }, "required": [ "files" ], "additionalProperties": false, "description": "The source files of a chat." }, "McpServer": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the MCP server." }, "name": { "type": "string", "description": "Display name of the MCP server." }, "url": { "type": "string", "description": "URL endpoint of the MCP server." }, "description": { "type": "string", "description": "Optional description of the MCP server." }, "createdAt": { "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))$", "description": "ISO timestamp of when the server was created." }, "updatedAt": { "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))$", "description": "ISO timestamp of the last update." }, "userId": { "type": "string", "description": "ID of the user who created the server." }, "enabled": { "type": "boolean", "description": "Whether the MCP server is enabled." }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ], "description": "Authentication configuration for the MCP server." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Scope of the MCP server configuration." } }, "required": [ "id", "name", "url", "description", "createdAt", "updatedAt", "userId", "enabled", "auth", "scope" ], "additionalProperties": false }, "ApiKey": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the API key." }, "name": { "type": "string", "description": "The name of the API key." }, "ownerId": { "type": "string", "description": "The team ID that owns this key." }, "partialKey": { "type": "string", "description": "The last few characters of the API key." }, "lastUsed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last time this key was used, or null if never used." } }, "required": [ "id", "name", "ownerId", "partialKey", "lastUsed" ], "additionalProperties": false }, "ApiKeyWithSecret": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the API key." }, "name": { "type": "string", "description": "The name of the API key." }, "ownerId": { "type": "string", "description": "The team ID that owns this key." }, "apiKey": { "type": "string", "description": "The full API key. Only returned on creation." } }, "required": [ "id", "name", "ownerId", "apiKey" ], "additionalProperties": false }, "SpendLimit": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entityId": { "type": "string", "description": "The team ID or organization ID this limit applies to." }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The spend limit in dollars." }, "source": { "type": "string", "enum": [ "team", "organization" ], "description": "Whether this limit is set at the team or organization level." }, "createdAt": { "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))$", "description": "ISO timestamp of when the spend limit was created." }, "updatedAt": { "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))$", "description": "ISO timestamp of when the spend limit was last updated." } }, "required": [ "entityId", "limit", "source", "createdAt", "updatedAt" ], "additionalProperties": false }, "TrustedPreviewHosts": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "hosts": { "type": "array", "items": { "type": "string" }, "description": "Canonicalized hostname patterns trusted to embed previews. Exact hosts match only themselves; *.example.com matches exactly one subdomain label; **.example.com matches one or more subdomain labels. Wildcards do not include the apex, so list example.com separately when it should also be trusted." } }, "required": [ "hosts" ], "additionalProperties": false }, "WebhookEventType": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." }, "Webhook": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the webhook." }, "createdAt": { "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))$", "description": "The ISO timestamp representing when the chat was created." }, "name": { "type": "string", "description": "A user-defined name to label the webhook." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." }, "description": "List of event types this webhook is subscribed to." }, "url": { "type": "string", "description": "Target URL that receives event payloads for this webhook." }, "chatId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional ID of the chat that this webhook is scoped to." } }, "required": [ "id", "createdAt", "name", "events", "url", "chatId" ], "additionalProperties": false } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/chats": { "post": { "tags": [ "Chats" ], "summary": "Create Chat", "description": "Creates a new chat from a prompt. The request blocks until the model response is complete and returns the chat.", "operationId": "chats.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A chat response that also reports the usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWithUsage" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Chats" ], "summary": "List Chats", "description": "Lists chats accessible to the authenticated user. Use metadata[key]=value style query parameters to filter by metadata.", "operationId": "chats.list", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Maximum number of chats to return (1-100, default 20)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pagination cursor returned from a previous response." }, { "name": "authorId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict results to chats created by this user. Must be a member of the calling scope." }, { "name": "vercelProjectId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict results to chats associated with this Vercel project." }, { "name": "metadata", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "description": "Filter by metadata, e.g. metadata[environment]=production. Returns chats matching all supplied key-value pairs." } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique chat identifier." }, "title": { "description": "Chat title, if generated.", "type": "string" }, "privacy": { "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ], "description": "Visibility setting of the chat." }, "createdAt": { "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))$", "description": "ISO timestamp of when the chat was created." }, "updatedAt": { "description": "ISO timestamp of when the chat was last updated.", "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))$" }, "authorId": { "type": "string", "description": "ID of the user who created the chat." }, "vercelProjectId": { "description": "Associated Vercel project ID, if any.", "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "User-defined key-value metadata." }, "writePermission": { "type": "boolean", "description": "Whether the caller has write access to this chat." } }, "required": [ "id", "privacy", "createdAt", "authorId", "metadata", "writePermission" ], "additionalProperties": false }, "description": "The chats in this page." }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor to fetch the next page, or null if there are no more chats." } }, "required": [ "chats", "cursor" ], "additionalProperties": false } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/from-files": { "post": { "tags": [ "Chats" ], "summary": "Create Chat From Files", "description": "Creates a new chat from inline source files.", "operationId": "chats.createFromFiles", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Path of the file in the project." }, "content": { "type": "string", "description": "UTF-8 text content of the file." } }, "required": [ "name", "content" ], "additionalProperties": false }, "description": "Source files used to seed the new chat." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "files" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Path of the file in the project." }, "content": { "type": "string", "description": "UTF-8 text content of the file." } }, "required": [ "name", "content" ], "additionalProperties": false }, "description": "Source files used to seed the new chat." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "files" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Path of the file in the project." }, "content": { "type": "string", "description": "UTF-8 text content of the file." } }, "required": [ "name", "content" ], "additionalProperties": false }, "description": "Source files used to seed the new chat." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "files" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A chat response that also reports the usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWithUsage" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/from-zip": { "post": { "tags": [ "Chats" ], "summary": "Create Chat From ZIP", "description": "Creates a new chat from a zip archive.", "operationId": "chats.createFromZip", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Zip archive used to seed the new chat." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "url" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Zip archive used to seed the new chat." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "url" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Zip archive used to seed the new chat." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A chat response that also reports the usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWithUsage" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/from-repo": { "post": { "tags": [ "Chats" ], "summary": "Create Chat From Repository", "description": "Creates a new chat from a GitHub repository.", "operationId": "chats.createFromRepo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "repo": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "GitHub repository URL, for example https://github.com/vercel/next.js." }, "branch": { "description": "Branch to import. If omitted, v0 uses the repository default branch.", "type": "string", "maxLength": 250 } }, "required": [ "url" ], "additionalProperties": false, "description": "Repository source for initialization. Supports public GitHub repositories and private repositories connected through Vercel." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "repo" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "repo": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "GitHub repository URL, for example https://github.com/vercel/next.js." }, "branch": { "description": "Branch to import. If omitted, v0 uses the repository default branch.", "type": "string", "maxLength": 250 } }, "required": [ "url" ], "additionalProperties": false, "description": "Repository source for initialization. Supports public GitHub repositories and private repositories connected through Vercel." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "repo" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "repo": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "GitHub repository URL, for example https://github.com/vercel/next.js." }, "branch": { "description": "Branch to import. If omitted, v0 uses the repository default branch.", "type": "string", "maxLength": 250 } }, "required": [ "url" ], "additionalProperties": false, "description": "Repository source for initialization. Supports public GitHub repositories and private repositories connected through Vercel." }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "repo" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A chat response that also reports the usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatWithUsage" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/stream": { "post": { "tags": [ "Chats" ], "summary": "Create Chat (Streaming)", "description": "Creates a new chat with a user message and returns a Server-Sent Events stream. Events include initial chat state, title deltas, content chunk deltas, and final chat state. The response is `text/event-stream`; each event is `data: \\n\\n` where the JSON conforms to ChatStreamEvent.", "operationId": "chats.createStream", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A single Server-Sent Events payload emitted by streaming chat endpoints. Each SSE event is `data: \\n\\n` where the JSON conforms to one of the union members.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/ChatStreamEvent" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/async": { "post": { "tags": [ "Chats" ], "summary": "Create Chat (Async)", "description": "Creates a new chat with a user message and processes it in the background. Returns immediately with the chat ID and message ID. Poll for the assistant message by ID until `finishReason` is non-null.", "operationId": "chats.createAsync", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "skills": { "description": "Skills to force-attach to the chat. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } }, "privacy": { "description": "Visibility setting for the new chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Title for the new chat.", "type": "string" }, "metadata": { "description": "Arbitrary key-value data to attach to the chat.", "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Response for status 202", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncChat" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages": { "get": { "tags": [ "Messages" ], "summary": "List Messages", "description": "Lists all messages in a chat.", "operationId": "messages.list", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "description": "Maximum number of messages to return (1-100, default 20).", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pagination cursor returned from a previous response.", "type": "string" } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Messages" ], "summary": "Send Message", "description": "Sends a new message to an existing chat. Blocks until the model response is complete and returns the message response.", "operationId": "messages.send", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A single message in a chat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/{messageId}": { "get": { "tags": [ "Messages" ], "summary": "Get Message", "description": "Fetches a single message in a chat.", "operationId": "messages.get", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the message." } } ], "responses": { "200": { "description": "A single message in a chat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/stream": { "post": { "tags": [ "Messages" ], "summary": "Send Message (Streaming)", "description": "Sends a new message to an existing chat and returns a Server-Sent Events stream. Events include the initial assistant-message snapshot, content chunk deltas, final usage, and a closing message snapshot. The response is `text/event-stream`; each event is `data: \\n\\n` where the JSON conforms to MessageStreamEvent.", "operationId": "messages.sendStream", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A single Server-Sent Events payload emitted by the streaming send-message endpoint. Each SSE event is `data: \\n\\n` where the JSON conforms to one of the union members.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessageStreamEvent" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/async": { "post": { "tags": [ "Messages" ], "summary": "Send Message (Async)", "description": "Sends a new message to an existing chat and processes it in the background. Returns immediately with the assistant message ID. Poll GET /chats/:chatId/messages/:messageId and check `finishReason` to detect completion.", "operationId": "messages.sendAsync", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The prompt or instruction to send to the model." }, "systemPrompt": { "description": "System-level context for the chat, such as frameworks or development environment details.", "type": "string" }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "required": [ "modelId", "imageGenerations" ], "additionalProperties": false }, "mcpServerIds": { "description": "MCP server IDs to enable. When omitted, uses default enabled servers.", "type": "array", "items": { "type": "string" } }, "attachments": { "description": "Files or assets to include with the message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the attachment." } }, "required": [ "url" ], "additionalProperties": false } }, "skills": { "description": "Skills to force-attach to the message. Supports skills.sh (`remote`), user/team memory (`memory`), and project (`project`) skills. Maximum 3.", "maxItems": 3, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "remote" ], "description": "Discriminator: a skills.sh skill." }, "id": { "type": "string", "description": "Skill ID from skills.sh." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "memory" ], "description": "Discriminator: a user- or team-scoped memory skill." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Whether the skill lives in user or team memory." }, "skillName": { "type": "string", "description": "Name of the memory skill to attach." } }, "required": [ "type", "scope", "skillName" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project" ], "description": "Discriminator: a skill defined in the project repo." }, "skillName": { "type": "string", "description": "Name of the project skill to attach." } }, "required": [ "type", "skillName" ], "additionalProperties": false } ], "description": "A skill to force-attach to the chat. Skills provide domain-specific knowledge to the AI. Use `remote` for skills.sh skills, `memory` for user/team memory skills (including design-system skills), and `project` for skills defined in the chat repo." } } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Acknowledgement that an async message has been queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncMessage" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/resolve": { "post": { "tags": [ "Messages" ], "summary": "Resolve Task", "description": "Resolves a pending task in a chat. Blocks until the model response is complete and returns the resulting message.", "operationId": "messages.resolve", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A single message in a chat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/resolve/stream": { "post": { "tags": [ "Messages" ], "summary": "Resolve Task (Streaming)", "description": "Resolves a pending task in a chat and returns a Server-Sent Events stream. Events include the initial assistant-message snapshot, content chunk deltas, final usage, and a closing message snapshot. The response is `text/event-stream`; each event is `data: \\n\\n` where the JSON conforms to MessageStreamEvent.", "operationId": "messages.resolveStream", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "A single Server-Sent Events payload emitted by the streaming send-message endpoint. Each SSE event is `data: \\n\\n` where the JSON conforms to one of the union members.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/MessageStreamEvent" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/resolve/async": { "post": { "tags": [ "Messages" ], "summary": "Resolve Task (Async)", "description": "Resolves a pending task and processes it in the background. Returns immediately with the assistant message ID. Poll GET /chats/:chatId/messages/:messageId and check `finishReason` to detect completion.", "operationId": "messages.resolveAsync", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "task": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-steps" ] }, "connectedIntegrationNames": { "description": "Names of integrations that were successfully connected (e.g. \"Neon\", \"Supabase\"). Pass an empty array to skip.", "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 64 } }, "connectedMcpPresetNames": { "description": "Names of MCP presets that were connected (e.g. \"Linear\", \"Sentry\"). Pass an empty array to skip.", "default": [], "type": "array", "items": { "type": "string", "enum": [ "Linear", "Notion", "Context7", "Sentry", "Zapier", "Glean", "Hex", "Sanity", "Granola", "PostHog", "Contentful", "Slack" ] } }, "appliedScripts": { "description": "Names of scripts that were applied.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } }, "addedEnvVars": { "description": "Names of environment variables that were added.", "default": [], "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves an integration installation task. The agent asked the user to install integrations, MCP presets, or set environment variables. Send this after provisioning the integration on Vercel." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan-exit-response" ] }, "status": { "type": "string", "enum": [ "approved", "rejected", "request-changes" ], "description": "Whether the plan is approved, rejected, or needs changes." }, "content": { "type": "string", "minLength": 1, "description": "Feedback or instructions for the agent." } }, "required": [ "type", "status", "content" ], "additionalProperties": false, "description": "Resolves a plan review task. The agent proposed an implementation plan and is waiting for approval." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "answered-questions" ] }, "answers": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "questionId": { "type": "string", "minLength": 1, "description": "The ID of the question being answered." }, "questionText": { "type": "string", "minLength": 1, "description": "The text of the question being answered." }, "selectedLabels": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The labels of the selected options. For single-select questions, pass one item." }, "customText": { "description": "Free-form text input, used when the user selects \"Other\" or wants to add context.", "type": "string", "minLength": 1 } }, "required": [ "questionId", "questionText", "selectedLabels" ], "additionalProperties": false }, "description": "Answers to the questions the agent asked." } }, "required": [ "type", "answers" ], "additionalProperties": false, "description": "Resolves a question task. The agent asked the user one or more multiple-choice questions." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "confirmed-permissions" ] }, "permissions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ] }, "toolName": { "type": "string", "minLength": 1, "description": "The name of the tool being permitted." }, "input": { "description": "The tool call input arguments. Pass the exact input from the stopped task." }, "taskNameActive": { "description": "Label shown while the tool is running (e.g. \"Running migration\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "taskNameComplete": { "description": "Label shown after the tool completes (e.g. \"Migration complete\").", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "userMessage": { "description": "Optional message from the user about this permission.", "type": "string", "minLength": 1 } }, "required": [ "type", "toolName", "input" ], "additionalProperties": false }, "description": "The permissions to grant. Pass the suggestedPermissions from the stopped task." }, "userMessage": { "description": "Optional message from the user about the permission grant.", "type": "string", "minLength": 1 } }, "required": [ "type", "permissions" ], "additionalProperties": false, "description": "Resolves a permission request task. The agent wants to execute a tool (shell command, script, MCP call) and needs approval. Also used to resolve environment variable prompts." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "vercel-connect-setup" ] } }, "required": [ "type" ], "additionalProperties": false, "description": "Resolves a Vercel Connect setup task. The agent asked the user to complete connector setup in a browser (a `configure_vercel_connect` agent action with `status: \"setup-required\"`). Complete setup at the action’s `setupUrl`, poll GET /chats/{chatId}/connect/status until it returns `ready`, then send this task. The server verifies the setup result and attaches the connector; no connector ID is needed. Returns 409 if setup is still pending or failed, or 404 if setup has not started or the request expired." } ], "description": "The task resolution data. Use this when the chat is waiting for user input on the matching task type." }, "modelConfiguration": { "description": "Overrides for the model behavior.", "type": "object", "properties": { "modelId": { "default": "v0-pro", "type": "string", "enum": [ "v0-mini", "v0-pro", "v0-max", "v0-max-fast" ], "description": "Model to use for the generation." }, "imageGenerations": { "default": false, "type": "boolean", "description": "Enables image generations to generate up to 5 images per version." } }, "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Acknowledgement that an async message has been queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncMessage" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/messages/{messageId}/stop": { "post": { "tags": [ "Messages" ], "summary": "Stop Message", "description": "Stops an in-flight assistant message generation. The agent aborts at the next safe point and the message is marked finished.", "operationId": "messages.stop", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the assistant message to stop." } } ], "responses": { "200": { "description": "The stopped message.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageId": { "type": "string", "description": "The unique identifier of the stopped message." } }, "required": [ "messageId" ], "additionalProperties": false, "description": "The stopped message." } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}": { "get": { "tags": [ "Chats" ], "summary": "Get Chat", "description": "Retrieves a chat by ID.", "operationId": "chats.get", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chat" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Chats" ], "summary": "Update Chat", "description": "Updates a chat's title, privacy, or metadata.", "operationId": "chats.update", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "description": "A new title to assign to the chat.", "type": "string" }, "privacy": { "description": "Updated visibility setting for the chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "metadata": { "description": "User-defined key-value metadata. Merged with existing entries. Pass `null` for a value to delete that key, or pass `null` for the whole field to delete all entries. Maximum 50 active entries.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 50 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, { "type": "null" } ] } }, "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "description": "A new title to assign to the chat.", "type": "string" }, "privacy": { "description": "Updated visibility setting for the chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "metadata": { "description": "User-defined key-value metadata. Merged with existing entries. Pass `null` for a value to delete that key, or pass `null` for the whole field to delete all entries. Maximum 50 active entries.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 50 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, { "type": "null" } ] } }, "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "description": "A new title to assign to the chat.", "type": "string" }, "privacy": { "description": "Updated visibility setting for the chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "metadata": { "description": "User-defined key-value metadata. Merged with existing entries. Pass `null` for a value to delete that key, or pass `null` for the whole field to delete all entries. Maximum 50 active entries.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 50 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chat" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Chats" ], "summary": "Delete Chat", "description": "Deletes a chat and all its associated messages. The requester must have edit access to the chat.", "operationId": "chats.delete", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chatId": { "type": "string", "description": "The ID of the deleted chat." } }, "required": [ "chatId" ], "additionalProperties": false } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/preview": { "get": { "tags": [ "Chats" ], "summary": "Get Preview URL", "description": "Returns the preview URL for a chat. If the preview isn't ready, the response is null. Poll this endpoint until the response is non-null.", "operationId": "chats.getPreview", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "The preview details, or null if the preview is still starting. Poll this endpoint until the response is non-null.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The preview URL for this chat." }, "token": { "type": "string", "description": "A short-lived token for accessing the preview URL via the x-v0-preview-token header." }, "expiresAt": { "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))$", "description": "The ISO timestamp when token expires." } }, "required": [ "url", "token", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "The preview details, or null if the preview is still starting. Poll this endpoint until the response is non-null." } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/files": { "get": { "tags": [ "Chats" ], "summary": "Get Chat Files", "description": "Returns the source files for a chat.", "operationId": "chats.getFiles", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "The source files of a chat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Files" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Chats" ], "summary": "Update Chat Files", "description": "Creates, updates, or deletes files for a chat. Pass null to delete. This requires the chat's preview to be running.", "operationId": "chats.updateFiles", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Project-relative file path, e.g. \"app/page.tsx\"." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New file content. Pass `null` to delete the file at this path." } }, "required": [ "path", "content" ], "additionalProperties": false }, "description": "The files to create, update, or delete. Each path must be unique." } }, "required": [ "files" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Project-relative file path, e.g. \"app/page.tsx\"." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New file content. Pass `null` to delete the file at this path." } }, "required": [ "path", "content" ], "additionalProperties": false }, "description": "The files to create, update, or delete. Each path must be unique." } }, "required": [ "files" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Project-relative file path, e.g. \"app/page.tsx\"." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New file content. Pass `null` to delete the file at this path." } }, "required": [ "path", "content" ], "additionalProperties": false }, "description": "The files to create, update, or delete. Each path must be unique." } }, "required": [ "files" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The messages created to record the file edit.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier." }, "chatId": { "type": "string", "description": "ID of the chat this message belongs to." }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who produced this message." }, "createdAt": { "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))$", "description": "ISO timestamp when the message was created." }, "updatedAt": { "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))$", "description": "ISO timestamp when the message was last updated." }, "content": { "type": "string", "description": "The trailing prose of the message — the agent’s closing summary, or the user’s message text. Empty string when there is no closing prose." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Markdown prose written by the agent or user." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A block of text output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "text": { "type": "string", "description": "The agent's reasoning trace." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Extended thinking output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-read" ] }, "paths": { "type": "array", "items": { "type": "string" }, "description": "The file paths the agent read in this step." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "paths" ], "additionalProperties": false, "description": "Files read by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-edit" ] }, "operation": { "type": "string", "enum": [ "create", "update", "delete", "rename", "patch" ], "description": "The type of file edit performed." }, "path": { "type": "string", "description": "The target file path." }, "toPath": { "description": "The new path when operation is \"rename\".", "type": "string" }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "operation", "path" ], "additionalProperties": false, "description": "The agent created, modified, deleted, renamed, or patched a file." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "scope": { "type": "string", "enum": [ "repo", "web" ], "description": "Whether the agent searched the repository or the web." }, "query": { "type": "string", "description": "The search query." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "scope", "query" ], "additionalProperties": false, "description": "The agent searched for something." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bash" ] }, "command": { "type": "string", "description": "The shell command that was executed." }, "output": { "description": "Combined stdout/stderr captured from the terminal. May be empty if the command produced no output.", "type": "string" }, "exitCode": { "description": "Process exit code, when available. Reserved for future use; currently always omitted.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isDangerous": { "description": "True if the command was flagged as potentially dangerous and required explicit user approval.", "type": "boolean" }, "timeoutMs": { "description": "Command timeout in milliseconds, when configured.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "command" ], "additionalProperties": false, "description": "The agent ran a shell command." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "name": { "type": "string", "description": "The name of the tool that was invoked (e.g. an MCP tool name or built-in tool identifier)." }, "input": { "description": "The arguments passed to the tool. Schema depends on the specific tool." }, "output": { "description": "The result returned by the tool. Schema depends on the specific tool." }, "status": { "type": "string", "enum": [ "ok", "error" ], "description": "Whether the tool call succeeded or returned an error." }, "suggestedPermissions": { "description": "Present when the agent is blocked waiting for you to approve this tool call (for example, running a setup or migration script). Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task to approve. Omitted once the tool has run.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ], "description": "Permission grant type." }, "toolName": { "type": "string", "description": "The tool this permission authorizes." }, "input": { "description": "The tool input this permission authorizes. Pass back unchanged when resolving." }, "taskNameActive": { "description": "Internal label for the in-progress task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskNameComplete": { "description": "Internal label for the completed task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userMessage": { "description": "Optional message associated with the permission.", "type": "string" } }, "required": [ "type", "toolName" ], "additionalProperties": false, "description": "A permission the agent is waiting for you to grant. Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task." } }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "status" ], "additionalProperties": false, "description": "The agent invoked a tool (MCP, integration, or other dynamic tool). For shell commands, use the \"bash\" part instead." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-action" ] }, "name": { "type": "string", "description": "Stable identifier for the action (e.g. \"generate_image\", \"manage_todos\", \"diagnostics\"). See documentation for the registry of known names." }, "summary": { "type": "string", "description": "A short human-readable summary of what happened. Always populated so clients can render something even without knowing the action name." }, "data": { "description": "Structured payload for input-requesting actions. Present on `ask_user_questions`, `exit_plan_mode`, `get_or_request_integration`, and `configure_vercel_connect` parts when the agent is waiting on you; narrow by the part `name`. Omitted for actions that do not carry structured data.", "anyOf": [ { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Question identifier. Pass back as `questionId` when resolving with an `answered-questions` task." }, "question": { "type": "string", "description": "The full question text." }, "header": { "type": "string", "description": "Short label for the question." }, "multiSelect": { "type": "boolean", "description": "Whether more than one option may be selected." }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Option identifier." }, "label": { "type": "string", "description": "Display label. Pass matching labels back in `selectedLabels` when resolving." }, "description": { "description": "Optional longer explanation of the option.", "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, "description": "The available answer options." } }, "required": [ "id", "question", "header", "multiSelect", "options" ], "additionalProperties": false }, "description": "The questions the agent is waiting for answers to. Resolve with an `answered-questions` task." } }, "required": [ "questions" ], "additionalProperties": false, "description": "Structured payload for an `ask_user_questions` agent action." }, { "type": "object", "properties": { "plan": { "type": "string", "description": "The full proposed plan, as Markdown." }, "summary": { "description": "A concise summary of the plan, when available.", "type": "string" }, "path": { "type": "string", "description": "The path the plan applies to." } }, "required": [ "plan", "path" ], "additionalProperties": false, "description": "Structured payload for an `exit_plan_mode` agent action." }, { "type": "object", "properties": { "requestedIntegrations": { "type": "array", "items": { "type": "string" }, "description": "Integration names the agent is asking you to connect (for example, \"Neon\"). Pass these back in `connectedIntegrationNames` when resolving with a `confirmed-steps` task." }, "requestedMcpPresets": { "type": "array", "items": { "type": "string" }, "description": "MCP preset names the agent is asking you to add. Pass these back in `connectedMcpPresetNames` when resolving with a `confirmed-steps` task." } }, "required": [ "requestedIntegrations", "requestedMcpPresets" ], "additionalProperties": false, "description": "Structured payload for a `get_or_request_integration` agent action." }, { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "setup-required" ], "description": "The agent is waiting for connector setup to be completed in a browser." }, "requestId": { "type": "string", "description": "Setup request identifier. Pass as `requestId` to GET /chats/{chatId}/connect/status to poll for completion." }, "service": { "type": "string", "description": "The service being connected (for example, \"linear\")." }, "serviceIconUrl": { "description": "Icon URL for the service, hosted on vercel.com.", "type": "string", "format": "uri" }, "connectorName": { "type": "string", "description": "Display name of the connector being created." }, "setupUrl": { "type": "string", "format": "uri", "description": "Open this vercel.com URL in a browser to complete connector setup. Requires a vercel.com session for a member of the team." }, "environments": { "type": "array", "items": { "type": "string", "enum": [ "production", "preview", "development" ], "description": "Vercel environment the connector is attached to." }, "description": "Environments the connector will be attached to." }, "triggerPath": { "description": "Webhook trigger path that will be registered on the connector, when requested.", "type": "string" }, "createdProject": { "description": "Vercel project auto-created for this chat during setup, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "requestId", "service", "connectorName", "setupUrl", "environments" ], "additionalProperties": false, "description": "Connector setup is pending. Complete setup at `setupUrl`, poll GET /chats/{chatId}/connect/status until `ready`, then resolve with a `vercel-connect-setup` task." }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ], "description": "The Connect action finished; no user input is needed." }, "action": { "type": "string", "enum": [ "list", "create", "attach" ], "description": "The Connect action that ran." }, "summary": { "type": "string", "description": "Human-readable result summary." }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Connector identifier." }, "name": { "type": "string", "description": "Connector display name." }, "service": { "description": "Connected service identifier.", "type": "string" }, "attachedToProject": { "type": "boolean", "description": "Whether the connector is attached to the chat’s Vercel project." } }, "required": [ "id", "name", "attachedToProject" ], "additionalProperties": false }, "description": "Connectors involved in the action." }, "createdProject": { "description": "Vercel project created during the action, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "action", "summary", "connectors" ], "additionalProperties": false, "description": "The Connect action finished; no user input is needed." } ], "description": "Structured payload for a `configure_vercel_connect` agent action." } ] }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "summary" ], "additionalProperties": false, "description": "A typed escape hatch for agent actions that don’t fit the other part types. Forward-compatible: new action types may appear without API version changes." } ], "description": "A single entry in the ordered narrative of a message. Iterate `parts` in order to render the full transcript." }, "description": "Ordered list of parts that make up the message. Iterate to render the full narrative including thinking, file operations, tool calls, and prose." }, "finishReason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "content-filter", "tool-calls", "error", "other" ], "description": "The reason why message generation finished, including standard completion reasons and error states." }, { "type": "null" } ], "description": "Why generation ended. Null while the agent is still generating; once non-null, the message is final and safe to consume." }, "restorable": { "type": "boolean", "description": "True when this is an assistant message that produced restorable code and is not the currently active code." }, "attachments": { "description": "Files attached to this message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the attachment." }, "name": { "description": "Original filename, when available.", "type": "string" }, "contentType": { "description": "MIME type.", "type": "string" }, "size": { "description": "Size in bytes.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false } }, "authorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the user who authored a user message; null for assistant messages." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not yet generated tokens." } }, "required": [ "id", "chatId", "role", "createdAt", "updatedAt", "content", "parts", "finishReason", "restorable", "authorId", "usage" ], "additionalProperties": false, "description": "A single message in a chat." }, "description": "The user and assistant messages created by the edit, in chronological order." } }, "required": [ "messages" ], "additionalProperties": false, "description": "The messages created to record the file edit." } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Invalid file contents" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The invalid request body field path." }, "error": { "type": "string", "description": "Validation error for the field." } }, "required": [ "path", "error" ], "additionalProperties": false }, "description": "All file content validation issues." } }, "required": [ "message", "issues" ], "additionalProperties": false }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } ] } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/files/download": { "get": { "tags": [ "Chats" ], "summary": "Download Chat Files", "description": "Downloads the source files for a chat as a ZIP archive.", "operationId": "chats.downloadFiles", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "ZIP archive of the chat files.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "ZIP archive of the chat files." } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/connect/status": { "get": { "tags": [ "Chats" ], "summary": "Get Connect Setup Status", "description": "Polls the status of a Vercel Connect connector setup started by a `configure_vercel_connect` agent action. Open the `setupUrl` from the agent action data in a browser, then poll this endpoint every few seconds while `pending`. When it returns `ready`, resolve the chat with a `vercel-connect-setup` task to resume generation.", "operationId": "chats.getConnectStatus", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } }, { "name": "requestId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The `requestId` from the `configure_vercel_connect` agent action data." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending" ], "description": "Setup is still in progress." }, "progress": { "description": "Current setup progress.", "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ], "description": "Setup completed successfully." }, "connector": { "type": "object", "properties": { "id": { "type": "string", "description": "Vercel Connect connector identifier." }, "uid": { "description": "Optional connector UID.", "type": "string" }, "name": { "type": "string", "description": "Connector display name." }, "service": { "description": "Connected service identifier.", "type": "string" }, "type": { "type": "string", "description": "Connector type." }, "supportedSubjectTypes": { "description": "Subject types supported by the connector.", "type": "array", "items": { "type": "string", "enum": [ "app", "user", "jwt-bearer" ] } }, "supportsInstallation": { "description": "Whether the connector supports installation.", "type": "boolean" }, "attachedToProject": { "type": "boolean", "description": "Whether the connector is already attached to the project." } }, "required": [ "id", "name", "type", "attachedToProject" ], "additionalProperties": false, "description": "Connector created by setup." } }, "required": [ "status", "connector" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Setup completed with an error." }, "message": { "type": "string", "description": "Safe user-facing setup error message." } }, "required": [ "status", "message" ], "additionalProperties": false } ] } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/restore-message": { "post": { "tags": [ "Chats" ], "summary": "Restore Message", "description": "Restores the files associated with an assistant message. The associated files must not already be the latest files in the chat.", "operationId": "chats.restoreMessage", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageId": { "type": "string", "minLength": 1, "description": "The unique identifier of the assistant message whose files to restore." } }, "required": [ "messageId" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageId": { "type": "string", "minLength": 1, "description": "The unique identifier of the assistant message whose files to restore." } }, "required": [ "messageId" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageId": { "type": "string", "minLength": 1, "description": "The unique identifier of the assistant message whose files to restore." } }, "required": [ "messageId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The messages created to record the restore.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier." }, "chatId": { "type": "string", "description": "ID of the chat this message belongs to." }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who produced this message." }, "createdAt": { "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))$", "description": "ISO timestamp when the message was created." }, "updatedAt": { "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))$", "description": "ISO timestamp when the message was last updated." }, "content": { "type": "string", "description": "The trailing prose of the message — the agent’s closing summary, or the user’s message text. Empty string when there is no closing prose." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string", "description": "Markdown prose written by the agent or user." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "A block of text output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "thinking" ] }, "text": { "type": "string", "description": "The agent's reasoning trace." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "text" ], "additionalProperties": false, "description": "Extended thinking output by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-read" ] }, "paths": { "type": "array", "items": { "type": "string" }, "description": "The file paths the agent read in this step." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "paths" ], "additionalProperties": false, "description": "Files read by the agent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file-edit" ] }, "operation": { "type": "string", "enum": [ "create", "update", "delete", "rename", "patch" ], "description": "The type of file edit performed." }, "path": { "type": "string", "description": "The target file path." }, "toPath": { "description": "The new path when operation is \"rename\".", "type": "string" }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "operation", "path" ], "additionalProperties": false, "description": "The agent created, modified, deleted, renamed, or patched a file." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search" ] }, "scope": { "type": "string", "enum": [ "repo", "web" ], "description": "Whether the agent searched the repository or the web." }, "query": { "type": "string", "description": "The search query." }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "scope", "query" ], "additionalProperties": false, "description": "The agent searched for something." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bash" ] }, "command": { "type": "string", "description": "The shell command that was executed." }, "output": { "description": "Combined stdout/stderr captured from the terminal. May be empty if the command produced no output.", "type": "string" }, "exitCode": { "description": "Process exit code, when available. Reserved for future use; currently always omitted.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isDangerous": { "description": "True if the command was flagged as potentially dangerous and required explicit user approval.", "type": "boolean" }, "timeoutMs": { "description": "Command timeout in milliseconds, when configured.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "command" ], "additionalProperties": false, "description": "The agent ran a shell command." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "name": { "type": "string", "description": "The name of the tool that was invoked (e.g. an MCP tool name or built-in tool identifier)." }, "input": { "description": "The arguments passed to the tool. Schema depends on the specific tool." }, "output": { "description": "The result returned by the tool. Schema depends on the specific tool." }, "status": { "type": "string", "enum": [ "ok", "error" ], "description": "Whether the tool call succeeded or returned an error." }, "suggestedPermissions": { "description": "Present when the agent is blocked waiting for you to approve this tool call (for example, running a setup or migration script). Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task to approve. Omitted once the tool has run.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ALLOW_DYNAMIC_TOOL_STRICT" ], "description": "Permission grant type." }, "toolName": { "type": "string", "description": "The tool this permission authorizes." }, "input": { "description": "The tool input this permission authorizes. Pass back unchanged when resolving." }, "taskNameActive": { "description": "Internal label for the in-progress task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskNameComplete": { "description": "Internal label for the completed task. Pass back unchanged.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userMessage": { "description": "Optional message associated with the permission.", "type": "string" } }, "required": [ "type", "toolName" ], "additionalProperties": false, "description": "A permission the agent is waiting for you to grant. Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task." } }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "status" ], "additionalProperties": false, "description": "The agent invoked a tool (MCP, integration, or other dynamic tool). For shell commands, use the \"bash\" part instead." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-action" ] }, "name": { "type": "string", "description": "Stable identifier for the action (e.g. \"generate_image\", \"manage_todos\", \"diagnostics\"). See documentation for the registry of known names." }, "summary": { "type": "string", "description": "A short human-readable summary of what happened. Always populated so clients can render something even without knowing the action name." }, "data": { "description": "Structured payload for input-requesting actions. Present on `ask_user_questions`, `exit_plan_mode`, `get_or_request_integration`, and `configure_vercel_connect` parts when the agent is waiting on you; narrow by the part `name`. Omitted for actions that do not carry structured data.", "anyOf": [ { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Question identifier. Pass back as `questionId` when resolving with an `answered-questions` task." }, "question": { "type": "string", "description": "The full question text." }, "header": { "type": "string", "description": "Short label for the question." }, "multiSelect": { "type": "boolean", "description": "Whether more than one option may be selected." }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Option identifier." }, "label": { "type": "string", "description": "Display label. Pass matching labels back in `selectedLabels` when resolving." }, "description": { "description": "Optional longer explanation of the option.", "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, "description": "The available answer options." } }, "required": [ "id", "question", "header", "multiSelect", "options" ], "additionalProperties": false }, "description": "The questions the agent is waiting for answers to. Resolve with an `answered-questions` task." } }, "required": [ "questions" ], "additionalProperties": false, "description": "Structured payload for an `ask_user_questions` agent action." }, { "type": "object", "properties": { "plan": { "type": "string", "description": "The full proposed plan, as Markdown." }, "summary": { "description": "A concise summary of the plan, when available.", "type": "string" }, "path": { "type": "string", "description": "The path the plan applies to." } }, "required": [ "plan", "path" ], "additionalProperties": false, "description": "Structured payload for an `exit_plan_mode` agent action." }, { "type": "object", "properties": { "requestedIntegrations": { "type": "array", "items": { "type": "string" }, "description": "Integration names the agent is asking you to connect (for example, \"Neon\"). Pass these back in `connectedIntegrationNames` when resolving with a `confirmed-steps` task." }, "requestedMcpPresets": { "type": "array", "items": { "type": "string" }, "description": "MCP preset names the agent is asking you to add. Pass these back in `connectedMcpPresetNames` when resolving with a `confirmed-steps` task." } }, "required": [ "requestedIntegrations", "requestedMcpPresets" ], "additionalProperties": false, "description": "Structured payload for a `get_or_request_integration` agent action." }, { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "setup-required" ], "description": "The agent is waiting for connector setup to be completed in a browser." }, "requestId": { "type": "string", "description": "Setup request identifier. Pass as `requestId` to GET /chats/{chatId}/connect/status to poll for completion." }, "service": { "type": "string", "description": "The service being connected (for example, \"linear\")." }, "serviceIconUrl": { "description": "Icon URL for the service, hosted on vercel.com.", "type": "string", "format": "uri" }, "connectorName": { "type": "string", "description": "Display name of the connector being created." }, "setupUrl": { "type": "string", "format": "uri", "description": "Open this vercel.com URL in a browser to complete connector setup. Requires a vercel.com session for a member of the team." }, "environments": { "type": "array", "items": { "type": "string", "enum": [ "production", "preview", "development" ], "description": "Vercel environment the connector is attached to." }, "description": "Environments the connector will be attached to." }, "triggerPath": { "description": "Webhook trigger path that will be registered on the connector, when requested.", "type": "string" }, "createdProject": { "description": "Vercel project auto-created for this chat during setup, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "requestId", "service", "connectorName", "setupUrl", "environments" ], "additionalProperties": false, "description": "Connector setup is pending. Complete setup at `setupUrl`, poll GET /chats/{chatId}/connect/status until `ready`, then resolve with a `vercel-connect-setup` task." }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "completed" ], "description": "The Connect action finished; no user input is needed." }, "action": { "type": "string", "enum": [ "list", "create", "attach" ], "description": "The Connect action that ran." }, "summary": { "type": "string", "description": "Human-readable result summary." }, "connectors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Connector identifier." }, "name": { "type": "string", "description": "Connector display name." }, "service": { "description": "Connected service identifier.", "type": "string" }, "attachedToProject": { "type": "boolean", "description": "Whether the connector is attached to the chat’s Vercel project." } }, "required": [ "id", "name", "attachedToProject" ], "additionalProperties": false }, "description": "Connectors involved in the action." }, "createdProject": { "description": "Vercel project created during the action, when applicable.", "type": "object", "properties": { "id": { "type": "string", "description": "Vercel project identifier." }, "name": { "type": "string", "description": "Vercel project name." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "status", "action", "summary", "connectors" ], "additionalProperties": false, "description": "The Connect action finished; no user input is needed." } ], "description": "Structured payload for a `configure_vercel_connect` agent action." } ] }, "startedAt": { "description": "ISO timestamp when this part began.", "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))$" }, "finishedAt": { "description": "ISO timestamp when this part completed.", "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))$" } }, "required": [ "type", "name", "summary" ], "additionalProperties": false, "description": "A typed escape hatch for agent actions that don’t fit the other part types. Forward-compatible: new action types may appear without API version changes." } ], "description": "A single entry in the ordered narrative of a message. Iterate `parts` in order to render the full transcript." }, "description": "Ordered list of parts that make up the message. Iterate to render the full narrative including thinking, file operations, tool calls, and prose." }, "finishReason": { "anyOf": [ { "type": "string", "enum": [ "stop", "length", "content-filter", "tool-calls", "error", "other" ], "description": "The reason why message generation finished, including standard completion reasons and error states." }, { "type": "null" } ], "description": "Why generation ended. Null while the agent is still generating; once non-null, the message is final and safe to consume." }, "restorable": { "type": "boolean", "description": "True when this is an assistant message that produced restorable code and is not the currently active code." }, "attachments": { "description": "Files attached to this message.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the attachment." }, "name": { "description": "Original filename, when available.", "type": "string" }, "contentType": { "description": "MIME type.", "type": "string" }, "size": { "description": "Size in bytes.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "url" ], "additionalProperties": false } }, "authorId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ID of the user who authored a user message; null for assistant messages." }, "usage": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Token counts for this message." }, "creditsCost": { "type": "object", "properties": { "input": { "type": "number", "description": "Prompt input value (non-cached)." }, "output": { "type": "number", "description": "Completion output value." }, "cacheRead": { "type": "number", "description": "Cache-read input value." }, "cacheWrite": { "type": "number", "description": "Cache-write input value." }, "total": { "type": "number", "description": "Sum of input, output, cacheRead, and cacheWrite." } }, "required": [ "input", "output", "cacheRead", "cacheWrite", "total" ], "additionalProperties": false, "description": "Credit cost for this message." } }, "required": [ "tokens", "creditsCost" ], "additionalProperties": false, "description": "Token usage and credit cost. All values are zero on user messages and on assistant messages that have not yet generated tokens." } }, "required": [ "id", "chatId", "role", "createdAt", "updatedAt", "content", "parts", "finishReason", "restorable", "authorId", "usage" ], "additionalProperties": false, "description": "A single message in a chat." }, "description": "The user and assistant messages created by the restore, in chronological order." } }, "required": [ "messages" ], "additionalProperties": false, "description": "The messages created to record the restore." } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/duplicate": { "post": { "tags": [ "Chats" ], "summary": "Duplicate Chat", "description": "Creates a new chat by duplicating an existing chat.", "operationId": "chats.duplicate", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "default": { "privacy": "private" }, "type": "object", "properties": { "privacy": { "default": "private", "description": "Visibility setting for the duplicated chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Custom title for the duplicated chat. If omitted, the original title is reused with an incremented suffix (e.g. \"My Chat (2)\").", "type": "string" } }, "required": [ "privacy" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "default": { "privacy": "private" }, "type": "object", "properties": { "privacy": { "default": "private", "description": "Visibility setting for the duplicated chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Custom title for the duplicated chat. If omitted, the original title is reused with an incremented suffix (e.g. \"My Chat (2)\").", "type": "string" } }, "required": [ "privacy" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "default": { "privacy": "private" }, "type": "object", "properties": { "privacy": { "default": "private", "description": "Visibility setting for the duplicated chat.", "type": "string", "enum": [ "public", "private", "team", "team-edit", "unlisted" ] }, "title": { "description": "Custom title for the duplicated chat. If omitted, the original title is reused with an incremented suffix (e.g. \"My Chat (2)\").", "type": "string" } }, "required": [ "privacy" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Response for status 201", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chat" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/deploy": { "post": { "tags": [ "Chats" ], "summary": "Deploy Chat", "description": "Triggers a Vercel deployment for a chat. Creates a Vercel project if one does not exist.", "operationId": "chats.deploy", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "A deployment created for a chat. The deployment build runs asynchronously on Vercel - use the Vercel API with the returned deploymentId to track status, fetch logs, or read build errors.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deploymentId": { "type": "string", "description": "Unique identifier of the Vercel deployment." }, "vercelProjectId": { "type": "string", "description": "The Vercel project that the deployment belongs to." } }, "required": [ "deploymentId", "vercelProjectId" ], "additionalProperties": false, "description": "A deployment created for a chat. The deployment build runs asynchronously on Vercel - use the Vercel API with the returned deploymentId to track status, fetch logs, or read build errors." } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/vercel-project": { "post": { "tags": [ "Chats" ], "summary": "Create Vercel Project", "description": "Creates a Vercel project and attaches it to the chat.", "operationId": "chats.createVercelProject", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "default": {}, "type": "object", "properties": { "name": { "description": "Name for the Vercel project. When omitted, the chat's title is used.", "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "default": {}, "type": "object", "properties": { "name": { "description": "Name for the Vercel project. When omitted, the chat's title is used.", "type": "string", "minLength": 1 } }, "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "default": {}, "type": "object", "properties": { "name": { "description": "Name for the Vercel project. When omitted, the chat's title is used.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Response for status 201", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "vercelProjectId": { "type": "string", "description": "Created Vercel project ID." } }, "required": [ "vercelProjectId" ], "additionalProperties": false } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Response for status 409", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/chats/{chatId}/resume": { "post": { "tags": [ "Chats" ], "summary": "Resume Chat Stream", "description": "Resumes consumption of the active assistant generation as Server-Sent Events. If the latest message has already finished, returns a closing chat-state event. The response is `text/event-stream`; each event is `data: \\n\\n` where the JSON conforms to ChatStreamEvent.", "operationId": "chats.resume", "parameters": [ { "name": "chatId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the chat." } } ], "responses": { "200": { "description": "A single Server-Sent Events payload emitted by streaming chat endpoints. Each SSE event is `data: \\n\\n` where the JSON conforms to one of the union members.", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/ChatStreamEvent" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp-servers": { "get": { "tags": [ "MCP Servers" ], "summary": "List MCP Servers", "description": "Retrieves all MCP servers configured for the current user.", "operationId": "mcpServers.list", "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the MCP server." }, "name": { "type": "string", "description": "Display name of the MCP server." }, "url": { "type": "string", "description": "URL endpoint of the MCP server." }, "description": { "type": "string", "description": "Optional description of the MCP server." }, "createdAt": { "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))$", "description": "ISO timestamp of when the server was created." }, "updatedAt": { "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))$", "description": "ISO timestamp of the last update." }, "userId": { "type": "string", "description": "ID of the user who created the server." }, "enabled": { "type": "boolean", "description": "Whether the MCP server is enabled." }, "auth": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ], "description": "Authentication configuration for the MCP server." }, "scope": { "type": "string", "enum": [ "user", "team" ], "description": "Scope of the MCP server configuration." } }, "required": [ "id", "name", "url", "description", "createdAt", "updatedAt", "userId", "enabled", "auth", "scope" ], "additionalProperties": false } } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "MCP Servers" ], "summary": "Create MCP Server", "description": "Creates a new MCP server configuration. Limited to 10 servers per user.", "operationId": "mcpServers.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the MCP server." }, "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "URL endpoint of the MCP server." }, "description": { "description": "Optional description of the MCP server.", "type": "string", "maxLength": 500 }, "enabled": { "default": true, "description": "Whether the server should be enabled.", "type": "boolean" }, "auth": { "default": { "type": "none" }, "description": "Authentication configuration.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ] }, "scope": { "default": "user", "description": "Scope of the MCP server configuration.", "type": "string", "enum": [ "user", "team" ] } }, "required": [ "name", "url", "enabled", "auth", "scope" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the MCP server." }, "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "URL endpoint of the MCP server." }, "description": { "description": "Optional description of the MCP server.", "type": "string", "maxLength": 500 }, "enabled": { "default": true, "description": "Whether the server should be enabled.", "type": "boolean" }, "auth": { "default": { "type": "none" }, "description": "Authentication configuration.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ] }, "scope": { "default": "user", "description": "Scope of the MCP server configuration.", "type": "string", "enum": [ "user", "team" ] } }, "required": [ "name", "url", "enabled", "auth", "scope" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name for the MCP server." }, "url": { "type": "string", "maxLength": 500, "format": "uri", "description": "URL endpoint of the MCP server." }, "description": { "description": "Optional description of the MCP server.", "type": "string", "maxLength": 500 }, "enabled": { "default": true, "description": "Whether the server should be enabled.", "type": "boolean" }, "auth": { "default": { "type": "none" }, "description": "Authentication configuration.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ] }, "scope": { "default": "user", "description": "Scope of the MCP server configuration.", "type": "string", "enum": [ "user", "team" ] } }, "required": [ "name", "url", "enabled", "auth", "scope" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp-servers/{mcpServerId}": { "get": { "tags": [ "MCP Servers" ], "summary": "Get MCP Server", "description": "Retrieves a specific MCP server by ID.", "operationId": "mcpServers.get", "parameters": [ { "name": "mcpServerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the MCP server." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "MCP Servers" ], "summary": "Update MCP Server", "description": "Updates an existing MCP server configuration.", "operationId": "mcpServers.update", "parameters": [ { "name": "mcpServerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the MCP server to update." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "New display name.", "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "description": "New URL endpoint.", "type": "string", "maxLength": 500, "format": "uri" }, "description": { "description": "New description.", "type": "string", "maxLength": 500 }, "enabled": { "description": "Enable or disable.", "type": "boolean" }, "auth": { "description": "New authentication configuration.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ] }, "scope": { "description": "New scope.", "type": "string", "enum": [ "user", "team" ] } }, "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "New display name.", "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "description": "New URL endpoint.", "type": "string", "maxLength": 500, "format": "uri" }, "description": { "description": "New description.", "type": "string", "maxLength": 500 }, "enabled": { "description": "Enable or disable.", "type": "boolean" }, "auth": { "description": "New authentication configuration.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ] }, "scope": { "description": "New scope.", "type": "string", "enum": [ "user", "team" ] } }, "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "New display name.", "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "description": "New URL endpoint.", "type": "string", "maxLength": 500, "format": "uri" }, "description": { "description": "New description.", "type": "string", "maxLength": 500 }, "enabled": { "description": "Enable or disable.", "type": "boolean" }, "auth": { "description": "New authentication configuration.", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bearer" ] }, "token": { "type": "string", "description": "Bearer token for authentication." } }, "required": [ "type", "token" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom-headers" ] }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom headers to include in requests." } }, "required": [ "type", "headers" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "oauth" ] }, "config": { "description": "OAuth configuration discovered or manually set.", "type": "object", "properties": { "authorizationUrl": { "type": "string", "format": "uri" }, "tokenUrl": { "type": "string", "format": "uri" }, "registrationUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "usePKCE": { "type": "boolean" }, "issuer": { "type": "string" }, "resource": { "type": "string" }, "clientIdMetadataDocumentSupported": { "type": "boolean" } }, "required": [ "authorizationUrl", "tokenUrl", "clientId", "scopes", "usePKCE" ], "additionalProperties": false }, "connected": { "default": false, "description": "Whether OAuth is currently connected.", "type": "boolean" }, "expiresAt": { "description": "ISO timestamp when the token expires.", "type": "string" } }, "required": [ "type", "connected" ], "additionalProperties": false } ] }, "scope": { "description": "New scope.", "type": "string", "enum": [ "user", "team" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServer" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "MCP Servers" ], "summary": "Delete MCP Server", "description": "Deletes an MCP server and cleans up associated OAuth tokens. This action is irreversible.", "operationId": "mcpServers.delete", "parameters": [ { "name": "mcpServerId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the MCP server to delete." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ], "additionalProperties": false } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settings/preview-hosts": { "get": { "tags": [ "Settings" ], "summary": "Get Trusted Preview Hosts", "description": "Returns the hostname patterns trusted to embed previews for the current team. Organization child teams inherit the parent organization’s hosts.", "operationId": "settings.getPreviewHosts", "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustedPreviewHosts" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Settings" ], "summary": "Set Trusted Preview Hosts", "description": "Sets the host patterns trusted to embed previews for a standalone team or parent organization. Organization child teams cannot override this setting.", "operationId": "settings.setPreviewHosts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "hosts": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "The complete list of exact or wildcard hostname patterns trusted to embed previews. Provide hostnames only, without a scheme, port, path, userinfo, query string, or fragment. Use *.example.com for exactly one subdomain label and **.example.com for one or more. Wildcards do not include example.com itself; add the apex as a separate entry when needed." } }, "required": [ "hosts" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "hosts": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "The complete list of exact or wildcard hostname patterns trusted to embed previews. Provide hostnames only, without a scheme, port, path, userinfo, query string, or fragment. Use *.example.com for exactly one subdomain label and **.example.com for one or more. Wildcards do not include example.com itself; add the apex as a separate entry when needed." } }, "required": [ "hosts" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "hosts": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 256 }, "description": "The complete list of exact or wildcard hostname patterns trusted to embed previews. Provide hostnames only, without a scheme, port, path, userinfo, query string, or fragment. Use *.example.com for exactly one subdomain label and **.example.com for one or more. Wildcards do not include example.com itself; add the apex as a separate entry when needed." } }, "required": [ "hosts" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustedPreviewHosts" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hooks": { "get": { "tags": [ "Webhooks" ], "summary": "List Webhooks", "description": "Retrieves a list of all webhooks in your workspace.", "operationId": "webhooks.list", "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the webhook." }, "name": { "type": "string", "description": "The name of the webhook." } }, "required": [ "id", "name" ], "additionalProperties": false } } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create Webhook", "description": "Creates a new webhook that listens for specific events. Supports optional association with a chat.", "operationId": "webhooks.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "description": "A human-readable name for the webhook." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." }, "description": "List of event types the webhook should subscribe to." }, "url": { "type": "string", "format": "uri", "description": "The target URL to receive the webhook payloads." }, "chatId": { "default": null, "description": "The ID of a chat to scope the webhook to.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "events", "url", "chatId" ], "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "description": "A human-readable name for the webhook." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." }, "description": "List of event types the webhook should subscribe to." }, "url": { "type": "string", "format": "uri", "description": "The target URL to receive the webhook payloads." }, "chatId": { "default": null, "description": "The ID of a chat to scope the webhook to.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "events", "url", "chatId" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "description": "A human-readable name for the webhook." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." }, "description": "List of event types the webhook should subscribe to." }, "url": { "type": "string", "format": "uri", "description": "The target URL to receive the webhook payloads." }, "chatId": { "default": null, "description": "The ID of a chat to scope the webhook to.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "events", "url", "chatId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/hooks/{hookId}": { "get": { "tags": [ "Webhooks" ], "summary": "Get Webhook", "description": "Retrieves the details of a specific webhook using its ID.", "operationId": "webhooks.get", "parameters": [ { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the webhook to retrieve." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update Webhook", "description": "Updates the configuration of an existing webhook, including its name, event subscriptions, or target URL.", "operationId": "webhooks.update", "parameters": [ { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the webhook to update." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A new display name for the webhook.", "type": "string" }, "events": { "description": "Updated list of event types to subscribe to.", "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." } }, "url": { "description": "A new target URL to receive webhook payloads.", "type": "string", "format": "uri" } }, "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A new display name for the webhook.", "type": "string" }, "events": { "description": "Updated list of event types to subscribe to.", "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." } }, "url": { "description": "A new target URL to receive webhook payloads.", "type": "string", "format": "uri" } }, "additionalProperties": false } }, "multipart/form-data": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A new display name for the webhook.", "type": "string" }, "events": { "description": "Updated list of event types to subscribe to.", "type": "array", "items": { "type": "string", "enum": [ "chat.created", "chat.updated", "chat.deleted", "message.created", "message.updated", "message.deleted", "message.finished" ], "description": "The event type that triggers a webhook. A webhook will be invoked whenever the specified lifecycle event occurs." } }, "url": { "description": "A new target URL to receive webhook payloads.", "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Response for status 422", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete Webhook", "description": "Deletes a webhook. This action is irreversible.", "operationId": "webhooks.delete", "parameters": [ { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The unique identifier of the webhook to delete." } } ], "responses": { "200": { "description": "Response for status 200", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "deleted" ], "additionalProperties": false } } } }, "401": { "description": "Response for status 401", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Response for status 403", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Response for status 404", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Response for status 500", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "servers": [ { "url": "https://api.v0.dev/v2" } ] }