Setup

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.

​

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.