API Reference

Before you start

You need an API key with the incidents:read scope and a terminal with curl.

For example, the workspace https://acme.tellagen.com uses the API address https://acme.api.tellagen.com.

• Create an API key

List incidents

1. Replace {company} with your workspace subdomain, such as acme.
2. Replace <token> with your API key.
3. Run the request in your terminal.

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents?limit=50' \
  --header 'Authorization: Bearer <token>'

Read the response

HTTP 200 means that the request succeeded. An empty workspace returns this response:

{
  "incidents": [],
  "has_more": false,
  "pagination": {
    "limit": 50,
    "has_more": false
  }
}

• 401: Check your API key
• 403: Check your permissions
• More results: use pagination.next_cursor

Create once, even if a request times out

Your alert script creates an incident, but the connection closes before the response arrives. The incident can already exist.

An Idempotency-Key identifies one create request. Tellagen remembers the key for 24 hours and returns the saved result for a repeat request.

1. Send a unique Idempotency-Key on the first create attempt.
2. Within 24 hours, retry with the same key and identical request body.
3. For a new incident, use a new key.

Idempotency-Key: payments-alert-2026-09-14-001

Update without overwriting someone else’s changes

Each incident has a version number called revision. An update sends the version that you last read.

If someone changes the incident first, Tellagen returns 412 instead of saving your update.

1. Read the incident with GET /api/v1/incidents/{id}.
2. Copy its revision or the Tellagen-Resource-Version response header.
3. Send that number in the If-Tellagen-Resource-Version header of your PATCH request.

Example: change an incident title

Suppose you read incident 42 at version 7. You want to change its title after a rollback.

Your API key needs both incidents:read and incidents:write. Its owner needs an active responder seat.

PATCH /api/v1/incidents/42 HTTP/1.1
Host: acme.api.tellagen.com
Authorization: Bearer <token>
Content-Type: application/json
If-Tellagen-Resource-Version: 7

{
  "title": "Payments API recovered after rollback"
}

If someone edits the incident first

A teammate changes incident 42 before your request arrives. Its version is now 8, so your request with version 7 returns 412.

1. Read the incident again.
2. Compare your title with the latest changes.
3. If your edit is still needed, send it with the new version.

• Update an incident: fields and examples

If you reach the rate limit

A 429 response includes Retry-After, which gives the wait time in seconds.

1. Wait for Retry-After before the next attempt.
2. Set a maximum number of attempts in your client.
3. If several workers share a workspace, add a small random delay between their retries.

• Rate limits and response headers
• Pagination and retry examples