API overview

The Chatevo REST API lets you manage assistants, knowledge bases, tools, conversations, and widget deployments programmatically.

Base URL

Environment	Base URL
Production	`https://api.chatevo.ai`

All paths below are relative to this base unless noted.

API version

Current version prefix: /api/v1

Example:

GET https://api.chatevo.ai/api/v1/assistants

Breaking changes ship under a new version prefix. Non-breaking additions (new fields, endpoints) may appear in the current version without a version bump.

Resource areas

Area	Purpose	Auth
Assistants	Create and configure assistants	API key or session
Knowledge bases	Upload and manage document collections	API key or session
Tools	Define API and MCP integrations	API key or session
Conversations	List and manage chat threads	API key or session
Messages	Send and read messages (Direct API)	API key or session
Widget config	Public widget bootstrap settings	Deployment ID + domain
Widget messages	Visitor chat (supports SSE streaming)	Deployment ID + domain
Webhooks	Register outbound event endpoints	API key or session

Request format

Header	Value	When
`Content-Type`	`application/json`	POST, PUT, PATCH bodies
`Authorization`	`Bearer <api_key>`	Server-to-server and automation
`Cookie`	Session cookie	Dashboard and browser clients

See Authentication for API keys vs session cookies.

Response format

Successful responses return JSON with resource fields. Errors use a consistent envelope:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after": 12
  }
}

HTTP status	Meaning
`200` / `201`	Success
`400`	Invalid request body or parameters
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted
`404`	Resource not found
`429`	Rate limit exceeded — see Rate limits
`500`	Server error — retry with backoff

Pagination

List endpoints accept limit (default 20, max 100) and cursor query parameters:

GET /api/v1/conversations?limit=50&cursor=eyJpZCI6ImNvbnYxMjMifQ==

Responses include data (array) and next_cursor (string or null).

Idempotency

For POST endpoints that create billable or side-effecting resources, send an idempotency key:

Idempotency-Key: 7f3c9a2e-4b1d-4e8f-9c0a-1b2c3d4e5f6a

Repeating the same key within 24 hours returns the original response without duplicating the resource.

OpenAPI

Interactive schema and try-it-out UI: OpenAPI docs at https://api.chatevo.ai/api/docs.