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.

Create Session

POST /sessions

Request Body

Parameter	Type	Required	Description
`provider`	string	Yes	LLM provider (openai, anthropic, google)
`model`	string	Yes	Model ID to use
`system_prompt`	string	No	Initial system instruction
`metadata`	object	No	Custom metadata (user_id, etc.)

Create Session

curl -X POST https://api.cid222.ai/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-4",
    "system_prompt": "You are a helpful customer support agent.",
    "metadata": {
      "user_id": "user-123",
      "department": "support"
    }
  }'

Response

{
  "id": "sess_abc123",
  "provider": "openai",
  "model": "gpt-4",
  "created_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "user_id": "user-123",
    "department": "support"
  },
  "token_usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Send Message

POST /sessions/:id/messages

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

Send Message

curl -X POST https://api.cid222.ai/sessions/sess_abc123/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I need help with my order #12345"
  }'

Get Session

GET /sessions/:id

Retrieve session details including full message history.

Response

{
  "id": "sess_abc123",
  "provider": "openai",
  "model": "gpt-4",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z",
  "metadata": {
    "user_id": "user-123"
  },
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful customer support agent."
    },
    {
      "role": "user",
      "content": "I need help with my order #12345",
      "timestamp": "2024-01-15T10:31:00Z"
    },
    {
      "role": "assistant",
      "content": "I'd be happy to help with order #12345...",
      "timestamp": "2024-01-15T10:31:05Z"
    }
  ],
  "token_usage": {
    "prompt_tokens": 150,
    "completion_tokens": 85,
    "total_tokens": 235
  }
}

List Sessions

GET /sessions

Parameter	Type	Description
`limit`	number	Max results (default: 20, max: 100)
`offset`	number	Pagination offset

Delete Session

DELETE /sessions/:id

Permanently deletes a session and all associated messages.

curl -X DELETE https://api.cid222.ai/sessions/sess_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

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.