Sessions API

A session is a conversation thread. Create, fetch, and delete sessions — all scoped to the API key's project.

Create a session

POST/v1/sessions

Starts a new, empty session. Optionally pass a title. (A session is also created automatically the first time you call Chat without a session_id.)

bash

curl -X POST https://api.carrieros.ai/v1/sessions \
  -H "Authorization: Bearer carrier_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "OAuth research" }'

json

{
  "success": true,
  "data": {
    "session_id": "9c4f…",
    "title": "OAuth research",
    "created_at": "2026-07-27T10:00:00.000Z",
    "message_count": 0
  }
}

Get a session

GET/v1/sessions/:id

Returns a single session, only if it belongs to the authenticated project.

bash

curl https://api.carrieros.ai/v1/sessions/9c4f… -H "Authorization: Bearer carrier_sk_live_YOUR_KEY"

Delete a session

DELETE/v1/sessions/:id

Soft-deletes the session. Returns 404 if it isn't in this project.

bash

curl -X DELETE https://api.carrieros.ai/v1/sessions/9c4f… -H "Authorization: Bearer carrier_sk_live_YOUR_KEY"

A returned 404 SESSION_NOT_FOUND also covers the case where the session exists but belongs to a different project — cross-project access is never revealed.