Overview
Programmatic access to Relay conversations and contacts.
The Relay API is a REST API for reading and writing conversations, contacts, and stores in your workspace. It runs alongside the realtime product, so a message you push through the API appears live in the dashboard for your agents.
Prefer the terminal? The Relay CLI wraps this API for scripting and one-off tasks, and can migrate your data from Crisp in one command.
Authentication
Every request is authenticated with a workspace API key sent as a Bearer token:
curl https://api.superrelay.ai/v1/public/conversations \
-H "Authorization: Bearer rl_live_xxxxxxxxxxxxxxxxxxxxxxxx"Create and manage keys in Settings → API Keys. Keys are scoped to a single workspace and to a set of permissions:
| Scope | Grants |
|---|---|
conversations:read | List and read conversations and their messages |
conversations:write | Create conversations, push messages, update parameters |
contacts:read | List and read contacts and stores |
contacts:write | Create and update contacts and stores |
The plaintext key is shown once at creation — store it securely. If a key is lost or leaked, revoke it and create a new one.
Pagination
List endpoints are cursor-paginated and return a consistent envelope:
{
"data": [],
"has_more": true,
"next_cursor": "eyJ2IjoxLCJ0cyI6..."
}Pass next_cursor back as the cursor query parameter (and limit, 1–200) to
fetch the next page. Cursors are opaque — treat them as a token, don't parse
them.
Errors
Errors return the appropriate HTTP status with a JSON body of the form
{ "error": "message" }. Common cases: 401 (missing/invalid/expired key),
403 (key missing the required scope), 404 (resource not in this workspace),
400 (validation error).