API reference
Every endpoint of the OpenCharts REST API, generated live from the OpenAPI 3.1 spec so it always matches production. Authenticate with Authorization: Bearer oc_…. Create keys on the Developers hub.
https://www.opencharts.com/api/v169 operationsv1.0.0Meta
1 endpoint/openapi→ 200no authFetch this OpenAPI document.
Account
2 endpoints/account→ 200read scopeGet the authenticated account (whoami).
/account/credits→ 200read scopeGet the plan + AI credit balance.
Personas
12 endpoints/personas→ 200read scopeList personas.
/personas→ 201write scopeCreate a persona.
/personas/{id}→ 200read scopeGet a persona.
Path params: {id}
/personas/{id}→ 200write scopeUpdate a persona.
Path params: {id}
/personas/{id}→ 204write scopeDelete a persona.
Path params: {id}
/personas/{id}/publish→ 200write scopePublish a persona.
Path params: {id}
/personas/{id}/deployments→ 200read scopeList a persona's deployments.
Path params: {id}
/personas/{id}/deployments→ 201write scopeCreate a persona deployment.
Path params: {id}
/personas/{id}/conversations→ 201write scopeStart a persona conversation.
Path params: {id}
/personas/{id}/conversations/{cid}/end→ 200write scopeEnd a persona conversation.
Path params: {id}, {cid}
/personas/{id}/conversations/{cid}/events→ 200read scopeList conversation events.
Path params: {id}, {cid}
/personas/faces→ 200read scopeList available persona faces.
Projects
4 endpoints/projects→ 200read scopeList projects.
/projects/{id}→ 200read scopeGet a project.
Path params: {id}
/projects/{id}→ 200write scopeUpdate a project's metadata or content.
Path params: {id}
/projects/{id}→ 204write scopeDelete a project.
Path params: {id}
Creation
6 endpoints/flowcharts→ 201write scopeCreate a flowchart project.
/whiteboards→ 201write scopeCreate a whiteboard project.
/notes→ 201write scopeCreate a notes project.
/presentations→ 201write scopeCreate a presentation project.
/templates→ 200read scopeList templates.
/templates/{id}/use→ 201write scopeCreate a project from a template.
Path params: {id}
Sheets
10 endpoints/sheets→ 200read scopeList sheets.
/sheets→ 201write scopeCreate a sheet.
/sheets/{id}→ 200read scopeRead a sheet's rows.
Path params: {id}
/sheets/{id}/range→ 200read scopeRead a sheet range.
Path params: {id}
/sheets/{id}/ops→ 200write scopeApply or propose structured sheet ops.
Path params: {id}
opsrequiredarray<object>proposebooleansummarystring/sheets/{id}/edit→ 200ai scopeEdit a sheet with a natural-language instruction.
Path params: {id}
instructionrequiredstringproposeboolean/sheets/{id}/commits→ 200read scopeList a sheet's commits.
Path params: {id}
/sheets/{id}/commits/{commitId}→ 200read scopeGet a commit diff.
Path params: {id}, {commitId}
/sheets/{id}/commits/{commitId}/resolve→ 200write scopeMerge or reject a proposed commit.
Path params: {id}, {commitId}
/sheets/{id}/rollback→ 200write scopeRoll a sheet back to a commit.
Path params: {id}
Boards
10 endpoints/boards→ 200read scopeList boards.
/boards→ 201write scopeCreate a board.
/boards/{id}→ 200read scopeGet a board.
Path params: {id}
/boards/{id}→ 200write scopeUpdate a board.
Path params: {id}
/boards/{id}→ 204write scopeDelete a board.
Path params: {id}
/boards/{id}/duplicate→ 201write scopeDuplicate a board.
Path params: {id}
/boards/{id}/cards→ 200read scopeList a board's cards.
Path params: {id}
/boards/{id}/cards→ 201write scopeCreate a card.
Path params: {id}
/boards/{id}/cards/{cardId}→ 200write scopeUpdate a card.
Path params: {id}, {cardId}
/boards/{id}/cards/{cardId}→ 204write scopeDelete a card.
Path params: {id}, {cardId}
Chat
1 endpoint/chat→ 200ai scopeRun a Theo chat turn (UI-message SSE stream by default; `stream: false` for the assembled message + artifacts).
conversationIdstringContinue an existing conversation (prior history loads server-side).
messagestringThe prompt (shorthand for a single user message).
messagesarray<object>modefast | thinkv1 launch modes.
streambooleantrue = AI SDK UI-message SSE stream; false = assembled JSON message + artifacts.
Conversations
6 endpoints/conversations→ 200read scopeList conversations.
/conversations→ 201write scopeCreate a conversation.
titlestringmodestringChat mode preference (e.g. `fast`, `think`).
/conversations/{id}→ 200read scopeGet a conversation.
Path params: {id}
/conversations/{id}→ 200write scopeUpdate a conversation's title or mode.
Path params: {id}
titlestringmodestringChat mode preference (e.g. `fast`, `think`).
/conversations/{id}→ 204write scopeDelete a conversation and its messages.
Path params: {id}
/conversations/{id}/messages→ 200read scopeList a conversation's messages (oldest first).
Path params: {id}
Media
5 endpoints/extract-flowchart→ 201ai scopeExtract a flowchart project from a document (PDF, PPTX, or image).
documentBase64requiredstringBase64-encoded document content (no `data:` prefix). Max 10MB decoded.
mimeTyperequiredapplication/pdf | application/vnd.openxmlformats-officedocument.presentationml.presentation | image/png | image/jpeg | image/webpfileNamestringOriginal file name (used as a title fallback).
/images→ 200ai scopeGenerate an image synchronously.
promptrequiredstringengineauto | theo-creative | theo-imagine | theo-photo | theo-rapid | theo-design | …aspectRatio1:1 | 16:9 | 9:16 | 4:3 | 3:4stylestringreferenceImageUrlsarray<string>includeBase64boolean/videos→ 202ai scopeStart a video generation job.
promptrequiredstringaspectRatio16:9 | 9:16modelTierfast | maxreferenceImageUrlstring/songs→ 202ai scopeStart a song generation job.
stylerequiredstringtitlestringlyricsstringautoLyricsbooleaninstrumentalbooleantierauto | premium | fast/code-builds→ 202ai scopeStart a Code Canvas build job.
promptrequiredstringnamestringframeworkhtml | react | autoplanFirstbooleanJobs
1 endpoint/jobs/{id}→ 200read | ai scopePoll any async job by its type-prefixed id.
Path params: {id}
Agents
3 endpoints/agents/{id}/run→ 202ai scopeDispatch a Theo Agent.
Path params: {id}
/agents/{id}/runs→ 200read scopeList an agent's runs.
Path params: {id}
/agents/{id}/runs/{runId}→ 200read scopeGet an agent run's status.
Path params: {id}, {runId}
Research
2 endpoints/research→ 202ai scopeStart a deep-research job (returns a res_-prefixed job id; poll it at GET /jobs/{id}).
queryrequiredstring/research/{jobId}→ 200read | ai scopePoll a deep-research job (legacy alias of GET /jobs/{id}; accepts raw or res_-prefixed ids).
Path params: {jobId}
Webhooks
6 endpoints/webhooks→ 200read scopeList webhooks.
/webhooks→ 201write scopeRegister a webhook (secret returned once).
namerequiredstringurlrequiredstringeventsrequiredarray<project.created | project.updated | project.shared | project.deleted | team.member_added | team.member_removed | …>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_*`.
/webhooks/{id}→ 200read scopeGet a webhook.
Path params: {id}
/webhooks/{id}→ 200write scopeUpdate a webhook.
Path params: {id}
namestringurlstringeventsarray<project.created | project.updated | project.shared | project.deleted | team.member_added | team.member_removed | …>isActiveboolean/webhooks/{id}→ 204write scopeDelete a webhook.
Path params: {id}
/webhooks/{id}/deliveries→ 200read scopeList a webhook's recent deliveries.
Path params: {id}
{ data, total, cursor? }; async work returns a job envelope polled at GET /jobs/{id}; errors are { error: { code, message, requestId } }. Register webhooks on the Developers hub to skip polling.