Skip to content

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:

http
Authorization: Bearer crn_conv_your-conversation-api-key

Send Message ​

Send a message to the AI agent and receive a response.

POST /api/conversation/v1/:projectId/message

Request Body ​

FieldTypeRequiredDescription
messagestringYesUser message text (max 10,000 characters)
conversationIdstringNoExisting conversation ID for multi-turn
contextobjectNoUI 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:

json
{
  "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 ​

StatusCondition
400Empty or over-long message; github.installation_missing (GitHub App not installed for the workspace); github.repo_required (project has no connected repository)
401Missing or invalid key (conversation.key_invalid)
403Key belongs to another project, or the workspace plan does not include the Conversation API (conversation.upgrade)
429chat.rate_limited (the key's per-minute limit), or conversation.monthly_limit (the key's or the workspace's monthly credits are used up)
503conversation.usage_unavailable: usage could not be checked, so the message was not sent

Example ​

bash
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/history

Query Parameters ​

ParameterTypeDescription
conversationIdstringConversation ID (required; 400 if missing)
limitnumberMax 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 ​

bash
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-keys

Returns 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
FieldTypeRequiredDescription
namestringYesKey display name
role'viewer' | 'editor' | 'admin'NoKey role (defaults to editor) — Conversation API keys use this 3-role model, not the internal agent's workspace/project roles
specificModelsbooleanNoWhen true, the key may only touch the content models listed in allowedModels (default false)
allowedModelsstring[]NoContent model IDs the key may access (used with specificModels)
allowedToolsstring[]NoRestrict the key to a subset of the agent tools its role allows
allowedLocalesstring[]NoRestrict to specific locales
customInstructionsstringNoCustom system prompt instructions (truncated to 2,000 characters). Requires the Custom AI Instructions feature (Pro and above)
aiModelstringNoAI 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
rateLimitPerMinutenumberNoRequests per minute for this key (default 10, clamped to 1-60)
monthlyMessageLimitnumberNoPer-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/:keyId

Accepts 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/:keyId

Returns { "revoked": true }. A revoked key stops working immediately and stays listed with revokedAt set.


Plan Limits ​

PlanConversation KeysAPI Credits/Month
Free00
Starter00
Pro15450
EnterpriseUnlimitedUnlimited

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:

json
{
  "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.

Released under the AGPL-3.0 License. Privacy