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-key

Send Message

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

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

Request Body

Field	Type	Required	Description
message	string	Yes	User message text
conversationId	string	No	Existing conversation ID for multi-turn
locale	string	No	Default locale for operations

Response

The response format depends on the API key configuration. The agent executes tools, performs content operations, and returns the final result.

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",
    "locale": "en"
  }'

---

Conversation History

Get the message history for a conversation.

GET /api/conversation/v1/:projectId/history

Query Parameters

Parameter	Type	Description
conversationId	string	Conversation ID

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:

List Keys

GET /api/workspaces/:workspaceId/projects/:projectId/conversation-keys

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
allowedModels	string[]	No	Restrict to specific models
allowedLocales	string[]	No	Restrict to specific locales
customInstructions	string	No	Custom system prompt instructions

Update Key

PATCH /api/workspaces/:workspaceId/projects/:projectId/conversation-keys/:keyId

Revoke Key

DELETE /api/workspaces/:workspaceId/projects/:projectId/conversation-keys/:keyId

---

Plan Limits

Plan	Conversation Keys	Messages/Month
Free	0	0
Starter	0	0
Pro	15	3,000
Enterprise	Unlimited	Unlimited

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