HTTP API
Authenticate requests, select an environment, and call Cereal from any language.
Call Cereal at https://app.trycereal.ai. Use the HTTP quickstart
for a complete example, or look up an operation in the API reference.
Make a request
Operations use POST /v1/<resource>/<operation> with JSON inputs. For example,
agents.upsert registers an agent and sessions.list reads sessions. Send {} when
an operation has no input fields.
curl --fail-with-body https://app.trycereal.ai/v1/sessions/list \
-H "Authorization: Bearer $CEREAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit": 20, "filter": {"metadata": {"customerId": "cus_42"}}}'Responses contain the operation's JSON result. Failures use an HTTP error status and
a JSON body with a _tag identifying the error. See errors.
Authenticate
Use Authorization: Bearer with an environment API key for your application or a
personal token for work you perform as a person, such as local development or account management.
Create API keys in Settings → API keys in the console.
Use cereal login to obtain a personal token for the CLI.
Keep these credentials in your application's server-side configuration. Browsers receive a short-lived token for a single session's stream. Credentials covers key creation, restrictions, and roles.
Select an environment
| Credential | Headers |
|---|---|
| API key | No selection headers needed. An optional x-cereal-environment must match the key’s bound environment. |
| Personal token | Use x-cereal-organization and x-cereal-environment to select the organization and environment for your work. |
Organization-level operations do not use the environment selection. The reference lists the headers accepted by each operation.
Required scopes
Scopes are independent. Include each one your application needs.
| Scope | Use it for |
|---|---|
read | Read agents, sessions, events, traces, and usage. |
data | Start sessions, send messages, answer approvals, upload attachments, and mint stream tokens. |
control | Configure agents, providers, connections, environments, and API keys. |
The API reference states each operation's scope. A typical application uses read,data;
configuration tooling also needs control. Some organization operations require a
person's credential and an appropriate role.
Stream a session
Mint a stream token with POST /v1/sessions/streamToken, then connect to
GET /sessions/{id}/stream. Use the token as a bearer credential with a fetch reader,
or in the token query parameter with EventSource. Reconnect with Last-Event-ID.
See streaming integration for application code and streaming protocol for event formats and cursors.
The OpenAPI document describes request and response schemas. The TypeScript client provides typed calls and error classes for applications using TypeScript.