API Reference

REST + JWT-signed CDP WebSocket. RFC-7807 errors. OpenAPI 3.1.

The Ventus Sessions API is split into two surfaces:

Control plane (this reference) — REST under https://api.sessions.ventus.ai/v1/*. Authenticate with a workspace API key as Authorization: Bearer vs_…. The full OpenAPI 3.1 spec is hosted at /openapi.json.
Browser data plane — CDP WebSocket at the connect_url you receive from POST /v1/sessions. Any Chrome DevTools Protocol client works.

Base URL

Environment	URL
Production	`https://api.sessions.ventus.ai`
Staging	`https://api.staging.sessions.ventus.ai`
Local	`http://localhost:8080`

Authentication

All endpoints require a Bearer token:

Authorization: Bearer vs_01JC1AMQX4N3PWV9MR2BCKDH7E.<32 chars>

See Authentication for the full token model. A missing or invalid token returns 401 Unauthorized with an RFC-7807 problem document.

Idempotency

Every POST /v1/sessions MUST include an Idempotency-Key header:

Idempotency-Key: 4e5f8b7a-1c2d-3a4b-5c6d-7e8f9a0b1c2d

Dedupe window: 24 hours per workspace. See Sessions → Idempotency.

Errors

All errors are RFC-7807 problem documents:

{
  "type":   "https://api.sessions.ventus.ai/errors/insufficient-capacity",
  "title":  "Insufficient capacity",
  "status": 503,
  "detail": "No agents in region us-east1 had spare capacity at 2026-05-18T00:14:22Z. Retry after the pool drains; us-east1 is the only region available today.",
  "instance": "/v1/sessions"
}

Status codes:

Code	Meaning
`200`	Success (idempotent replay).
`201`	Resource created.
`204`	Success, no body (releases, profile delete).
`400`	Validation error — fix the request body and retry.
`401`	Missing / invalid Bearer token.
`403`	Token valid, but scope insufficient.
`404`	Resource doesn't exist (or isn't in your workspace).
`409`	State conflict (e.g., trying to demote the last owner).
`422`	Schema-correct but semantically invalid (e.g., unknown region).
`429`	Rate-limited. See `Retry-After` header.
`503`	No capacity right now. Retryable with backoff.
`5xx`	Bug on our side. Filed automatically; please retry.

Pagination

List endpoints use cursor pagination:

GET /v1/sessions?limit=100&cursor=eyJhZnRlciI6Im…

Response includes:

{
  "items": [ … ],
  "next_cursor": "eyJhZnRlciI6Im…",
  "has_more": true
}

Don't parse the cursor; treat it as opaque. Cursors are stable across inserts (we sort by ULID, which encodes time monotonically).

Versioning

The API is on v1. We will:

Add fields and endpoints without version bumps.
Never change a field's type or remove a field within v1.
Ship breaking changes under /v2/* with at least 6-month parallel

operation of v1.

Subscribe to https://status.sessions.ventus.ai for deprecation announcements; we also surface them via Sunset HTTP headers per RFC 8594 starting 90 days out.

Live spec

You can fetch the live OpenAPI document at any time:

curl https://api.sessions.ventus.ai/openapi.json

That spec is the contract. If this page disagrees with the spec, the spec wins; please open a docs PR or report the drift.