Skip to content

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 admin keys 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 ​

  1. Open the project settings (gear icon in the sidebar)
  2. Go to the API keys tab and find Conversation API keys
  3. Click Create key
  4. Enter a Key Name and pick a Role (viewer, editor, or admin; it determines what the agent can do)
  5. 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):

SettingDescription
specificModelsRestrict the key to the models in allowedModels
allowedModelsList of model IDs the key can access
allowedToolsWhich agent tools the key can invoke
allowedLocalesWhich locales the key can read/write
customInstructionsAdditional system prompt text for this key (length-capped; needs a plan with custom AI instructions)
aiModelWhich 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
rateLimitPerMinutePer-key request rate limit
monthlyMessageLimitPer-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:

MethodPathPurpose
GET/api/workspaces/{workspaceId}/projects/{projectId}/conversation-keysList keys, with each key's usage this month
POST/api/workspaces/{workspaceId}/projects/{projectId}/conversation-keysCreate 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/json

Request Body ​

json
{
  "message": "Create a blog post titled 'API-Created Post' with status published",
  "conversationId": null,
  "context": { "activeLocale": "en" }
}
FieldRequiredDescription
messageYesThe user message to send to the agent (length-capped)
conversationIdNoContinue an existing conversation (null for new)
contextNoUI 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:

json
{
  "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
  }
}
FieldDescription
conversationIdThe conversation ID — pass it back as conversationId on the next request to continue the thread
messageThe agent's final response text
toolResultsResults of any tools the agent invoked this turn (omitted when no tools ran)
usageToken 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.

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

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

javascript
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:

bash
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}/message

Bulk Content Operations ​

Use the API to perform bulk operations that would be tedious in the UI:

javascript
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:

RoleCan ReadCan WriteCan DeleteCan Manage Models
ViewerYesNoNoNo
EditorYesYesYesNo
AdminYesYesYesYes

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 ​

FeatureFreeStarterProEnterprise
Conversation keys0015Unlimited
API credits/month00450Unlimited
Custom AI instructionsNoNoYesYes

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

Released under the AGPL-3.0 License. Privacy