{"openapi":"3.1.0","info":{"title":"OpenCharts API","version":"1.0.0","description":"The OpenCharts public REST API — create and manage projects, sheets, boards, personas, agents, and generate media (images, video, music, code) with Theo. Available on the Pro and Teams plans. Authenticate with an API key: `Authorization: Bearer oc_...`."},"servers":[{"url":"https://www.opencharts.com/api/v1","description":"Production"}],"tags":[{"name":"Meta"},{"name":"Account"},{"name":"Personas"},{"name":"Projects"},{"name":"Creation"},{"name":"Sheets"},{"name":"Boards"},{"name":"Chat"},{"name":"Conversations"},{"name":"Media"},{"name":"Jobs"},{"name":"Agents"},{"name":"Research"},{"name":"Webhooks"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key (oc_...)","description":"Pass an OpenCharts API key as a Bearer token. Create keys in the Developers hub. Keys carry `read` / `write` / `ai` scopes."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["code","message","requestId"]}},"required":["error"]},"ListEnvelope":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"total":{"type":"integer"},"cursor":{"type":"string","nullable":true}},"required":["data","total"]},"JobEnvelope":{"type":"object","properties":{"jobId":{"type":"string","description":"Type-prefixed public id (vid_/song_/code_/res_)."},"type":{"type":"string","enum":["video","song","code","research"]},"status":{"type":"string","enum":["queued","processing","complete","failed"]},"rawStatus":{"type":"string"},"pollUrl":{"type":"string"},"progressMessage":{"type":"string"},"result":{"type":"object","additionalProperties":true,"nullable":true},"error":{"type":"string","nullable":true}},"required":["jobId","status","pollUrl"]},"ChatArtifact":{"type":"object","description":"A tool output surfaced on a chat turn: a created project, generated media, a search result, or an async job handle. Non-streaming responses carry artifacts on `message.artifacts`; streams deliver each one as the `output` of a `tool-output-available` SSE event.","properties":{"type":{"type":"string","description":"Artifact kind. Creation/media kinds reachable via the API tool set include: flowchart | whiteboard | notes | presentation | document | table | sheet | social_board | image | video | song | podcast | web_search | brand_theme | platform_action | error."},"title":{"type":"string"},"projectId":{"type":"string","description":"Set on project-backed artifacts (the created project's id; for social_board it is the board id)."},"projectType":{"type":"string","enum":["chart","notes","presentation","code","sheet","simulation"],"description":"Editor route family for project-backed artifacts (flowcharts + whiteboards are `chart`)."},"openUrl":{"type":"string","format":"uri","description":"Absolute OpenCharts editor deep link for project-backed artifacts. URL formats: /editor/{projectId} (flowchart + whiteboard), /notes/{projectId}, /presentations/{projectId}, /sheets/{projectId}, /simulations/{projectId}, /code-editor/{projectId}, /boards/{boardId}."},"data":{"type":"object","description":"Type-specific payload. Async media artifacts (video / song) carry `apiJobId` (type-prefixed) + `pollUrl` — poll at GET /jobs/{id}. Image artifacts carry the image URL. Board artifacts carry `boardId` + card counts.","properties":{"apiJobId":{"type":"string","description":"Type-prefixed job id (vid_/song_) for async media artifacts."},"pollUrl":{"type":"string","description":"Poll path for async media artifacts (`/api/v1/jobs/{apiJobId}`)."}},"additionalProperties":true}},"required":["type","title"]},"ChatJsonResponse":{"type":"object","description":"The assembled non-streaming chat result (`stream: false`).","properties":{"conversationId":{"type":"string"},"mode":{"type":"string","enum":["fast","think"]},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"string"},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/ChatArtifact"}},"engine":{"type":"object","nullable":true,"description":"Which lab engine Theo orchestrated for this reply — the Theo tier plus the public lab and model name of the engine that actually answered (Theo walks a fallback chain; this is the one that succeeded). Public names only. `null` for white-label tenants.","properties":{"theoName":{"type":"string","description":"Theo tier name, e.g. `Theo Think`."},"lab":{"type":"string","description":"Lab key, e.g. `anthropic`, `google`, `openai`, `theovex`."},"labName":{"type":"string","description":"Public lab name, e.g. `Anthropic`."},"model":{"type":"string","description":"Public model name, e.g. `Claude Sonnet 5`."}},"required":["theoName","lab","labName","model"]}},"required":["role","content","artifacts"]},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer","nullable":true},"outputTokens":{"type":"integer","nullable":true}}}},"required":["conversationId","message"]},"ChatRequest":{"type":"object","properties":{"conversationId":{"type":"string","description":"Continue an existing conversation (prior history loads server-side)."},"message":{"type":"string","description":"The prompt (shorthand for a single user message)."},"messages":{"type":"array","maxItems":40,"items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}},"required":["role","content"]}},"mode":{"type":"string","enum":["fast","think"],"description":"v1 launch modes."},"stream":{"type":"boolean","default":true,"description":"true = AI SDK UI-message SSE stream; false = assembled JSON message + artifacts."}}},"AgentMessageRequest":{"type":"object","description":"One message to a goal-driven Theo Agent. Reuse `threadId` to continue a conversation the agent remembers; omit it to start a new thread (the response carries the minted id).","properties":{"message":{"type":"string","maxLength":20000},"threadId":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9_.:-]{1,64}$","description":"Caller-chosen conversation handle (letters, digits, `_ . : -`)."}},"required":["message"]},"AgentMessageAccepted":{"type":"object","properties":{"runId":{"type":"string"},"threadId":{"type":"string"},"agentId":{"type":"string"},"status":{"type":"string","enum":["queued"]},"resultUrl":{"type":"string","description":"Poll here for the reply (`GET /agents/{id}/runs/{runId}/result`)."}},"required":["runId","threadId","agentId","status","resultUrl"]},"AgentRunArtifact":{"type":"object","description":"Something the agent made: an OpenCharts project (editor or public link) or a downloadable file.","properties":{"kind":{"type":"string","enum":["project","file"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"projectId":{"type":"string"},"fileId":{"type":"string"}},"required":["kind","title","url"]},"AgentRunResult":{"type":"object","description":"What a run produced. `queued` / `running` while the agent works; `paused` when an action needs the owner's approval (`pendingApproval` names it); `completed` with `reply` + `artifacts`; `failed` with `error`.","properties":{"runId":{"type":"string"},"agentId":{"type":"string"},"threadId":{"type":"string","nullable":true},"status":{"type":"string","enum":["queued","running","paused","completed","failed"]},"reply":{"type":"string","nullable":true,"description":"The agent's reply (markdown) once completed."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/AgentRunArtifact"}},"pendingApproval":{"type":"object","nullable":true,"properties":{"actionSlug":{"type":"string"},"approveUrl":{"type":"string"}},"required":["actionSlug","approveUrl"]},"error":{"type":"string","nullable":true},"creditsUsed":{"type":"integer"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true},"pollUrl":{"type":"string"}},"required":["runId","agentId","status","reply","artifacts","pendingApproval","error","creditsUsed","pollUrl"]},"AgentRunApproveRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]}},"required":["decision"]},"AgentRunApproveAccepted":{"type":"object","properties":{"runId":{"type":"string"},"decision":{"type":"string","enum":["approve","reject"]},"status":{"type":"string","enum":["resuming"]}},"required":["runId","decision","status"]},"AgentUsage":{"type":"object","description":"The agent's own run + credit usage over the window (the same numbers it reports when asked what it cost).","properties":{"agentId":{"type":"string"},"days":{"type":"integer"},"since":{"type":"string"},"runs":{"type":"integer"},"creditsUsed":{"type":"integer"},"byStatus":{"type":"object","additionalProperties":{"type":"integer"}},"byTrigger":{"type":"object","additionalProperties":{"type":"integer"}},"avgDurationMs":{"type":"integer","nullable":true},"lastRunAt":{"type":"string","nullable":true},"truncated":{"type":"boolean"}},"required":["agentId","days","since","runs","creditsUsed","byStatus","byTrigger","truncated"]},"AgentCompletionRequest":{"type":"object","description":"An OpenAI chat-completions request aimed at a Theo Agent. Only the last `user` message is sent; the agent remembers the conversation by `metadata.thread_id` (or `user`). `stream: true` returns a protocol-compatible SSE stream that delivers the whole reply as one final chunk.","properties":{"model":{"type":"string","pattern":"^agent:[A-Za-z0-9_-]{1,64}$","description":"`agent:<agentId>`."},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"description":"A string, or OpenAI text content parts."}},"required":["role","content"]}},"stream":{"type":"boolean","default":false,"description":"false (default): the assembled JSON. true: an SSE stream with keepalive comments while the agent works, then one `chat.completion.chunk` with the full reply and `[DONE]`."},"user":{"type":"string","description":"Optional end-user id; doubles as the thread when `metadata.thread_id` is absent."},"metadata":{"type":"object","properties":{"thread_id":{"type":"string"}},"additionalProperties":true}},"required":["model","messages"]},"AgentCompletionResponse":{"type":"object","description":"A standard `chat.completion` object plus an `opencharts` extension.","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"string"}},"required":["role","content"]},"finish_reason":{"type":"string","enum":["stop"]}},"required":["index","message","finish_reason"]}},"usage":{"type":"object","description":"Raw engine tokens across the agent's turns (credits are billed separately at each engine's rate).","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"required":["prompt_tokens","completion_tokens","total_tokens"]},"opencharts":{"type":"object","properties":{"agentId":{"type":"string"},"runId":{"type":"string"},"threadId":{"type":"string"},"status":{"type":"string","enum":["completed","paused"]},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/AgentRunArtifact"}},"pendingApproval":{"type":"object","nullable":true,"properties":{"actionSlug":{"type":"string"},"approveUrl":{"type":"string"}}},"resultUrl":{"type":"string"}},"required":["agentId","runId","threadId","status","artifacts","resultUrl"]}},"required":["id","object","created","model","choices","opencharts"]},"ConversationCreate":{"type":"object","properties":{"title":{"type":"string","maxLength":256},"mode":{"type":"string","description":"Chat mode preference (e.g. `fast`, `think`)."}}},"ConversationUpdate":{"type":"object","properties":{"title":{"type":"string","maxLength":256},"mode":{"type":"string","description":"Chat mode preference (e.g. `fast`, `think`)."}}},"ExtractFlowchartRequest":{"type":"object","properties":{"documentBase64":{"type":"string","description":"Base64-encoded document content (no `data:` prefix). Max 10MB decoded."},"mimeType":{"type":"string","enum":["application/pdf","application/vnd.openxmlformats-officedocument.presentationml.presentation","image/png","image/jpeg","image/webp"]},"fileName":{"type":"string","description":"Original file name (used as a title fallback)."}},"required":["documentBase64","mimeType"]},"ImageRequest":{"type":"object","properties":{"prompt":{"type":"string"},"engine":{"type":"string","enum":["auto","theo-creative","theo-imagine","theo-photo","theo-rapid","theo-design","theo-studio","theo-type","theo-ultra","grok-theo"],"description":"Defaults to theo-ultra (highest fidelity) on paid plans; a Free-plan call falls back to theo-creative and the response carries a `notes` entry saying so. An explicit theo-ultra on Free returns 403. grok-theo (Grok + Theo, the xAI co-brand) is accepted only on workspaces that enable it; elsewhere it resolves to the default."},"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4"]},"style":{"type":"string"},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5},"includeBase64":{"type":"boolean"}},"required":["prompt"]},"VideoRequest":{"type":"object","description":"A Theo Reel render. `modelTier` picks the engine: `fast` / `max` render a fixed ~8s 1080p clip (cheap, quick), while `cinema` / `cinema-ultra` are the premium tiers, offering longer takes, a selectable quality and length, six frame shapes, and many reference images. A premium render costs several times a standard one, so pick deliberately. Any knob the resolved tier cannot serve steps DOWN to its ceiling and the 202 response reports why in `notes`. Nothing is silently ignored, and nothing is refused for asking too much.","properties":{"prompt":{"type":"string","description":"The scene: subject, action, camera, setting, mood."},"aspectRatio":{"type":"string","enum":["21:9","16:9","4:3","1:1","3:4","9:16"],"description":"Frame shape. Default 16:9. The standard tiers render 16:9 and 9:16 only; another shape resolves to the NEAREST ratio they do render."},"modelTier":{"type":"string","enum":["fast","max","cinema","cinema-ultra"],"default":"max","description":"Which tier renders the clip. A premium tier on a workspace that has not enabled it lands on `max` with a note saying so."},"resolution":{"type":"string","enum":["480p","720p","1080p","4k"],"description":"Output quality. Premium tiers only; the standard tiers always render 1080p. `cinema` reaches 4k, and `cinema-ultra` tops out at 720p (it trades quality for length)."},"clipSeconds":{"type":"integer","minimum":4,"maximum":30,"description":"Clip length in seconds. Premium tiers only; the standard tiers render a fixed ~8s clip. `cinema` reaches 15s and `cinema-ultra` 30s; over a tier's ceiling clamps to its longest."},"referenceImageUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":30,"description":"ONE url = the opening frame to animate (image-to-video). SEVERAL = how the subject should look. Trimmed to the resolved tier's own budget (1 on the standard tiers, 9 on Cinema, 30 on Cinema Ultra); when only one survives it becomes the opening frame."},"referenceImageUrl":{"type":"string","format":"uri","description":"Single first-frame anchor. Kept for compatibility; prefer `referenceImageUrls`. Passing both puts this one first."}},"required":["prompt"]},"SongRequest":{"type":"object","properties":{"style":{"type":"string"},"title":{"type":"string"},"lyrics":{"type":"string"},"autoLyrics":{"type":"boolean"},"instrumental":{"type":"boolean"},"tier":{"type":"string","enum":["auto","premium","fast"]}},"required":["style"]},"CodeBuildRequest":{"type":"object","properties":{"prompt":{"type":"string"},"name":{"type":"string"},"framework":{"type":"string","enum":["html","react","auto"]},"planFirst":{"type":"boolean"}},"required":["prompt"]},"ResearchRequest":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"],"additionalProperties":true},"ResearchJobStatus":{"type":"object","description":"LEGACY research poll shape (GET /research/{jobId} only). The canonical poll is GET /jobs/{id} with the res_-prefixed id, which returns the neutral JobEnvelope.","properties":{"jobId":{"type":"string","description":"The raw pipeline job id (no res_ prefix)."},"status":{"type":"string","description":"The pipeline's raw status token. `complete`, `partial`, and `failed` are terminal."},"isComplete":{"type":"boolean","description":"True once the job reached a terminal, non-failed state (`complete` or `partial`)."},"content":{"type":"string","nullable":true,"description":"The markdown report (terminal states)."},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"domain":{"type":"string"}}}},"searchCount":{"type":"integer"},"readCount":{"type":"integer"},"totalTokens":{"type":"integer"},"errorMessage":{"type":"string","nullable":true},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true}},"required":["jobId","status","isComplete"]},"SheetOpsRequest":{"type":"object","properties":{"ops":{"type":"array","items":{"type":"object","additionalProperties":true}},"propose":{"type":"boolean"},"summary":{"type":"string"}},"required":["ops"]},"SheetEditRequest":{"type":"object","properties":{"instruction":{"type":"string"},"propose":{"type":"boolean"}},"required":["instruction"]},"WebhookCreate":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["project.created","project.updated","project.shared","project.deleted","team.member_added","team.member_removed","export.completed","meeting.completed","code_canvas.iteration_complete","code_canvas.iteration_failed","code_canvas.published","podcast.completed","podcast.failed","notes_movie.completed","notes_movie.failed","skill.installed","evi.run_completed","evi.run_failed","video.completed","video.failed","song.completed","song.failed","code_build.completed","code_build.failed","research.completed","research.failed","email.received"]},"minItems":1,"description":"Event names to subscribe to. The enum lists every currently emitted event (generated from the same registry the dispatcher validates against); unknown or not-yet-emitted events return a 400 naming them. Naming note: the `code` job type (job ids `code_...`) emits `code_build.*`, and Theo Agent runs emit `evi.run_*`."}},"required":["name","url","events"]},"WebhookUpdate":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["project.created","project.updated","project.shared","project.deleted","team.member_added","team.member_removed","export.completed","meeting.completed","code_canvas.iteration_complete","code_canvas.iteration_failed","code_canvas.published","podcast.completed","podcast.failed","notes_movie.completed","notes_movie.failed","skill.installed","evi.run_completed","evi.run_failed","video.completed","video.failed","song.completed","song.failed","code_build.completed","code_build.failed","research.completed","research.failed","email.received"]}},"isActive":{"type":"boolean"}}}},"responses":{"BadRequest":{"description":"Invalid request (validation error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the required scope, or the plan lacks API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/openapi":{"get":{"operationId":"get_openapi","summary":"Fetch this OpenAPI document.","tags":["Meta"],"x-required-scope":"public","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[]}},"/account":{"get":{"operationId":"get_account","summary":"Get the authenticated account (whoami).","tags":["Account"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/account/credits":{"get":{"operationId":"get_account_credits","summary":"Get the plan + AI credit balance.","tags":["Account"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/personas":{"get":{"operationId":"get_personas","summary":"List personas.","tags":["Personas"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"post_personas","summary":"Create a persona.","tags":["Personas"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/personas/{id}":{"get":{"operationId":"get_personas_id","summary":"Get a persona.","tags":["Personas"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"patch":{"operationId":"patch_personas_id","summary":"Update a persona.","tags":["Personas"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"delete":{"operationId":"delete_personas_id","summary":"Delete a persona.","tags":["Personas"],"x-required-scope":"write","responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/personas/{id}/publish":{"post":{"operationId":"post_personas_id_publish","summary":"Publish a persona.","tags":["Personas"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/personas/{id}/deployments":{"get":{"operationId":"get_personas_id_deployments","summary":"List a persona's deployments.","tags":["Personas"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"post":{"operationId":"post_personas_id_deployments","summary":"Create a persona deployment.","tags":["Personas"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/personas/{id}/conversations":{"post":{"operationId":"post_personas_id_conversations","summary":"Start a persona conversation.","tags":["Personas"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/personas/{id}/conversations/{cid}/end":{"post":{"operationId":"post_personas_id_conversations_cid_end","summary":"End a persona conversation.","tags":["Personas"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"cid","in":"path","required":true,"schema":{"type":"string"},"description":"The `cid` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/personas/{id}/conversations/{cid}/events":{"get":{"operationId":"get_personas_id_conversations_cid_events","summary":"List conversation events.","tags":["Personas"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"cid","in":"path","required":true,"schema":{"type":"string"},"description":"The `cid` path parameter."}]}},"/personas/faces":{"get":{"operationId":"get_personas_faces","summary":"List available persona faces.","tags":["Personas"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/projects":{"get":{"operationId":"get_projects","summary":"List projects.","tags":["Projects"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/projects/{id}":{"get":{"operationId":"get_projects_id","summary":"Get a project.","tags":["Projects"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"patch":{"operationId":"patch_projects_id","summary":"Update a project's metadata or content.","tags":["Projects"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"delete":{"operationId":"delete_projects_id","summary":"Delete a project.","tags":["Projects"],"x-required-scope":"write","responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/flowcharts":{"post":{"operationId":"post_flowcharts","summary":"Create a flowchart project.","tags":["Creation"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/whiteboards":{"post":{"operationId":"post_whiteboards","summary":"Create a whiteboard project.","tags":["Creation"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/notes":{"post":{"operationId":"post_notes","summary":"Create a notes project.","tags":["Creation"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/presentations":{"post":{"operationId":"post_presentations","summary":"Create a presentation project.","tags":["Creation"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/templates":{"get":{"operationId":"get_templates","summary":"List templates.","tags":["Creation"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/templates/{id}/use":{"post":{"operationId":"post_templates_id_use","summary":"Create a project from a template.","tags":["Creation"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/sheets":{"get":{"operationId":"get_sheets","summary":"List sheets.","tags":["Sheets"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"post_sheets","summary":"Create a sheet.","tags":["Sheets"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/sheets/{id}":{"get":{"operationId":"get_sheets_id","summary":"Read a sheet's rows.","tags":["Sheets"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/sheets/{id}/range":{"get":{"operationId":"get_sheets_id_range","summary":"Read a sheet range.","tags":["Sheets"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/sheets/{id}/ops":{"post":{"operationId":"post_sheets_id_ops","summary":"Apply or propose structured sheet ops.","tags":["Sheets"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SheetOpsRequest"}}}}}},"/sheets/{id}/edit":{"post":{"operationId":"post_sheets_id_edit","summary":"Edit a sheet with a natural-language instruction.","tags":["Sheets"],"x-required-scope":"ai","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SheetEditRequest"}}}}}},"/sheets/{id}/commits":{"get":{"operationId":"get_sheets_id_commits","summary":"List a sheet's commits.","tags":["Sheets"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/sheets/{id}/commits/{commitId}":{"get":{"operationId":"get_sheets_id_commits_commitId","summary":"Get a commit diff.","tags":["Sheets"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"commitId","in":"path","required":true,"schema":{"type":"string"},"description":"The `commitId` path parameter."}]}},"/sheets/{id}/commits/{commitId}/resolve":{"post":{"operationId":"post_sheets_id_commits_commitId_resolve","summary":"Merge or reject a proposed commit.","tags":["Sheets"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"commitId","in":"path","required":true,"schema":{"type":"string"},"description":"The `commitId` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/sheets/{id}/rollback":{"post":{"operationId":"post_sheets_id_rollback","summary":"Roll a sheet back to a commit.","tags":["Sheets"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/boards":{"get":{"operationId":"get_boards","summary":"List boards.","tags":["Boards"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"post_boards","summary":"Create a board.","tags":["Boards"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/boards/{id}":{"get":{"operationId":"get_boards_id","summary":"Get a board.","tags":["Boards"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"patch":{"operationId":"patch_boards_id","summary":"Update a board.","tags":["Boards"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"delete":{"operationId":"delete_boards_id","summary":"Delete a board.","tags":["Boards"],"x-required-scope":"write","responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/boards/{id}/duplicate":{"post":{"operationId":"post_boards_id_duplicate","summary":"Duplicate a board.","tags":["Boards"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/boards/{id}/cards":{"get":{"operationId":"get_boards_id_cards","summary":"List a board's cards.","tags":["Boards"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"post":{"operationId":"post_boards_id_cards","summary":"Create a card.","tags":["Boards"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/boards/{id}/cards/{cardId}":{"patch":{"operationId":"patch_boards_id_cards_cardId","summary":"Update a card.","tags":["Boards"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"cardId","in":"path","required":true,"schema":{"type":"string"},"description":"The `cardId` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"delete":{"operationId":"delete_boards_id_cards_cardId","summary":"Delete a card.","tags":["Boards"],"x-required-scope":"write","responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"cardId","in":"path","required":true,"schema":{"type":"string"},"description":"The `cardId` path parameter."}]}},"/chat":{"post":{"operationId":"post_chat","summary":"Run a Theo chat turn (UI-message SSE stream by default; `stream: false` for the assembled message + artifacts).","tags":["Chat"],"x-required-scope":"ai","responses":{"200":{"description":"Default (`stream: true`): a Server-Sent Events stream in the AI SDK UI-message protocol (`Content-Type: text/event-stream`; protocol marker header `x-vercel-ai-ui-message-stream: v1`). Each event is `data: <json>` with a `type` discriminator (`start`, `start-step`, `text-start`, `text-delta`, `text-end`, `reasoning-*`, `tool-input-start`, `tool-input-delta`, `tool-input-available`, `tool-output-available`, `finish-step`, `finish`, `error`), terminated by `data: [DONE]`. Tool artifacts arrive as the `output` of `tool-output-available` events. With `stream: false`: the assembled JSON message + artifacts.","content":{"text/event-stream":{"schema":{"type":"string","description":"AI SDK UI-message SSE chunks (`data: <json>` per event, `data: [DONE]` terminator)."}},"application/json":{"schema":{"$ref":"#/components/schemas/ChatJsonResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}}}},"/chat/completions":{"post":{"operationId":"post_chat_completions","summary":"OpenAI-compatible chat completion over a Theo Agent (`model: \"agent:<agentId>\"`; the agent runs inline and replies, as JSON or as a single-chunk SSE stream when `stream: true`).","tags":["Agents"],"x-required-scope":"ai","responses":{"200":{"description":"Default (`stream` false or omitted): the assembled `chat.completion` JSON. With `stream: true`: a Server-Sent Events stream (`Content-Type: text/event-stream`) that sends SSE comments as keepalives while the agent works, then ONE `chat.completion.chunk` event carrying the whole assistant message (`delta.role`, `delta.content`, `finish_reason: stop`, plus the `opencharts` extension), a usage-only chunk, and `data: [DONE]`. No token-level streaming.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCompletionResponse"}},"text/event-stream":{"schema":{"type":"string","description":"OpenAI `chat.completion.chunk` SSE events (`data: <json>` per event, `data: [DONE]` terminator)."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCompletionRequest"}}}}}},"/conversations":{"get":{"operationId":"get_conversations","summary":"List conversations.","tags":["Conversations"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"post_conversations","summary":"Create a conversation.","tags":["Conversations"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCreate"}}}}}},"/conversations/{id}":{"get":{"operationId":"get_conversations_id","summary":"Get a conversation.","tags":["Conversations"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"patch":{"operationId":"patch_conversations_id","summary":"Update a conversation's title or mode.","tags":["Conversations"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdate"}}}}},"delete":{"operationId":"delete_conversations_id","summary":"Delete a conversation and its messages.","tags":["Conversations"],"x-required-scope":"write","responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/conversations/{id}/messages":{"get":{"operationId":"get_conversations_id_messages","summary":"List a conversation's messages (oldest first).","tags":["Conversations"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/extract-flowchart":{"post":{"operationId":"post_extract_flowchart","summary":"Extract a flowchart project from a document (PDF, PPTX, or image).","tags":["Media"],"x-required-scope":"ai","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractFlowchartRequest"}}}}}},"/images":{"post":{"operationId":"post_images","summary":"Generate an image synchronously.","tags":["Media"],"x-required-scope":"ai","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"}}}}}},"/videos":{"post":{"operationId":"post_videos","summary":"Start a video generation job (pick a tier: Fast, Max, Cinema, or Cinema Ultra).","tags":["Media"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted — an async job was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"}}}}}},"/songs":{"post":{"operationId":"post_songs","summary":"Start a song generation job.","tags":["Media"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted — an async job was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongRequest"}}}}}},"/code-builds":{"post":{"operationId":"post_code_builds","summary":"Start a Code Canvas build job.","tags":["Media"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted — an async job was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeBuildRequest"}}}}}},"/jobs/{id}":{"get":{"operationId":"get_jobs_id","summary":"Poll any async job by its type-prefixed id.","tags":["Jobs"],"x-required-scope":"read | ai","responses":{"200":{"description":"The job's current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/agents/{id}/run":{"post":{"operationId":"post_agents_id_run","summary":"Dispatch a Theo Agent.","tags":["Agents"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted — an async job was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"/agents/{id}/messages":{"post":{"operationId":"post_agents_id_messages","summary":"Send a message to a goal-driven agent on a conversation thread (returns the run id to poll for the reply).","tags":["Agents"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted: the work continues in the background.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMessageAccepted"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMessageRequest"}}}}}},"/agents/{id}/runs":{"get":{"operationId":"get_agents_id_runs","summary":"List an agent's runs.","tags":["Agents"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/agents/{id}/runs/{runId}":{"get":{"operationId":"get_agents_id_runs_runId","summary":"Get an agent run's status.","tags":["Agents"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"description":"The `runId` path parameter."}]}},"/agents/{id}/runs/{runId}/result":{"get":{"operationId":"get_agents_id_runs_runId_result","summary":"Get an agent run's result: the reply, artifacts, pending approval, credits.","tags":["Agents"],"x-required-scope":"read | ai","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"description":"The `runId` path parameter."}]}},"/agents/{id}/runs/{runId}/approve":{"post":{"operationId":"post_agents_id_runs_runId_approve","summary":"Approve or reject the action a paused agent run is waiting on (owner only).","tags":["Agents"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted: the work continues in the background.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunApproveAccepted"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."},{"name":"runId","in":"path","required":true,"schema":{"type":"string"},"description":"The `runId` path parameter."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunApproveRequest"}}}}}},"/agents/{id}/usage":{"get":{"operationId":"get_agents_id_usage","summary":"Get an agent's run + credit usage over a window (`?days=7`, 1 to 90).","tags":["Agents"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/research":{"post":{"operationId":"post_research","summary":"Start a deep-research job (returns a res_-prefixed job id; poll it at GET /jobs/{id}).","tags":["Research"],"x-required-scope":"ai","responses":{"202":{"description":"Accepted — an async job was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequest"}}}}}},"/research/{jobId}":{"get":{"operationId":"get_research_jobId","summary":"Poll a deep-research job (legacy alias of GET /jobs/{id}; accepts raw or res_-prefixed ids).","tags":["Research"],"x-required-scope":"read | ai","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchJobStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"},"description":"The `jobId` path parameter."}]}},"/webhooks":{"get":{"operationId":"get_webhooks","summary":"List webhooks.","tags":["Webhooks"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"post_webhooks","summary":"Register a webhook (secret returned once).","tags":["Webhooks"],"x-required-scope":"write","responses":{"201":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}}}},"/webhooks/{id}":{"get":{"operationId":"get_webhooks_id","summary":"Get a webhook.","tags":["Webhooks"],"x-required-scope":"read","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]},"patch":{"operationId":"patch_webhooks_id","summary":"Update a webhook.","tags":["Webhooks"],"x-required-scope":"write","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"}}}}},"delete":{"operationId":"delete_webhooks_id","summary":"Delete a webhook.","tags":["Webhooks"],"x-required-scope":"write","responses":{"204":{"description":"No content."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}},"/webhooks/{id}/deliveries":{"get":{"operationId":"get_webhooks_id_deliveries","summary":"List a webhook's recent deliveries.","tags":["Webhooks"],"x-required-scope":"read","responses":{"200":{"description":"A paginated list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The `id` path parameter."}]}}}}