Sessions API

Manage conversation sessions with automatic context handling, message history, and token tracking.

Sessions automatically maintain conversation context, so you don't need to send the full message history with each request.

Sessions use JWT auth

Session endpoints are authenticated with a user JWT (Authorization: Bearer YOUR_JWT), not a tenant API key.

Create Session

POST /sessions

Creates an empty conversation session. The model and provider are chosen per message, not at creation time.

Request Body

Parameter	Type	Required	Description
`session_name`	string	No	Human-readable label for the session
`user_id`	string	No	Your end-user identifier for attribution

Create Session

curl -X POST https://api.cid222.ai/sessions \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "session_name": "Support chat",
    "user_id": "user-123"
  }'

Response

{
  "id": "6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e",
  "session_name": "Support chat",
  "tenant_id": "b2c3d4e5-...",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "token_usage": {
    "total_tokens": 0,
    "total_cost": 0
  }
}

Send Message

POST /sessions/:id/messages

Send a message in an existing session. Returns a streaming response (SSE).

Request Body

Parameter	Type	Required	Description
`content`	string	Yes	User message text
`model`	string	Yes	Model ID for this turn (e.g. `gpt-4o`)
`provider`	string	No	`openai`, `azure_openai`, `anthropic`, `google`
`temperature`, `max_tokens`, `top_p`	number	No	Sampling controls
`imageBase64`	string	No	Base64 image; redacted by the pipeline before the model

Send Message

curl -N -X POST https://api.cid222.ai/sessions/6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e/messages \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I need help with my order #12345",
    "model": "gpt-4o"
  }'

Streamed like /chat/completions

The message response is a Server-Sent Events stream with the same event types as /chat/completions (content_block_delta, filter warnings, context_usage, message_stop).

Get Session

GET /sessions/:id

Retrieve session details including full message history.

Response

{
  "id": "6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e",
  "session_name": "Support chat",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:35:00Z",
  "context": [
    { "role": "user", "content": "I need help with my order #12345" },
    { "role": "assistant", "content": "I'd be happy to help with order #12345..." }
  ],
  "token_usage": {
    "total_tokens": 235,
    "total_cost": 0.0021
  }
}

List Sessions

GET /sessions

Returns the sessions belonging to the authenticated tenant, most recent first.

Delete Session

DELETE /sessions/:id

Permanently deletes a session and all associated messages.

curl -X DELETE https://api.cid222.ai/sessions/6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e \
  -H "Authorization: Bearer YOUR_JWT"

Context Management

CID222 automatically manages conversation context:

Full History — Complete message history is stored and available via the session endpoint
AI Context — A summarized context is sent to the LLM to stay within token limits
Token Tracking — Cumulative token usage is tracked per session

When a session's context exceeds the model's token limit, CID222 automatically summarizes older messages to preserve the most relevant context while staying within limits.