This section walks you through integrating with the Operator API. We offer both REST endpoints for standard operations and low-latency WebSocket and Server-Sent Events (SSE) APIs for real-time use cases. The Operator API lets you:
  • Perform standard CRUD operations — create agents, update configurations, view conversations
  • Schedule conversations — set up outbound calls, start async chats
  • Hook into the agent lifecycle — drive the flow manually, inject replies over text, and let Operator handle scheduling, infra, and voice

​
Creating an API key

Log in to your Operator account and go to Developers → API Keys. Click New API key to generate one, and store it securely (e.g. in a secrets manager). Throughout these docs, we’ll refer to it as $OPERATOR_API_KEY. If you’re following along in a shell: 
export OPERATOR_API_KEY="your-api-key"

​
Connecting to the API

The Operator API is available at https://api.operator.xyz. To fetch a list of conversations your agent has handled: 
curl -X GET \
  --header "User-Agent: Your-Application-Name" \
  --header "Operator-Version: 2025-06-19" \
  --header "Authorization: Bearer $OPERATOR_API_KEY" \
  https://api.operator.xyz/conversations
You should see your most recent conversations returned.

​
Connecting to the API using ephemeral tokens

When building a client-side application, you can grant a full access to a conversation by creating an ephemeral access token. The token is a short-lived string that can be used to authenticate requests to the events and session APIs without sharing the API key, which should remain secret within your backend. Each conversation can have at most one active token at a time and tokens have a default lifetime of 3 hours. To use a token, do not pass the Authorization HTTP request header with your API key, instead set the ?token=<token> query parameter on the following APIs:

​
Concepts

​
Authentication

All requests must include your API key using a bearer token in the Authorization header: 
curl -X GET \
  --header "User-Agent: Your-Application-Name" \
  --header "Operator-Version: 2025-06-19" \
  --header "Authorization: Bearer op_prod_abcdefghijklmnopqrstuvwxyz" \
  https://api.operator.xyz/...

​
Versioning

We use date-based versioning. Breaking changes are released under new versions. The current version is: 2025-06-19. Include the version in all requests using the Operator-Version header.

​
Idempotency (coming soon!)

Let us know if you’d like us to prioritize this.

​
Troubleshooting

We aim to make errors self-explanatory. If something’s unclear or you hit a weird edge case, drop us a note.

​
Status codes

We use standard HTTP status codes:
  • 200 OK – Success.
  • 201 Created – Resource created.
  • 202 Accepted – Async operation accepted (no body returned).
  • 204 No Content – Resource deleted. Future DELETEs will return 404.
  • 400 Bad Request – Malformed request or missing parameters.
  • 401 Unauthorized – Invalid API key.
  • 403 Forbidden – API key lacks permission for this resource.
  • 404 Not Found – Resource doesn’t exist.
  • 405 Method Not Allowed – Method not allowed on this endpoint.
  • 409 Conflict – Usually due to idempotency key clash.
  • 418 I'm a Teapot – Your Operator is a teapot.
  • 429 Too Many Requests – Rate limit exceeded. Use exponential backoff with jitter.
  • 5xx – Something went wrong on our end. Try again later.

​
Error schema

Errors are returned in the following format: 
{
  "code": "UniqueErrorCode",
  "transient": false,
  "message": "A human readable message.",
  "data": { ... }
}
  • code: A stable identifier for this error.
  • transient: If true, it’s safe to retry the request.
  • message: A descriptive message. Don’t program against this—use code instead.
  • data: Optional. Extra context if relevant.