Stateful Agent API

The stateful agent API is the first-class way to run persistent agentic conversations: create a session, post messages, and each message executes a real agent run — with sources, files, and full conversation continuity. It replaces the deprecated session hints on chat/completions (see Deprecations). All endpoints live under /v1/agent/*, authenticate with your sk-rav- key, and are scoped (sessions:*, messages:*, runs:* — granted by default on all keys).

Model

Resource	What it is
Session	The durable agentic container. Conversation state persists across runs.
Message	Your input (and the agent’s replies) in the session history.
Run	One agentic execution. Posting a message queues exactly one run over it.

Every run reports credits and usage from the billing ledger receipt — the number you see is the number that was charged, never an estimate.

Lifecycle

# 1. Create a session
curl -X POST https://api.rav.chat/v1/agent/sessions \
  -H "Authorization: Bearer $RAVCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "ravchat"}'
# → {"id": "SESSION_ID", "object": "agent.session", ...}

# 2. Post a message — this queues and starts a run
curl -X POST https://api.rav.chat/v1/agent/sessions/$SESSION_ID/messages \
  -H "Authorization: Bearer $RAVCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "What does the candle-flame mashal teach about bittul?"}'
# → {"message": {...}, "run": {"id": "RUN_ID", "status": "queued", ...}}

# 3. Poll the run to a terminal state
curl https://api.rav.chat/v1/agent/runs/$RUN_ID \
  -H "Authorization: Bearer $RAVCHAT_API_KEY"
# → status: queued | in_progress | completed | failed | cancelled
#   on completed: output, credits (ledger-true), usage

# 4. Or stream lifecycle events (SSE)
curl -N https://api.rav.chat/v1/agent/runs/$RUN_ID/events \
  -H "Authorization: Bearer $RAVCHAT_API_KEY"
# events: run.started → message.completed → run.completed|run.failed|run.cancelled
# A stream opened on a finished run replays its terminal events and closes.

# 5. Continue the conversation — same session, full continuity
curl -X POST https://api.rav.chat/v1/agent/sessions/$SESSION_ID/messages \
  -H "Authorization: Bearer $RAVCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "Which sources did you base that on?"}'

Endpoints

Method & path	Purpose
`POST /v1/agent/sessions`	Create a session (`project_id` optional — your key’s default project is used and created on demand).
`GET /v1/agent/sessions`	List your agent sessions.
`GET /v1/agent/sessions/{id}`	Fetch one session.
`POST /v1/agent/sessions/{id}/messages`	Post a user message → returns `{message, run}`.
`GET /v1/agent/sessions/{id}/messages`	Full history, oldest first.
`POST /v1/agent/sessions/{id}/runs`	Advanced: explicit input array → the messages are created and linked.
`GET /v1/agent/sessions/{id}/runs`	Runs for a session, newest first.
`GET /v1/agent/runs/{id}`	Run status, output, `credits`, `usage`, error.
`GET /v1/agent/runs/{id}/events`	SSE lifecycle stream (terminal replay supported).
`POST /v1/agent/runs/{id}/cancel`	Stop waiting on a run.

Semantics worth knowing

One active run per session. Posting while a run is queued or in_progress returns 409 (enforced at the database level). Wait for the terminal state or cancel first.
Cancel means stop waiting. A turn already executing server-side completes and its charge stands; the run’s status becomes cancelled and is never overwritten.
Runs are billed as chat turns (standard multiplier). The run object’s credits comes from the charge receipt.
Restarts are safe, not silent. A server restart fails stranded runs with interrupted by server restart — resubmit the message; you will never see a run stuck in queued forever.
Powered accounts (own Claude token) get 403 powered_token_required on execution until the account’s Claude connection is set up in the app; their runs record zero-credit receipts.

chat/completions and the stateless split

POST /v1/chat/completions is now the stateless fast surface — fast mode is the default and needs no selector. The legacy agentic behavior over chat/completions (mode: "standard" or metadata.ravchat.session_id hints) is deprecated: responses carry Deprecation: true and Sunset: Fri, 14 Aug 2026 headers until the sunset date, after which those requests return invalid_request pointing here. Migrate stateful workloads to /v1/agent/* — the model above is strictly more capable.

Get started

Core concepts

Model

Lifecycle

Endpoints

Semantics worth knowing

chat/completions and the stateless split

​Model

​Lifecycle

​Endpoints

​Semantics worth knowing

​chat/completions and the stateless split

Model

Lifecycle

Endpoints

Semantics worth knowing

chat/completions and the stateless split