Introduction

View in product

In this section, we will guide you through integrating with the Operator REST API.

​

Creating an API key

First, create an API key for your Operator. On the API Integration page, scroll down to the “API Keys” section. Click the “Generate Key” button to generate a new API key. Save this API key in a secure place such as a secrets manager.

In the rest of the documentation, we will reference this key as $OPERATOR_API_KEY. If you are following along in the shell, please run:

export OPERATOR_API_KEY="your-api-key"

​

Connecting to the API

The Operator REST API is accessible on the https://api.operator.xyz domain. To get a list of your Operator’s conversations, make a request like so:

curl -X GET \
  --header "User-Agent: Your-Application-Name" \
  --header "Operator-Version: 2024-11-11" \
  --header "Authorization: Bearer $OPERATOR_API_KEY" \
  --url-query "operator_id=$YOUR_OPERATOR_ID" \
  https://api.operator.xyz/conversations

You should see the most recent conversations appear!

​

Concepts

​

Authentication

We authenticate requests with an API Key authentication scheme. You can generate an API Key on the API Integration page.

When making a request to the Operator API, add the API Key to the request header. For example:

curl -X GET \
  --header "User-Agent: Your-Application-Name" \
  --header "Operator-Version: 2024-11-11" \
  --header "Authorization: Bearer op_prod_abcdefghijklmnopqrstuvwxyz"
  https://api.operator.xyz/...

​

Versioning

We use date-based versioning. When introducing breaking changes, we will release a new API version. The current version is 2024-11-11.

All API requests must include a Operator-Version header:

curl -X GET \
  --header "User-Agent: Your-Application-Name" \
  --header "Operator-Version: 2024-11-11" \
  --header "Authorization: Bearer op_prod_abcdefghijklmnopqrstuvwxyz"
  https://api.operator.xyz/...

​

Idempotency (coming soon!)

Please get in touch if you would like us to prioritize this sooner!

​

Troubleshooting

We have tried to make errors as descriptive as possible so that they can be solved from the error output alone. However, if you encounter any difficulties or obscure errors when integrating with the API, please drop a note in Slack!

​

Status codes & errors

We use standard HTTP status codes to indicate request success or failure. 2xx codes indicate success, 4xx codes indicate client errors, and 5xx codes indicate server errors.

We return these specific status codes:

• 200 OK - Successful request.
• 201 Created - Resource successfully created.
• 202 Accepted - Asynchronous operation accepted. No data will be returned.
• 204 No Content - Resource successfully deleted. Subsequent DELETE requests will return 404 Not Found.
• 400 Bad Request - Invalid request. Check that the request is well-formed and includes all required parameters.
• 401 Unauthorized - Invalid API key.
• 403 Forbidden - The provided API key lacks permission for this resource.
• 404 Not Found - The requested resource was not found.
• 405 Method Not Allowed - The requested HTTP method is not allowed for this resource.
• 409 Conflict - The request conflicts with a previous request, typically due to an idempotency key conflict.
• 418 I'm a Teapot - Your Operator is a teapot.
• 429 Too Many Requests - Rate limit exceeded. Please wait for a exponential backoff with jitter before retrying.
• 5xx - Server error. Please retry later.

Errors are returned with the following schema:

{
  // A code that uniquely identifies this error. Errors commonly share a status
  // code (e.g. 400), but they can be differentiated by their error code.
  "code": "UniqueErrorCode",
  // If the error is due to a temporary system state. Transient errors are not
  // cached in idempotent requests, meaning an idempotent request with a
  // transient error response can be safely retried. Inspired by
  // https://brandur.org/fragments/is-transient.
  "transient": false,
  // A human readable message to help understand and debug the error. These
  // messages may change freely without an API version bump. Please do not rely
  // on them to change your program's behavior--use the error code.
  "message": "A human readable message.",
  // Additional error-specific data. Most errors will not contain extra
  // metadata. However, when an error benefits from additional context,
  // that context will be provided here.
  "data": { ... }
}