Authenticate with the REST API
Updated 1 min read
On this page/ Before you start
The Relaypoint REST API lets your own systems create conversations, read customers and manage your workspace. Every request is authenticated with an API key sent as a Bearer token over HTTPS.
Before you start
- You're an Admin or Owner in the workspace
- You've created an API key (below)
- You've stored it somewhere safe, such as a secrets manager
Create an API key
Open API settings
Go to Settings › API keys and select Create key.
Choose scopes
Give the key only what it needs, e.g.
conversations:readandconversations:write.Copy the key
The key is shown once. Copy it into your secrets manager before closing the dialog.
Make your first request
Base URL: https://api.relaypoint.example/v1. Send the key in the Authorization header.
curl https://api.relaypoint.example/v1/conversations?status=open \
-H "Authorization: Bearer $RELAYPOINT_KEY" \
-H "Accept: application/json"const res = await fetch('https://api.relaypoint.example/v1/conversations?status=open', {
headers: { Authorization: `Bearer ${process.env.RELAYPOINT_KEY}` },
});
if (!res.ok) throw new Error(`Relaypoint ${res.status}`);
const { data } = await res.json();
console.log(`${data.length} open conversations`);import os
import requests
res = requests.get(
"https://api.relaypoint.example/v1/conversations",
params={"status": "open"},
headers={"Authorization": f"Bearer {os.environ['RELAYPOINT_KEY']}"},
timeout=10,
)
res.raise_for_status()
print(len(res.json()["data"]), "open conversations")<?php
$response = Http::withToken(env('RELAYPOINT_KEY'))
->get('https://api.relaypoint.example/v1/conversations', ['status' => 'open'])
->throw();
echo count($response->json('data')) . " open conversations\n";require "net/http"
require "json"
uri = URI("https://api.relaypoint.example/v1/conversations?status=open")
req = Net::HTTP::Get.new(uri, "Authorization" => "Bearer #{ENV.fetch('RELAYPOINT_KEY')}")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)["data"].lengthreq, _ := http.NewRequest("GET", "https://api.relaypoint.example/v1/conversations?status=open", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("RELAYPOINT_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()A successful response looks like this:
{
"data": [
{
"id": "conv_8h2k1x",
"subject": "Webhook deliveries failing with 401",
"status": "open",
"customer": { "name": "Jamie Kim", "email": "jamie@example.com" },
"assignee": null,
"created_at": "2026-10-30T09:14:22Z"
}
],
"next_cursor": "eyJpZCI6ImNvbnZfOGgyazF4In0"
}Errors
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request |
Fix the parameter named in error.field |
| 401 | unauthenticated |
Check the key and the Bearer prefix |
| 403 | missing_scope |
Create a key with the scope named in the message |
| 404 | not_found |
The id doesn't exist in this workspace |
| 429 | rate_limited |
Wait Retry-After seconds, then retry |
Pagination
List endpoints return up to 50 items and a next_cursor. Pass it back as ?cursor= to get the next page. When next_cursor is null, you've reached the end.
Video walkthrough
Was this page helpful?