DocsChat
Начать

REST API integration

DocsChat exposes REST API v1 (sessions + widget-compatible chat) and API v2 (streaming chat, conversations, agents). Use v2 for new integrations.

Requirements

  • Standard+ workspace plan (apiAccess feature)
  • API key from Admin → API (/admin/api-keys)

Authentication

Authorization: Bearer YOUR_API_KEY

Keys are workspace-scoped. Invalid or revoked keys return 401.

Optional identity verification (Enterprise / white-label):

X-DocsChat-Identity: <base64url JSON payload>
X-DocsChat-Signature: <hmac-sha256 hex of payload using workspace webhookSecret>

API v2 (recommended)

OpenAPI spec: openapi/v2.yaml in the repo root.

Streaming chat

POST /api/v2/chat
Authorization: Bearer sk_live_xxxx
Content-Type: application/json

{
  "agent": "support",
  "message": "How do I reset my password?",
  "stream": true
}

With "stream": true, the response is Server-Sent Events:

data: {"type":"token","content":"You "}
data: {"type":"done","sessionId":"...","message":"...","citations":[...]}

Non-streaming omits stream and returns JSON:

{
  "sessionId": "clxx...",
  "message": "...",
  "citations": [{ "documentName": "..." }],
  "isFallback": false
}

List conversations

GET /api/v2/conversations?limit=20&agent=support
Authorization: Bearer sk_live_xxxx

Response includes cursor pagination:

{
  "data": [{ "id": "...", "agent": "support", "channel": "CHAT", "lastMessage": "..." }],
  "meta": { "nextCursor": "...", "hasMore": true }
}

List agents

GET /api/v2/agents
Authorization: Bearer sk_live_xxxx

Error format (v2)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "message is required"
  }
}

API v1 (stable)

1. Create a session

POST /api/v1/sessions
Authorization: Bearer sk_live_xxxx
Content-Type: application/json

{
  "slug": "support"
}
FieldRequiredDescription
slugNoAgent slug; defaults to first agent in workspace

Response 200

{
  "sessionId": "clxx..."
}

Errors

StatusMeaning
401Missing or invalid API key
403Plan lacks API access
404Agent slug not found

2. Send a message (v1 session)

POST /api/chat/{sessionId}/message
Content-Type: application/json

{
  "message": "How do I reset my password?"
}

Uses the published agent config, multi-source RAG, guardrails, and LLM tool calling on Standard+.

Response 200

{
  "messages": [...],
  "offerHandoff": false
}

CLI

export DOCSCHAT_API_KEY=sk_live_xxxx
export DOCSCHAT_API_URL=http://localhost:3000/api/v2

node packages/cli/bin/docschat.mjs agents list
node packages/cli/bin/docschat.mjs conversations list --agent support

Related