Public REST API reference
Authentication, bot endpoints, streaming chat, request fields, limits and errors in the Corthex developer API.
In this article
Before you begin
Use a test environment and the smallest necessary access. Keep workspace API keys and signing secrets on your server, outside browser code and public screenshots.
Step by step
- 1
Create a workspace key
Use a plan and role with API access, copy the key once and store it on your server.
- 2
Select the correct bot
List bots in the key’s workspace and use the UUID of the active assistant you intend to call.
- 3
Send and handle a test request
Start with a non-sensitive test message, consume the UI message stream and handle errors before deploying your integration.
Integrate bots and streaming chat with the public REST API.
The developer API is scoped to the organisation that owns the API key. All requests use HTTPS, JSON request bodies where applicable, and a Bearer token. API access requires a plan that includes it.
Authentication
Create a key under Settings → API Keys, copy it once, and send it in every request:
Authorization: Bearer ctx_your_api_keyEndpoints
GET /api/v1/bots: List bots owned by the authenticated organisation.
GET /api/v1/bots/:botId: Get a single bot. A bot outside the key’s organisation returns 404.
POST /api/v1/chat: Send messages to an active bot and receive a UI message stream. Omit conversationId to create a new one.
curl https://www.corthex.app/api/v1/bots \
-H "Authorization: Bearer ctx_your_api_key"curl https://www.corthex.app/api/v1/bots/BOT_ID \
-H "Authorization: Bearer ctx_your_api_key"curl -X POST https://www.corthex.app/api/v1/chat \
-H "Authorization: Bearer ctx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"botId": "BOT_ID",
"messages": [{ "role": "user", "content": "What is your refund policy?" }]
}'Chat request fields
| Field | Required | Meaning |
|---|---|---|
| botId | Yes | UUID of an active bot in the authenticated organisation. |
| messages | Yes | One or more user, assistant or system messages with non-empty text. |
| conversationId | No | UUID to continue an existing conversation; omitted creates a new one. |
| attachmentIds | No | Up to 10 uploaded attachment UUIDs. |
Responses, limits and errors
The chat endpoint streams a UI message response. Requests are rate limited per API key; the chat API is limited to 60 requests per minute and also reserves model-weighted usage credits. Handle 429 with backoff, never with an immediate retry loop.
Keep the conversation ID: persist the ID returned or established by your integration if you want multi-turn context. If a staff member has taken over, expect 423 and direct the user to the human support path instead of retrying the AI.
- 400 Invalid request body 401 Missing or invalid key 404 Bot absent or inactive 423 Staff owns the chat 429 Rate or credit limit 500 Server-side chat failure
Good to know
Examples contain placeholders, never real credentials. The widget does not need a private API key.
Re-use an existing conversationId only in its owning workspace. A conversation owned by staff must follow the human support path.
Check the result
Check the response, relevant delivery history and organisation scope. Use the Public REST API reference in this Help Center for the technical contract.
Questions & troubleshooting
Why is my request rejected?
Check the HTTP status, Bearer header, bot UUID, active state and available credits. Do not retry a staff-owned conversation as AI.
Rate this guide on this device. Ratings are not sent to Corthex.