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 web app. 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.
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:

​
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 13, 2026