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. Optionally add one or more Allowed IP ranges in CIDR notation to restrict where the key can be used from. See Restrict a key to specific IP ranges.
  5. 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, last usage timestamp, and the number of IP ranges it is restricted to.
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.

​
Restrict a key to specific IP ranges

You can pin an API key to one or more IP ranges so requests from any other address are rejected. Use this to lock a key to your office network, a NAT gateway, a bastion host, or a specific CI runner. When to use IP restrictions:
  • The key is used by a system with a stable, well-known egress IP (a CI job, a scheduled worker, a customer’s on-prem integration).
  • You want a stolen key to be unusable outside your network even before you notice and revoke it.
  • Your security policy requires network-level scoping in addition to key-level authentication.
Configure allowed ranges on a new key:
  1. On the Create API Key dialog, add each range to Allowed IP ranges and press Enter.
  2. Leave the list empty to make the key usable from any IP address (existing keys are unrestricted by default).
Change ranges on an existing key:
  1. Go to Settings > API Keys.
  2. Open the key’s menu and select Edit IP ranges.
  3. Add or remove ranges, then save. Changes take effect immediately.
Accepted notation:
  • IPv4 with a prefix length, for example 203.0.113.0/24 or 198.51.100.42/32 for a single address.
  • IPv6 with a prefix length, for example 2001:db8::/32 or 2001:db8::1/128.
  • IPv4-mapped IPv6 addresses (::ffff:203.0.113.50) are compared as IPv4, so a caller arriving over a dual-stack listener matches an IPv4 range.
  • /0 is rejected — it would match every address, which is what an empty list already means.
Each key can hold up to 50 ranges. How the caller IP is determined: Ravenna reads the caller IP from the CloudFront-Viewer-Address header, which CloudFront sets itself and a client cannot spoof. If your traffic passes through your own proxy or egress gateway before reaching Ravenna, add that gateway’s public egress IP to the allowlist, not the internal client’s address. Failure mode: A request from an address outside the allowlist is rejected with 403 Forbidden and no WWW-Authenticate header. The response body does not reveal that the key is IP-scoped — the same status is returned when the caller IP cannot be established at all — so a stolen key learns nothing about the restriction. The reason is recorded in Ravenna’s server logs.
Two related behaviors changed alongside IP-restricted keys and apply to every workspace, restricted or not: audit events on the API key surface record the real caller IP rather than the load balancer’s, and per-key rate limits are counted per real client instead of shared across every caller behind the load balancer.

​
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 August 21, 2026