Skip to main content
Use the Ravenna API to programmatically create tickets, manage queues, sync data, and automate workflows in your workspace. All requests use REST principles with JSON responses and require API key authentication.

​
Getting started

Base URL: https://core.ravenna.ai/api Authentication: Include your API key in the x-ravenna-api-token header with every request. Example request:

​
Authentication

​
Create an API key

  1. Navigate to Settings in your Ravenna workspace
  2. Select API Keys from the sidebar
  3. Click Create API Key
  4. Copy your key and store it securely
You can view your API keys at any time from the settings page. Each key displays its creation date and last usage timestamp.
Keep your API key secure. Never expose it in client-side code or public repositories.

​
Use your API key

Include your API key in the x-ravenna-api-token header with every request:

​
Authenticate via query parameter

For environments where you cannot set custom HTTP headers, such as browser-based access, embedded links, or webhook receivers, pass your API key as the apiKey query parameter instead:
The query parameter is interchangeable with the header, but if both are present the header takes precedence. Header authentication remains the recommended method whenever your client supports it, since query parameters can be logged by proxies, browser history, and server access logs.
Avoid sharing or storing URLs that include API keys in query parameters. Treat them with the same care you would a password.

​
Monitor API key usage

The API Keys settings page shows a Last used timestamp for each key. Use this to:
  • Identify unused or stale keys that can be safely revoked
  • Verify that integrations are actively using their assigned keys

​
Revoke an API key

To revoke an API key:
  1. Go to Settings > API Keys
  2. Find the key you want to revoke
  3. Click the Revoke button
Revoked keys stop working immediately.

​
Finding resource IDs

Most write endpoints reference other resources by ID (for example, assigneeId, queueId, workspaceId, or a custom field ID). IDs are not shown in the Admin. Look them up with the matching list endpoint, then reuse the id value in your next request. Common lookups:
  • Users (for assigneeId, requesterId, approverIds): call GET /users. Narrow the result with the search, email, or workspaceId query parameters, then copy the id field from the user you want.
  • Workspaces (for workspaceId): call GET /workspaces to list every workspace your API key can access.
  • Queues (for queueId): call GET /queues, optionally filtered by workspaceId.
  • Forms, statuses, tags, and custom fields: call the matching list endpoint (for example, GET /forms, GET /statuses, GET /tags) and copy the id of the entry you need.
  • Statuses (for statusId on ticket create or update): status IDs are per-workspace and are not fixed enums. Call GET /statuses to list your workspace’s statuses (both system statuses like Open, In Progress, Waiting, Done, and Closed, and any custom sub-statuses), then use the id of the status you want to set.
If you already know a resource by name or email, use the search query parameter on the list endpoint instead of paginating through every record.

​
Making requests

​
Response format

All responses return JSON with a Content-Type: application/json header. The response body contains the resource data directly, without a top-level data wrapper. Successful responses return the requested resource. The example below shows a queue response, but the fields differ by endpoint. For example, GET /queues/{id} returns queue fields (id, name, status, and so on), while GET /users/{id} returns user fields. Refer to the endpoint’s reference page for the full field list.
List endpoints return an array of resources of the same shape:
Error responses always use the same envelope, regardless of endpoint. The code is a stable machine-readable string you can branch on, and message is a human-readable description that may change:

​
Response shape for ticket lists

Ticket list endpoints (GET /tickets, and related list endpoints that accept a responseType query parameter) support a responseType value that controls how much detail each ticket includes. The response shape is otherwise the same.
  • default (used when responseType is omitted): returns each ticket with its standard fields and expanded relations, such as the ticket’s queue name, status object, tags, and other embedded resources.
  • thin: returns the same set of top-level ticket fields, but embedded relations are collapsed to their IDs only. Use thin when you are listing many tickets and only need identifiers plus core scalar fields, for example when building a dashboard, exporting data, or feeding another system that will fetch full details on demand.
If you need more than IDs for related resources when using thin, fetch the related record separately with its own endpoint (for example, GET /queues/{id} or GET /statuses).

​
Rate limits

The API enforces rate limits to ensure fair usage. If you exceed the limit, you’ll receive a 429 Too Many Requests response. Wait before retrying your request.

​
Common error codes

Every error response uses the JSON envelope shown in Response format. The HTTP status maps to the following categories:
  • 400 Bad Request: Request body or query parameters are malformed or missing required fields
  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Valid API key but insufficient permissions for the requested action
  • 404 Not Found: Resource does not exist or is not visible to your API key
  • 409 Conflict: Request conflicts with the current state of the resource (for example, a duplicate)
  • 422 Unprocessable Entity: Request is well-formed but fails validation
  • 429 Too Many Requests: Rate limit exceeded, wait before retrying
  • 500 Internal Server Error: Server error, contact support if persistent
Last modified on July 21, 2026