API v2

API v2 is a structured REST API for managing agents and building custom chat experiences. It adds agent management, streaming chat, conversation history, message feedback, contacts, leads, sources, settings, and training endpoints.

API access requires a Hobby plan or above with active billing.

Base URL

https://your-domain.com/api/v2

Authentication

Except for the health check, send your workspace API key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Create and revoke API keys from Settings > API Keys.

Response Format

Most successful responses return either a resource object or a data envelope:

{
  "data": []
}

List endpoints include cursor pagination:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Errors use a structured error object:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Every v2 response includes an x-request-id header. Include it when contacting support about an API request.

Conversation Scope

Read-only conversation endpoints default to source=api_v2. Set source=widget to return widget and Playground conversations; Playground rows are stored with the widget source. Set source=all to return API v2, widget, and Playground conversations. Results always remain limited to the authenticated account's agent. An invalid source value or more than one source query parameter returns 400 VALIDATION_INVALID_BODY. Chat continuation, retry, feedback, message listing, and per-user reads remain scoped to API v2 conversations.

Health

GET /api/v2/health

The health check does not require authentication.

Success: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp is the current Unix timestamp in seconds.

Chat

POST /api/v2/agents/{agentId}/chat

Request:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Streaming responses use Server-Sent Events. The stream includes message-start, text-start, text-delta, text-end, message-metadata, finish, and [DONE] events. A stream or completion-hook failure emits an error event with error.code set to CHAT_STREAMING_ERROR; this SSE-only protocol code is separate from the structured REST error catalog. message-metadata contains the assistant message ID when persistence succeeds, plus the conversation ID, user ID, finish reason, and usage. Its messageId is null when no assistant message was persisted. When the reply pauses on a client-side action, the stream also emits a tool-call event with { "id", "name", "arguments" }; submit the outcome to the tool-result endpoint to resume the conversation — the response to that request streams the continuation.

Non-streaming responses return:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

The non-streaming data.id and metadata.userMessageId values are numeric message IDs serialized as strings, or null when the corresponding message was not persisted. metadata.userId is the supplied/stored user ID or null. pendingToolCall is null unless the reply paused on a client-side tool call, in which case it holds { "id", "name", "arguments" } for the tool-result endpoint.

Endpoint Summary

Feedback

Use feedback to mark API v2 assistant messages as positive, negative, or null. See Conversations, messages, and feedback for the request schema, response, and error behavior.

Pagination

Treat cursors as opaque tokens returned by the API. Replay the pagination.cursor value unchanged on the next request; do not construct or decode it.

Contacts also accept search. Leads accept inclusive createdAfter and createdBefore ISO 8601 datetime filters. Sources accept sourceType with web_crawl, file_upload, text_snippet, or qna_entry.

Cursor formats are an internal implementation detail. Clients must treat every cursor as opaque and replay it unchanged without constructing or decoding it.

Common Errors

See the complete API v2 error catalog for all 27 declared codes, HTTP statuses, triggers, and reserved codes.

Reference

• Error catalog
• Agents and settings
• Conversations, messages, retries, and feedback
• Sources and training
• Contacts and leads
• Instagram channel

Next Steps

• Create an API key
• Set up identity verification
• Review API v2 errors
• Manage agents and settings
• Work with conversations
• Manage sources and training
• Manage contacts and leads
• Manage the Instagram channel