Resources · Chat API

Chat API Documentation

Enterprise-grade reference for /chat/completions including request schema, streaming events, runtime behavior, and error semantics.

Back to Docs Jump to Endpoints

Endpoints

GET /api/v1/chat/health

POST /api/v1/chat/completions

Required Headers

Authorization: Bearer [token] or API key authContent-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: required only when scope is workspace

Request Body

json

{
  "message": "Summarize the last meeting in bullet points",
  "session_id": "sess_123",
  "stream": true,
  "attachments": [],
  "metadata": {
    "locale": "en",
    "channel": "web"
  }
}

Response Body

json

{
  "success": true,
  "session_id": "sess_123",
  "content": "• Discussed roadmap\n• Confirmed release scope\n• Assigned owners",
  "provider": "pulse",
  "usage": {
    "input_tokens": 324,
    "output_tokens": 118
  },
  "metadata": {
    "latency_ms": 612
  }
}

Streaming Events

response.started — chat execution started
response.delta — incremental text tokens
response.tool_call — tool invocation event (if any)
response.usage — usage/tokens update
response.completed — final assembled response

Runtime Behaviors

Backpressure control rejects overload with 503.
Distributed locking prevents duplicate in-flight processing.
Dedup cache serves repeated non-stream requests.
Session persistence stores user + assistant turns.
Validation guards request body, attachments, and access context.

Error Models

400

Invalid request payload or missing required fields.

401

Missing or invalid authentication.

403

Scope/permission restriction.

409

Lock conflict: request already processing.

422

Validation failure in headers/body/context.

429

Rate limit exceeded.

503

System overload or upstream unavailability.

Examples

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Write a short product update",
    "session_id":"sess_123",
    "stream":false
  }'