API Reference

Prerequisites

For a workspace at https://acme.tellagen.com, the API origin is https://acme.api.tellagen.com. Use acme as the company placeholder in the request URL.

You need your workspace slug, an API key with incidents:read, curl, and a POSIX-compatible shell. Keep the key out of source control and application logs.

• Create an API key

List incidents

Replace the company and token placeholders with your workspace slug and API key. For a local server, replace the API origin with its address.

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

Read the response

A successful request returns HTTP 200. The JSON example below is a successful empty workspace response. Authentication failures return 401, and a valid key without incidents:read returns 403. If pagination.has_more is true, follow pagination.next_cursor as described in the pagination guide.

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

• Scopes
• 401: Check authentication
• 403: Check access
• Pagination guide

Idempotent creates

Send Idempotency-Key on POST /api/v1/incidents, POST /api/v1/incidents/{id}/timeline, POST /api/v1/services, and POST /api/v1/teams. A key is retained for 24 hours and can replay only the identical request body. Generate a new key for a logically new create.

Attach the key on the first create attempt, before any network uncertainty. If the 24-hour retention has expired, do not assume the old key can replay: look up the intended resource first and use a new key only when you have established that a new create is required.

A reused key with different content returns idempotency_key_reused. idempotency_in_progress means the identical request is still being handled and may be retried after Retry-After. idempotency_outcome_unknown means the earlier operation may have completed; do not retry automatically. Reconcile by listing or fetching the resource, or ask an operator to decide.

Revision-protected updates

API-key clients must send If-Tellagen-Resource-Version on PATCH /api/v1/incidents/{id}, PATCH /api/v1/timeline/{id}, PATCH /api/v1/services/{id}, PATCH /api/v1/teams/{id}, and PATCH /api/v1/custom-fields/{id}. Use the positive revision from the latest response or Tellagen-Resource-Version response header.

Those are the five revision-protected resource PATCH operations. PATCH /api/v1/teams/{id}/members/{userId}, PATCH /api/v1/incidents/{id}/custom-fields, and PATCH /api/v1/incidents/{id}/slack/channel-name use their operation-specific validation and do not take If-Tellagen-Resource-Version.

The token also needs the matching read scope to fetch the resource and its current revision before a protected PATCH. A 412 response means another writer changed the resource. Fetch the latest representation, compare your intended edit with the new state, and then either abandon it or send a reconciled PATCH with the new revision. Never overwrite automatically after a conflict.

Rate limits and request identity

A 429 response reports the current quota in X-RateLimit-Limit and X-RateLimit-Remaining. Wait for Retry-After before retrying. Bound attempts and add jitter when many workers share one workspace key.

Send a unique X-Request-ID when tracing a workflow. The response echoes an accepted ID or supplies one; record it with the status and structured error code.

Write requests accept one JSON document no larger than 1 MiB. Invalid JSON, multiple JSON values, unknown properties, and oversized bodies fail before application logic runs.

• Errors and recovery
• Pagination and bounded retries