Conversation API
The Conversation API lets you interact with Contentrain Studio's AI agent programmatically. Instead of using the web interface, you can send messages and receive structured responses through a REST API — enabling chatbots, CI/CD pipelines, and custom integrations.
What the Conversation API Is
The Conversation API exposes the same AI agent that powers the Studio chat panel, but through a programmatic interface:
- A subset of the chat tool set: reading and searching content and media, creating, updating and deleting content, saving models, copying locales, uploading media, and reviewing form submissions. Tools that need a signed-in person are not available to keys: deleting models, changing entry status, updating or deleting media, the vocabulary and locale tools, relation expansion, branch health, requesting changes, and the comment tools. Merging and rejecting branches and approving submissions are available to
adminkeys only - Same permission model (scoped by API key role)
- Same branch workflow (changes go to review branches)
- Same conversation context (maintains history within a session)
API Key Management
Conversation API access requires an API key, managed in the project settings.
Creating an API Key
- Open the project settings (gear icon in the sidebar)
- Go to the API keys tab and find Conversation API keys
- Click Create key
- Enter a Key Name and pick a Role (
viewer,editor, oradmin; it determines what the agent can do) - The key is generated and shown once — copy it immediately
Only workspace owners and admins can view and manage keys. Each key's row shows when it was last used and its messages this month.
The dashboard dialog sets the name and role only. The other settings are available through the key management API (see Key Management API):
| Setting | Description |
|---|---|
specificModels | Restrict the key to the models in allowedModels |
allowedModels | List of model IDs the key can access |
allowedTools | Which agent tools the key can invoke |
allowedLocales | Which locales the key can read/write |
customInstructions | Additional system prompt text for this key (length-capped; needs a plan with custom AI instructions) |
aiModel | Which Claude model to use — Haiku 5.5 or Sonnet 5.5 (defaults to Sonnet 5.5). Opus 5.5 is not offered on API keys; a key that names a retired model ID runs on the current model of the same family |
rateLimitPerMinute | Per-key request rate limit |
monthlyMessageLimit | Per-key monthly message cap, never above the plan's API credits |
Without a role, a key created through the API is an editor key.
Key Format
Conversation API keys follow the format:
crn_conv_{random-base62-string}WARNING
API keys are shown only once at creation time. Studio stores only the SHA-256 hash. If you lose the key, create a new one and delete the old one.
Editing and Revoking Keys
In the dashboard, the Revoke action on a key's row (with a confirmation) immediately revokes access. To change a key's name, role or restrictions, use the key management API.
Key Management API
These routes use your signed-in Studio session (not a Conversation API key) and need the workspace owner or admin role and a plan that includes the Conversation API:
| Method | Path | Purpose |
|---|---|---|
GET | /api/workspaces/{workspaceId}/projects/{projectId}/conversation-keys | List keys, with each key's usage this month |
POST | /api/workspaces/{workspaceId}/projects/{projectId}/conversation-keys | Create a key. Body: name (required) plus any setting from the table above. The response includes the full key once |
PATCH | /api/workspaces/{workspaceId}/projects/{projectId}/conversation-keys/{keyId} | Update any of the same fields; at least one is required |
DELETE | /api/workspaces/{workspaceId}/projects/{projectId}/conversation-keys/{keyId} | Revoke the key |
Creating a key returns 403 when the plan does not include the Conversation API, when the plan's key limit is reached, or when customInstructions is sent on a plan without custom AI instructions.
Sending Messages
Endpoint
POST /api/conversation/v1/{projectId}/message
Authorization: Bearer crn_conv_...
Content-Type: application/jsonRequest Body
{
"message": "Create a blog post titled 'API-Created Post' with status published",
"conversationId": null,
"context": { "activeLocale": "en" }
}| Field | Required | Description |
|---|---|---|
message | Yes | The user message to send to the agent (length-capped) |
conversationId | No | Continue an existing conversation (null for new) |
context | No | UI context hints — activeLocale, activeModelId, activeEntryId, activeBranch — that ground the agent's operations |
There is no per-request model override. The Claude model is fixed per key: it is the AI model chosen when the key was created (see Creating an API Key).
Response
The endpoint returns a single JSON object once the agent's turn completes — it does not stream:
{
"conversationId": "conv-uuid",
"message": "Done! The blog post has been created on branch cr/content/blog-posts/en/...",
"toolResults": [
{
"id": "tool-1",
"name": "save_content",
"result": { "branch": "cr/content/blog-posts/en/..." }
}
],
"usage": {
"inputTokens": 1234,
"outputTokens": 567,
"cacheCreationInputTokens": 0,
"cacheReadInputTokens": 0
}
}| Field | Description |
|---|---|
conversationId | The conversation ID — pass it back as conversationId on the next request to continue the thread |
message | The agent's final response text |
toolResults | Results of any tools the agent invoked this turn (omitted when no tools ran) |
usage | Token usage for the turn — input, output, and prompt-cache tokens |
Conversation History
Fetching a Conversation
GET /api/conversation/v1/{projectId}/history?conversationId=conv-uuid
Authorization: Bearer crn_conv_...The conversationId query parameter is required — the endpoint returns the messages for that one conversation, not a list of conversations. An optional limit (default 50, max 100) caps how many messages come back.
{
"conversationId": "conv-uuid",
"messages": [
{
"id": "msg-uuid-1",
"role": "user",
"content": "Create a blog post titled 'API-Created Post'",
"createdAt": "2026-04-02T10:00:00Z"
},
{
"id": "msg-uuid-2",
"role": "assistant",
"content": "Done! The blog post has been created...",
"model": "claude-sonnet-5-5",
"usage": { "inputTokens": 1234, "outputTokens": 567 },
"createdAt": "2026-04-02T10:00:05Z"
}
]
}An assistant message that ran tools also carries a toolCalls field, and usage appears only when token counts were recorded.
Continuing a Conversation
Pass the conversationId in subsequent requests to maintain context:
{
"message": "Now update the title to 'Updated Post'",
"conversationId": "conv-uuid"
}The agent will remember the previous context and can reference earlier operations.
Custom Instructions
Each API key can have custom instructions — additional text injected into the agent's system prompt. Use this to:
- Set content guidelines ("Always use formal English")
- Define default behaviors ("Set status to draft unless I say published")
- Restrict scope ("Only work with the blog-posts model")
- Add domain knowledge ("Our brand voice is friendly and professional")
Custom instructions are set with the customInstructions field when you create or update the key through the key management API.
Use Cases
Chatbot on Your Website
Embed a chat widget on your website that uses the Conversation API to let visitors ask questions about your content or submit feedback:
const response = await fetch('/api/conversation/v1/{projectId}/message', {
method: 'POST',
headers: {
'Authorization': 'Bearer crn_conv_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: userInput,
conversationId: sessionId,
}),
})
const { conversationId, message } = await response.json()
// Show `message` to the visitor; reuse `conversationId` on the next turn.CI/CD Content Updates
Automate content updates from your deployment pipeline:
curl -X POST \
-H "Authorization: Bearer crn_conv_..." \
-H "Content-Type: application/json" \
-d '{"message": "Set the site-settings version field to 2.1.0"}' \
https://your-studio.com/api/conversation/v1/{projectId}/messageBulk Content Operations
Use the API to perform bulk operations that would be tedious in the UI:
const operations = [
'Set all blog posts with status draft to published',
'Add the tag "featured" to entries with rating above 4',
'Copy all English FAQ entries to Spanish',
]
for (const op of operations) {
await sendMessage(op, conversationId)
}Content Migration
Migrate content from external sources by instructing the agent:
"Create a team member entry with name 'Jane Smith', role 'CTO',
bio 'Leading technology strategy...', and email 'jane@example.com'"Role-Based Access
Each Conversation API key has exactly one of three roles, and that role determines what the agent can do:
| Role | Can Read | Can Write | Can Delete | Can Manage Models |
|---|---|---|---|---|
| Viewer | Yes | No | No | No |
| Editor | Yes | Yes | Yes | No |
| Admin | Yes | Yes | Yes | Yes |
INFO
These three roles (viewer / editor / admin) are specific to Conversation API keys. They are not the same as the workspace and project roles used by the in-app AI Chat agent (workspace owner / admin / member combined with project editor / reviewer / viewer).
Model Restrictions
With specificModels enabled, the API key can only access the models listed in allowedModels. This is useful for creating scoped keys that can only manage specific content areas.
Tool Restrictions
The allowedTools setting lets you restrict which agent tools a key can invoke. For example, a viewer key might only allow brain_query and brain_search, while an editor key allows save_content and delete_content.
Locale Restrictions
The allowedLocales setting restricts which locales the key can read from and write to.
Plan Limits
| Feature | Free | Starter | Pro | Enterprise |
|---|---|---|---|---|
| Conversation keys | 0 | 0 | 15 | Unlimited |
| API credits/month | 0 | 0 | 450 | Unlimited |
| Custom AI instructions | No | No | Yes | Yes |
INFO
The Conversation API is an Enterprise-Edition feature available on Pro and above — Starter workspaces cannot create conversation keys.
Next Steps
- AI Chat — Understand the agent's capabilities
- Content Models — Define models for API-driven content
- Webhooks — Get notified when content changes via API