API Reference
Public API requests authenticate with a workspace API key via the Authorization header. Console requests use a Clerk session JWT; WebSocket clients pass the same API key through the session WebSocket auth flow.
▓ auth
Authorization: Bearer pk_your_api_key
# Agents
POST
/agents
Deploy: create, or if the name exists add a new version and make it live
GET
/agents
List agents with session stats
GET
/agents/:idOrName
Get agent detail and parsed config (by id or name)
PUT
/agents/:id
Add a new version of an existing agent (id-addressed)
DELETE
/agents/:idOrName
Delete an agent and its versions (by id or name)
GET
/agents/:idOrName/versions
List an agent's versions
GET
/agents/:idOrName/deployments
List an agent's deployment timeline
POST
/agents/:idOrName/rollback
Roll back to a previous version
POST
/agents/:idOrName/rename
Rename an agent
# Sessions
POST
/agents/:agentId/sessions
Create a session for an agent
GET
/sessions
List sessions (filter: agent_id, status, limit, offset)
GET
/sessions/:id
Get session state
POST
/sessions/:id/messages
Send a message and start a turn
GET
/sessions/:id/messages?view=chat
Get chat-visible structured messages
GET
/sessions/:id/trace
Get the full structured transcript with trace-visible parts
POST
/sessions/:id/steer
Steer a running session
GET
/sessions/:id/events
Get step events (filter: since_seq)
GET
/sessions/:id/logs
Get structured logs
POST
/sessions/:id/inputs
Deliver a non-user-message wakeable input (channel_event / async_callback) to the durable input queue; idempotent
GET
/sessions/:id/runtime/spans
Get runtime instrumentation spans (execution timing / observability)
GET
/sessions/:id/ws
Real-time streaming WebSocket
# Execution Controls
GET
/sessions/:id/execution/snapshots
List a session's execution snapshots
POST
/sessions/:id/execution/snapshots
Capture an execution snapshot manually
GET
/execution/snapshots/:snapshotId
Get a single execution snapshot
POST
/execution/snapshots/:snapshotId/branches
Create a branch session from a snapshot
POST
/execution/snapshots/:snapshotId/replays
Create a replay session from a snapshot
GET
/execution/branches/:branchId
Get a branch or replay record
GET
/sessions/:id/execution/pause-policies
List pause policies
POST
/sessions/:id/execution/pause-policies
Create or update a pause policy
DELETE
/execution/pause-policies/:policyId
Delete a pause policy
GET
/sessions/:id/execution/pauses
List a session's pauses
GET
/execution/pauses/:pauseId
Get a single pause
POST
/execution/pauses/:pauseId/resume
Resume paused execution
POST
/execution/pauses/:pauseId/cancel
Cancel paused execution
# Channels (beta)
Channels let external systems trigger an agent session. Two entry shapes: webhook (the provider pushes events over HTTP) and managed_ws (an outbound long-lived connection PAREL maintains). The channel protocol is implemented by a connector plugin; connectors are limited to first-party / audited packages for now. routingPolicy decides how an event maps to a session: main, per_subject, per_actor, or isolated.
POST
/webhooks/channels/:connectionId
Inbound webhook (public endpoint, verified per connection)
GET
/channels/connections
List channel connections
POST
/channels/connections
Create a connection (type=webhook|managed_ws, plugin, config)
GET
/channels/connections/:connectionId
Get a connection
POST
/channels/connections/:connectionId/start
Enable a connection (managed_ws opens the long-lived connection)
POST
/channels/connections/:connectionId/stop
Disable a connection
GET
/channels/connections/:connectionId/status
Get a connection's runtime status
POST
/channels/bindings
Bind an agent to a connection (routingPolicy + filter)
GET
/channels/bindings
List bindings
DELETE
/channels/bindings/:bindingId
Delete a binding
GET
/channels/events
List channel events (filter: connectionId, sessionId, status, limit)
POST
/channels/deliveries
Enqueue an outbound delivery
# API Keys
GET
/api-keys
List API keys
POST
/api-keys
Create an API key
POST
/api-keys/:id/revoke
Soft-revoke an API key
DELETE
/api-keys/:id
Delete an API key
# Provider Keys
GET
/providers
List model providers and credential source
GET
/provider-keys
List BYOK model provider keys
POST
/provider-keys
Set a BYOK provider key
DELETE
/provider-keys/:id
Delete a BYOK provider key
# Secrets
Named values referenced as ${NAME} in agent configs; the response never returns a secret value, only its prefix. A row with an agent_id overrides that agent's org value.
GET
/required-secrets
Aggregate the ${NAME} references used by deployed agents and their set-state
GET
/secrets
List secrets (org + agent scoped)
POST
/secrets
Upsert a secret (agentId optional)
DELETE
/secrets/:id
Delete a secret
# Billing
GET
/billing/summary
Summarize usage by agent, model, and day
GET
/billing/usage
Usage records
GET
/billing/balance
Current balance and auto top-up settings
POST
/billing/topup
Create a top-up checkout
PUT
/billing/auto-topup
Update auto top-up settings
# Rate Limits
Limits are counted over a rolling 60-second window. Unauthenticated requests are limited per IP to 120 per minute; authenticated requests (with an API key) are additionally limited per key to 300 per minute. Both apply, and whichever trips first returns a 429.
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum for the applicable window (300 authenticated, 120 unauthenticated) |
| X-RateLimit-Remaining | Remaining requests |
| X-RateLimit-Reset | Unix timestamp of the window reset |
# Errors
| Code | Meaning |
|---|---|
| 400 | Bad request (missing/invalid params) |
| 401 | Unauthorized (missing/invalid API key) |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |