Conversation API
Public API · Enterprise Edition
The Conversation API is part of Studio's public, versioned API (/api/conversation/v1/), authenticated with a crn_conv_ Bearer key. It is an Enterprise-Edition feature available on Pro and above.
The Conversation API allows external applications to interact with the Studio AI agent programmatically. It provides the same content management capabilities as the chat UI but through a REST API authenticated with project-scoped API keys.
Authentication
Conversation API endpoints use API key authentication, not session cookies:
Authorization: Bearer crn_conv_your-conversation-api-keySend Message
Send a message to the AI agent and receive a response.
POST /api/conversation/v1/:projectId/messageRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | User message text (max 10,000 characters) |
conversationId | string | No | Existing conversation ID for multi-turn |
context | object | No | UI context hints; the operation locale is derived from context.activeLocale (there is no top-level locale field) |
The agent can use the tools the key's role allows (a subset of the Chat API tools: content, model, branch merge/reject, media, and form-submission tools; no comment moderation, status, glossary, or request-changes tools), narrowed further by allowedTools.
The key must belong to the :projectId in the path (403 otherwise). The agent runs with the key's role, allowed models, allowed locales and allowed tools, on the key's configured model.
Response
A single JSON response (not a stream). The agent executes tools, performs content operations, and returns the final result:
{
"conversationId": "uuid",
"message": "Done! I created the blog post as a draft.",
"toolResults": [ ... ],
"usage": {
"inputTokens": 1234,
"outputTokens": 567,
"cacheCreationInputTokens": 0,
"cacheReadInputTokens": 0
}
}toolResults is omitted when the agent called no tools.
Errors
| Status | Condition |
|---|---|
400 | Empty or over-long message; github.installation_missing (GitHub App not installed for the workspace); github.repo_required (project has no connected repository) |
401 | Missing or invalid key (conversation.key_invalid) |
403 | Key belongs to another project, or the workspace plan does not include the Conversation API (conversation.upgrade) |
429 | chat.rate_limited (the key's per-minute limit), or conversation.monthly_limit (the key's or the workspace's monthly credits are used up) |
503 | conversation.usage_unavailable: usage could not be checked, so the message was not sent |
Example
curl -X POST https://studio.example.com/api/conversation/v1/{projectId}/message \
-H "Content-Type: application/json" \
-H "Authorization: Bearer crn_conv_your-api-key" \
-d '{
"message": "Create a blog post titled Getting Started with content about onboarding",
"context": { "activeLocale": "en" }
}'Conversation History
Get the message history for a conversation.
GET /api/conversation/v1/:projectId/historyQuery Parameters
| Parameter | Type | Description |
|---|---|---|
conversationId | string | Conversation ID (required; 400 if missing) |
limit | number | Max messages to return (default 50, max 100) |
The response is { "conversationId": "...", "messages": [ ... ] }. Each message has id, role, content, createdAt, and when present toolCalls, model, and usage (inputTokens, outputTokens). Only conversations created by the calling key can be read (404 otherwise).
Example
curl https://studio.example.com/api/conversation/v1/{projectId}/history?conversationId=uuid \
-H "Authorization: Bearer crn_conv_your-api-key"API Key Management
Conversation API keys are managed through the project settings. These are internal app routes (session cookie, like the Chat API), not Bearer-key routes. All four require workspace owner or admin role.
List Keys
GET /api/workspaces/:workspaceId/projects/:projectId/conversation-keysReturns the project's keys (the secret is never returned again): id, name, keyPrefix, role, specificModels, allowedModels, allowedTools, allowedLocales, customInstructions, aiModel, rateLimitPerMinute, monthlyMessageLimit, monthlyUsage (credits used this billing period), lastUsedAt, createdAt, revokedAt.
Create Key
POST /api/workspaces/:workspaceId/projects/:projectId/conversation-keys| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Key display name |
role | 'viewer' | 'editor' | 'admin' | No | Key role (defaults to editor) — Conversation API keys use this 3-role model, not the internal agent's workspace/project roles |
specificModels | boolean | No | When true, the key may only touch the content models listed in allowedModels (default false) |
allowedModels | string[] | No | Content model IDs the key may access (used with specificModels) |
allowedTools | string[] | No | Restrict the key to a subset of the agent tools its role allows |
allowedLocales | string[] | No | Restrict to specific locales |
customInstructions | string | No | Custom system prompt instructions (truncated to 2,000 characters). Requires the Custom AI Instructions feature (Pro and above) |
aiModel | string | No | AI model the key runs on. Non-premium chat models only: claude-haiku-5-5 or claude-sonnet-5-5. Anything else falls back to the default, claude-sonnet-5-5 on create and is ignored on update |
rateLimitPerMinute | number | No | Requests per minute for this key (default 10, clamped to 1-60) |
monthlyMessageLimit | number | No | Per-key monthly credit cap (default 1000, clamped to 1 and the plan's API credits) |
The response is the created key row plus the full key value, shown once. Errors: 400 when name is empty, 403 when the plan does not include the Conversation API or the key limit is reached (conversation.key_limit), 404 if the project is not in the workspace.
Update Key
PATCH /api/workspaces/:workspaceId/projects/:projectId/conversation-keys/:keyIdAccepts any of the create fields (name, role, specificModels, allowedModels, allowedTools, allowedLocales, customInstructions, aiModel, rateLimitPerMinute, monthlyMessageLimit) with the same limits; send customInstructions: null to clear them. Errors: 400 (validation.no_fields_to_update) when nothing valid is sent, 403 (conversation.upgrade) for custom instructions on a plan without the feature, 404 (conversation.key_not_found).
Revoke Key
DELETE /api/workspaces/:workspaceId/projects/:projectId/conversation-keys/:keyIdReturns { "revoked": true }. A revoked key stops working immediately and stays listed with revokedAt set.
Plan Limits
| Plan | Conversation Keys | API Credits/Month |
|---|---|---|
| Free | 0 | 0 |
| Starter | 0 | 0 |
| Pro | 15 | 450 |
| Enterprise | Unlimited | Unlimited |
API usage is counted in credits, like the chat agent: one credit stands for $0.01 of model spend, so a heavier message uses more than one. See Billing & Plans for overage.
The Conversation API requires Pro or above (Enterprise Edition); Free and Starter workspaces cannot create conversation keys.
Custom Instructions
Each API key can include custom instructions that are appended to the agent's system prompt. This allows project admins to constrain the agent's behavior for specific integrations:
{
"name": "Blog Integration Key",
"customInstructions": "Only create content in the blog-post model. Always set status to draft. Do not delete any content.",
"allowedModels": ["blog-post"],
"allowedLocales": ["en", "tr"]
}Enterprise Feature
The Conversation API routes through the enterprise bridge. If ee/ is not loaded, these endpoints return 403.
Related Pages
- Chat API -- the SSE chat endpoint for the Studio UI
- Agent System -- how the agent processes requests
- Enterprise Edition -- API feature details