# Tellagen API Reference

> Generated from the same canonical API contract as the human-readable reference at https://tellagen.com/api-reference.

Documentation contract: `sha256:898ee484330817a84c170e0e87bf24f27e62e5838635ee4c9daf6a7a3d704ce9`. This fingerprint identifies the generated documentation contract, not the API major version.

## Endpoint index

### Incidents

[Incidents Markdown export](https://tellagen.com/api-reference/incidents/markdown)

- [`GET /api/v1/incidents`](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incidents) — List incidents
- [`POST /api/v1/incidents`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents) — Create incident
- [`GET /api/v1/incidents/archived`](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incidents-archived) — List archived incidents
- [`GET /api/v1/incident-references/{reference}`](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incident-references-reference) — Get incident by permanent reference
- [`GET /api/v1/incidents/{id}`](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incidents-id) — Get incident
- [`PATCH /api/v1/incidents/{id}`](https://tellagen.com/api-reference/incidents#incidents-endpoint-patch-api-v1-incidents-id) — Update incident
- [`POST /api/v1/incidents/{id}/resolve`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-resolve) — Resolve incident
- [`POST /api/v1/incidents/{id}/close`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-close) — Close incident without resolution
- [`POST /api/v1/incidents/{id}/reopen`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-reopen) — Reopen incident
- [`GET /api/v1/incidents/{id}/provisioning`](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incidents-id-provisioning) — Get incident integration setup
- [`POST /api/v1/incidents/{id}/provisioning/retry`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-provisioning-retry) — Retry incident integration setup
- [`POST /api/v1/incidents/{id}/archive`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-archive) — Archive incident
- [`POST /api/v1/incidents/{id}/restore`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-restore) — Restore incident
- [`POST /api/v1/incidents/{id}/rename-slack-channel`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-rename-slack-channel) — Reapply the Slack channel-name template (deprecated)
- [`POST /api/v1/incidents/{id}/slack/channel-name/preview`](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-slack-channel-name-preview) — Preview an incident Slack channel name
- [`PATCH /api/v1/incidents/{id}/slack/channel-name`](https://tellagen.com/api-reference/incidents#incidents-endpoint-patch-api-v1-incidents-id-slack-channel-name) — Update an incident Slack channel name

## Base URL

`https://{company}.api.tellagen.com/api/v1/`

Replace `{company}` with your company subdomain. Requests and JSON responses use `application/json` unless an endpoint documents an empty response.

## Authentication

Create an API token in **Settings > API keys** and send it as a Bearer token:

`Authorization: Bearer tllg_YOUR_TOKEN`

Tokens are shown only once when created. Grant only the scopes the client needs.

## Integration guides

- [Make your first request](https://tellagen.com/api-reference#first-request)
- [Build reliable requests](https://tellagen.com/api-reference#reliable-requests)
- [Filter and paginate collections](https://tellagen.com/api-reference/guides/pagination)
- [Create and move an incident through its workflow](https://tellagen.com/api-reference/guides/workflows)
- [Send custom-field values](https://tellagen.com/api-reference/guides/field-values)

## Versioning

All endpoints in this reference use `/api/v1` and are supported.

**Compatible changes.** Tellagen can add optional response fields or enum values. Ignore response fields that your client does not use.

**Breaking changes.** Tellagen uses a new major version for incompatible changes.

**Deprecated endpoints.** Tellagen marks an endpoint deprecated at least 180 days before removal. Deprecated responses identify the replacement endpoint.

## Scopes

| Scope | Description |
| --- | --- |
| `incidents:read` | List and retrieve incidents, and discover writable workflow statuses and severities |
| `incidents:write` | Create and update incidents and timeline events. Requires an active responder seat for the key owner. |
| `slack_context:read` | Read Slack context collected for incident investigation |
| `services:read` | List and retrieve services, and discover writable service tiers |
| `services:write` | Create, update, and archive services. Requires an active responder seat and the manage_settings role permission. |
| `teams:read` | List and retrieve teams and members |
| `teams:write` | Create, update, and archive teams; manage members. Requires an active responder seat and the manage_teams role permission. |
| `custom_fields:read` | List and retrieve custom field definitions and values |
| `custom_fields:write` | Create, update, and archive custom fields; set incident field values. Definition changes require the manage_settings role permission. Incident value changes require an active responder seat. |

## Prerequisite definitions

- **Active responder seat** (`active_responder`): The API key owner must have an active responder seat.
- **Manage workspace settings** (`manage_settings`): The API key owner must have the manage_settings role permission.
- **Manage teams** (`manage_teams`): The API key owner must have the manage_teams role permission.
- **Incident is not archived** (`mutable_incident`): The incident must not be archived. Workflow-state restrictions are described by each operation.
- **Linked Slack channel** (`slack_channel`): The incident must have a linked Slack channel.

## Errors

Errors always include a stable `code` and a human-readable `message`. They can also include `field`, `details`, and `request_id`.

You can send `X-Request-ID` with a request. If you omit it, the API generates one. The response header and error body return the same value.

### Missing scope (403)

```json
{
  "code": "missing_scope",
  "message": "insufficient scope: incidents:write required",
  "details": {
    "required_scope": "incidents:write"
  },
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

### Stale resource version (412)

```json
{
  "code": "precondition_failed",
  "message": "the resource changed; fetch it again and retry with the current resource version",
  "field": "If-Tellagen-Resource-Version",
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

### Rate limit (429)

```json
{
  "code": "rate_limited",
  "message": "rate limit exceeded",
  "details": {
    "retry_after_seconds": 1
  },
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

When you contact support, include the request ID, method, path, status, and time. Omit tokens and private request bodies.

| Code | Meaning | Next action | Retry |
| --- | --- | --- | --- |
| `authentication_required` | The request has no valid API token or session. | Send an active Bearer token for this workspace. Replace an expired or revoked key. | After correcting authentication. |
| `missing_scope` | The token lacks the scope named in details.required_scope. | Read details.required_scope. Ask a workspace manager for a replacement key with that scope. | After correcting access. |
| `responder_seat_required` | The key owner needs the seat named in details.required_seat. | Ask a workspace manager to review the key owner’s responder seat. | After correcting access. |
| `missing_role_permission` | The key owner lacks details.required_permission or one of details.required_roles. | Ask a workspace manager to review the owner’s role and the permission named in details. | After correcting access. |
| `permission_denied` | Access is denied without exposing private authorization state. | Verify the workspace, key owner, and resource access with a workspace manager. | After correcting access. |
| `invalid_resource_state` | The operation is not valid for the current resource state. | Read the current resource. Restore an archived resource or choose an operation allowed in its current state. | After reconciling state. |
| `invalid_relationship_state` | Restore requires a retained owner or parent relationship to identify an active resource. | Restore the retained parent or owning team before restoring this resource. | After correcting the relationship. |
| `duplicate_slug` | A team already uses the requested slug. | Read the existing team or choose a different slug. | After changing the request. |
| `invalid_json` | The request body is not one valid JSON document. | Send one valid JSON object with Content-Type: application/json. | After correcting the body. |
| `unknown_field` | The request contains an unsupported JSON property named in field. | Remove or correct the property named in field. Use the request schema, not the response schema. | After correcting the body. |
| `request_body_too_large` | The request body is larger than 1 MiB. | Reduce the body to 1 MiB or less. | After reducing the body. |
| `multiple_json_values` | The request body contains more than one JSON document. | Send one JSON document rather than concatenated documents. | After correcting the body. |
| `idempotency_key_reused` | The key was already used with different request content. | Recover the original request for this key. Use a new key only for a different intended operation. | Do not resend changed content with the same key. |
| `idempotency_in_progress` | An equal request with this key is still running. Retry later. | Wait for Retry-After, then resend the identical body with the same key. | After the indicated delay. |
| `idempotency_outcome_unknown` | An earlier request may have completed, but its result could not be stored. Do not retry it automatically. | Read the resource state and contact support with the request ID before deciding whether to create again. | Never retry automatically. |
| `precondition_required` | An API-key PATCH request omitted If-Tellagen-Resource-Version. | Read the resource, then send its Tellagen-Resource-Version as If-Tellagen-Resource-Version. | After adding the current version. |
| `invalid_precondition` | If-Tellagen-Resource-Version is not a positive integer. | Use the positive integer version returned for this resource. Do not use an ETag or a timestamp. | After correcting the header. |
| `precondition_failed` | The resource changed after the client read it. | Read the resource again. Reconcile your intended change with the current state before using its new version. | After reconciling the change. |
| `rate_limited` | Retry after details.retry_after_seconds or the Retry-After header. | Wait for Retry-After or details.retry_after_seconds. Limit concurrency across the workspace. | After the indicated delay, with the original idempotency key where supported. |
| `internal` | The server failed without exposing an internal error. | Keep the request ID. Read current state before retrying a write whose outcome is uncertain. | Retry reads with bounded backoff. Follow operation-specific rules for writes. |
| `invalid_slack_channel_name_request` | The channel-name request is invalid. | Use custom mode with name, or workspace_template mode without name. | After correcting the request. |
| `slack_not_configured` | The workspace has no usable Slack integration. | Ask a workspace manager to connect or repair Slack. | After repairing the integration. |
| `incident_slack_channel_missing` | The incident has no linked Slack channel. | Link a channel through the incident workspace before requesting a rename. | After linking a channel. |
| `slack_channel_not_found` | Slack cannot find the linked channel. | Verify the channel still exists and that the integration can access it. | After repairing channel access. |
| `slack_channel_name_taken` | Another Slack channel uses the requested name. | Choose another custom name or revise the workspace naming template. | After choosing an available name. |
| `invalid_idempotency_key` | The idempotency key has an invalid length or character. | Use 1–128 visible, non-space ASCII characters. A UUID is suitable. | After correcting the key. |

| Status | Meaning |
| --- | --- |
| `400` | Bad Request — invalid input or missing required fields |
| `401` | Unauthorized — missing or invalid token |
| `403` | Forbidden — insufficient scope or responder access |
| `404` | Not Found — resource does not exist |
| `409` | Conflict — resource state prevents the request |
| `412` | Precondition Failed — the supplied resource version is stale |
| `428` | Precondition Required — this operation needs If-Tellagen-Resource-Version |
| `429` | Too Many Requests — rate limit exceeded |
| `500` | Internal Server Error |

Authenticated requests share a workspace limit. Anonymous requests and failed authentication attempts use the trusted client IP. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining`. A `429` response also includes `Retry-After`.

## Incidents

Creates, lists, reads, updates, archives, restores, and changes the lifecycle state of incidents.

### `GET /api/v1/incidents`

**List incidents.** Returns one page of active incidents. The default page size is 50, and the maximum is 100. Values repeated within one set filter combine with OR; different filters combine with AND. Filters apply before pagination and also apply to restricted_count. Omitted sort keeps the legacy created_at-descending order. Extended collection queries use opaque v3 cursors bound to the company, normalized predicates, resolved metadata, and exact typed sort key. Legacy v1/v2 cursors remain accepted only with the legacy default order and legacy-compatible predicates. Pagination is deterministic keyset traversal for unchanged rows, not a cross-request database snapshot.

Required scope: `incidents:read`

Operation ID: `listIncidents`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Query parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | No | The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. Maximum: 100. Default: 50. |
| `cursor` | `string` | No | The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. Maximum length: 4096 characters. |
| `scope` | `string` | No | Selects all incidents or only postmortems. The default is all. Default: "all". Allowed values: `"all"` \| `"postmortem"` |
| `status` | `string[]` | No | Includes incidents with any supplied workflow status. Repeating status supplies more than one accepted value. |
| `severity` | `string[]` | No | Includes incidents with any supplied severity key. Repeating severity supplies more than one accepted value. |
| `service` | `string[]` | No | Includes incidents with any supplied service slug. Repeating service supplies more than one accepted value. |
| `team_id` | `integer[]` | No | Includes incidents with any supplied owning-team ID. Repeating team_id supplies more than one accepted value. Each ID must be positive. |
| `created_from` | `string (RFC 3339)` | No | Includes incidents created at or after this RFC 3339 timestamp. |
| `created_to` | `string (RFC 3339)` | No | Includes incidents created at or before this RFC 3339 timestamp. |
| `created_before` | `string (RFC 3339)` | No | Includes incidents created strictly before this RFC 3339 timestamp. It cannot be combined with created_to. |
| `region` | `string[]` | No | Includes incidents with any supplied case-insensitive region. Repeating region supplies more than one accepted value. Maximum items: 100. |
| `lifecycle` | `string[]` | No | Includes any supplied incident lifecycle: ticket, incident, postmortem, or alert. Maximum items: 100. Allowed values: `"ticket"` \| `"incident"` \| `"postmortem"` \| `"alert"` |
| `service_tier` | `string[]` | No | Includes incidents whose canonical tenant service has any supplied tier. Maximum items: 100. Allowed values: `"t0"` \| `"t1"` \| `"t2"` \| `"t3"` |
| `effective_team_id` | `integer[]` | No | Includes incidents assigned directly to any supplied team or inheriting it from the canonical service. Repeating the parameter supplies more than one accepted positive ID. Maximum items: 100. |
| `unassigned_team` | `boolean` | No | When true, also includes incidents with no direct or canonical-service team. Default: false. |
| `mine` | `boolean` | No | When true, includes incidents assigned to the authenticated user, or created by that user when no active assignee exists. API-key-only authentication cannot use this filter. Default: false. |
| `active_only` | `boolean` | No | When true, excludes workflow stages configured as terminal. False does not add a status restriction. |
| `status_scope` | `string` | No | Selects all statuses, nonterminal ongoing statuses, or one configured workflow-stage slug. Minimum length: 1 characters. Maximum length: 2048 characters. |
| `diagnosis` | `string[]` | No | Includes incidents in any supplied diagnosis state. Repeating diagnosis supplies more than one accepted value. Maximum items: 100. Allowed values: `"not_run"` \| `"in_progress"` \| `"completed"` \| `"needs_attention"` \| `"unavailable"` |
| `sort` | `string` | No | Selects the collection sort field. Custom requires sort_custom_field. Omission keeps legacy created_at order. Allowed values: `"created_at"` \| `"last_event_at"` \| `"severity"` \| `"service"` \| `"diagnosis"` \| `"case"` \| `"regions"` \| `"team"` \| `"impact"` \| `"status"` \| `"owner"` \| `"events"` \| `"custom"` |
| `direction` | `string` | No | Sort direction for both the selected key and incident-ID tiebreaker. Default: "desc". Allowed values: `"asc"` \| `"desc"` |
| `sort_custom_field` | `string` | No | Active custom-field slug used when sort is custom. The server resolves and validates its stored type. Minimum length: 1 characters. Maximum length: 64 characters. |
| `custom_filter` | `string[]` | No | A JSON object with slug, operator, and value. Repeat for up to 32 predicates. Values remain typed JSON; arrays preserve choices containing commas. Supported operators depend on the resolved field type: string is/is_not/contains/starts_with; select is/is_not; boolean is; number and monetary eq/gt/lt/gte/lte/between; date and datetime is/before/after/between/gte/lte; time is/before/after; multiselect includes_any/includes_all/excludes. SQL fragments and client-supplied field types are rejected. Maximum items: 32. |
| `include_counts` | `boolean` | No | When true, returns authoritative matched, all, ongoing, and per-status counts before cursor and limit. Default: false. |
| `impact_status` | `string[]` | No | Includes incidents with any supplied customer-impact status. Allowed values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `affected_customers_op` | `string` | No | Selects the operator for the affected-customer comparison. This parameter and affected_customers_value must appear together. Allowed values: `"<"` \| `">"` \| `"="` |
| `affected_customers_value` | `integer` | No | The non-negative affected-customer count for comparison. This parameter and affected_customers_op must appear together. Minimum: 0. |
| `mrr_op` | `string` | No | Selects the operator for the MRR comparison. This parameter and mrr_value must appear together. Allowed values: `"<"` \| `">"` \| `"="` |
| `mrr_value` | `integer` | No | The non-negative MRR amount for comparison, in minor currency units. This parameter and mrr_op must appear together. Minimum: 0. |
| `mrr_currency` | `string` | No | A three-letter ISO currency code. If mrr_basis is source, this parameter is required. Pattern: ^[A-Z]{3}$. |
| `mrr_basis` | `string` | No | Selects normalized workspace currency values or original source currency values. The default is normalized. Default: "normalized". Allowed values: `"normalized"` \| `"source"` |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

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

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incidents` | `object[]` | Always | The incidents in this page. |
| `incidents[].id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incidents[].revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incidents[].company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incidents[].human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incidents[].title` | `string` | Always | The editable display title of the incident. |
| `incidents[].service` | `string` | Always | The service slug associated with the incident. |
| `incidents[].regions` | `string[]` | Always | The affected regions. |
| `incidents[].severity` | `string` | Always | The configured severity key. |
| `incidents[].slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incidents[].meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incidents[].doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incidents[].status` | `string` | Always | The configured workflow-status key. |
| `incidents[].status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incidents[].last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incidents[].last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incidents[].issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incidents[].severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incidents[].impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incidents[].customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incidents[].impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incidents[].first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incidents[].first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incidents[].recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incidents[].duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incidents[].duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incidents[].team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incidents[].event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incidents[].investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incidents[].investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incidents[].investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incidents[].investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incidents[].investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incidents[].investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incidents[].created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incidents[].created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incidents[].custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incidents[].archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incidents[].archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incidents[].incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incidents[].incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incidents[].has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `has_more` | `boolean` | Always | Deprecated top-level alias for pagination.has_more. |
| `next_cursor` | `string` | Optional | Deprecated top-level alias for pagination.next_cursor. |
| `pagination` | `object` | Always | Pagination details for a collection response. |
| `pagination.limit` | `integer` | Always | The maximum number of items requested for this page. Minimum: 1. Maximum: 100. |
| `pagination.has_more` | `boolean` | Always | Indicates whether another page is available. |
| `pagination.next_cursor` | `string` | Optional | The opaque cursor for the next page. This field is absent on the final page. |
| `restricted_count` | `integer` | Optional | The number of matching incidents excluded by the workspace history limit. Minimum: 0. |
| `history_limited` | `boolean` | Optional | Indicates whether the workspace history limit applies to this response. |
| `mrr_currency` | `string` | Optional | The workspace reporting currency used for normalized MRR values. |
| `mrr_conversion_mode` | `string` | Optional | The workspace mode for MRR currency conversion. Possible values: `"normalized"` \| `"source_only"` |
| `mrr_projection_state` | `string` | Optional | The MRR projection state. Possible values: `"ready"` \| `"stale"` \| `"unavailable"` |
| `supported_mrr_currencies` | `string[]` | Optional | The ISO currency codes supported by MRR filters. |
| `collection_counts` | `object` | Optional | Complete collection counts before cursor and limit when include_counts is true. |
| `collection_counts.matched` | `integer` | Always | Count after every predicate, including status selection. Minimum: 0. |
| `collection_counts.all` | `integer` | Always | Count after non-status predicates, excluding status, status_scope, and active_only. Minimum: 0. |
| `collection_counts.ongoing` | `integer` | Always | Nonterminal count after non-status predicates. Minimum: 0. |
| `collection_counts.by_status` | `object` | Always | Exact counts by normalized stored status after non-status predicates. |

Returns incidents and pagination fields. If has_more is true, next_cursor is the cursor for the next request. When include_counts is true, collection_counts describes the complete filtered collection before cursor and limit. Nullable fields are always present. Empty arrays and empty custom_fields objects are also present.

```json
{
  "incidents": [
    {
      "id": 1,
      "revision": 7,
      "company_id": 7,
      "human_id": "INC-2025-001",
      "title": "Payments API requests timing out",
      "service": "payments",
      "regions": [
        "us-east-1"
      ],
      "severity": "sev1",
      "slack_channel_id": "C08ABC123",
      "meet_url": "https://meet.google.com/abc-defg-hij",
      "doc_url": "https://docs.google.com/d/1abc",
      "status": "active",
      "status_changed_at": "2025-01-30T12:05:00Z",
      "last_event_at": "2025-01-30T12:10:00Z",
      "last_event_summary": "Investigating root cause",
      "issue_type": "incident",
      "severity_mode": "manual",
      "impact_summary": "Payment processing delayed for EU customers",
      "customer_impact_status": "confirmed",
      "impact_started_at": "2025-01-30T11:55:00Z",
      "first_reported_at": "2025-01-30T11:58:00Z",
      "first_responded_at": "2025-01-30T12:00:00Z",
      "recovered_at": null,
      "duration_seconds": 900,
      "duration_anchor": "impact_started_at",
      "team_id": 42,
      "event_count": 5,
      "investigation_summary": null,
      "created_at": "2025-01-30T12:00:00Z",
      "created_by": "oncall@example.com",
      "custom_fields": {},
      "archived_at": null,
      "archived_by": null,
      "incident_manager": "oncall@example.com",
      "incident_responders": [
        "responder@example.com"
      ],
      "has_assignees": true
    }
  ],
  "has_more": true,
  "next_cursor": "opaque-server-cursor",
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "opaque-server-cursor"
  },
  "collection_counts": {
    "matched": 12,
    "all": 20,
    "ongoing": 8,
    "by_status": {
      "active": 8,
      "resolved": 12
    }
  }
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents`

**Create incident.** The API validates every field before it creates the incident. Unknown JSON fields return 400. The API trims text and removes duplicate regions. It rejects values that exceed their length limits. It validates the team before saving the incident. The incident, declaration history, changelog, and outgoing setup work commit together. If Slack is configured and create_slack_channel is true, a durable worker creates the channel after the incident is saved. Use getIncidentProvisioning to inspect setup state and retryIncidentProvisioning to retry failed steps.

Required scope: `incidents:write`

Operation ID: `createIncident`
Contract: `supported`
Retry guidance: Retry an identical request with the same Idempotency-Key used on the first attempt, within 24 hours. Never retry an unknown outcome automatically.
Prerequisites: None

#### Request headers

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | `string` | No | A key for safe retries of a create request. It must contain 1–128 visible, non-space ASCII characters. The same key applies only to an identical request. Minimum length: 1 characters. Maximum length: 128 characters. Pattern: ^[\x21-\x7E]+$. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

For `<idempotency-key>`, choose a unique key on the first attempt. Reuse it only when retrying the identical request.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents' \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Payments API requests timing out",
  "impact_summary": "EU customers cannot complete payment authorization",
  "create_slack_channel": false
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | No | The incident display title. The maximum length is 160 characters. If title is omitted, the API derives it from impact_summary or service. Maximum length: 160 characters. |
| `service` | `string` | No | The service slug. The maximum length is 128 characters. Maximum length: 128 characters. |
| `regions` | `string[]` | No | The affected regions. The API trims each value and removes duplicates. |
| `severity` | `string` | No | A severity key from the workspace configuration. If severity is omitted, the API uses the configured default severity. |
| `short_title` | `string` | Conditional | A short slug for the incident reference and Slack channel name. The API normalizes it and limits it to 12 characters. If short_title_required is true, this field is required. This field is not the incident title. Required when: Required when the workspace configuration enables short titles. Maximum length: 12 characters. |
| `impact_summary` | `string` | No | The customer or operational impact summary. This field is separate from title and can change independently. |
| `declaration_evidence` | `string` | No | Alert or log text for the incident_declared timeline event. This field records responder evidence and does not set customer_impact_status. |
| `doc_url` | `string` | No | An absolute HTTP or HTTPS URL stored as an incident reference. The API can import a supported initial report as a separate timeline event. |
| `import_source_timeline_event` | `boolean` | Conditional | If this value is true, the API imports a supported Slack or PagerDuty doc_url as a timeline event. This value requires doc_url. A signed Slack declaration can require import regardless of this value. Required when: This field may be true only when doc_url is provided. |
| `team_id` | `integer` | No | A positive owning-team ID. If the team does not exist, the API returns 404. If the team is archived, the API returns 400. If the request omits team_id, the API uses the service owner. Minimum: 1. |
| `issue_type` | `string` | No | The work type. If the request omits issue_type, the API uses incident. Allowed values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `status` | `string` | No | An initial workflow-status key from the workspace configuration. If the request omits status, the API uses the configured default status. |
| `severity_mode` | `string` | No | The severity selection mode. If the request omits severity_mode, the API uses auto. Allowed values: `"auto"` \| `"manual"` |
| `create_slack_channel` | `boolean` | No | Controls Slack channel creation. If the request omits create_slack_channel, the API uses the workspace Slack configuration. Slack must be configured before the API can create a channel. |
| `invite_usergroups` | `string[]` | No | The Slack user-group IDs to invite. If the request omits invite_usergroups, the API uses the workspace Slack configuration. |
| `custom_field_values` | `object[]` | No | Custom-field values for the new incident. The API validates every value and each required_on_creation field before Slack work. It saves these values and the incident in one database transaction. |
| `custom_field_values[].field_id` | `integer` | Yes | The positive ID of the custom-field definition. Minimum: 1. |
| `custom_field_values[].value` | `any` | Yes | The value for the custom field. The accepted type depends on field_type. |

Request JSON:

```json
{
  "title": "Payments API requests timing out",
  "impact_summary": "EU customers cannot complete payment authorization",
  "create_slack_channel": false
}
```

#### Success response

Status: `201 Created`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |
| `source_timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `source_timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `source_timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `source_timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `source_timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `source_timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `source_timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `source_timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `source_timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `source_timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `source_timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `source_timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `source_timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `source_timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `source_timeline_event.title` | `string` | Always | The optional display title of the event. |
| `source_timeline_event.body` | `string` | Always | The event description. |
| `source_timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `source_timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `source_timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `source_timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `source_timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `source_timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `source_timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `source_timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `source_timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `source_timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `source_timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `source_timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `source_timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `source_timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `source_timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `source_timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `source_timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `source_timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `source_timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `source_timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `source_timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `source_timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `source_timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `source_timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `source_timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `source_timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |
| `source_timeline_import` | `object` | Optional | The result of importing an initial report as a timeline event. |
| `source_timeline_import.status` | `string` | Always | The import result. Possible values: `"imported"` \| `"failed"` \| `"unavailable"` \| `"invalid"` \| `"unsupported"` |
| `source_timeline_import.provider` | `string` | Optional | The detected source provider. When the provider is unavailable, this field is absent. |
| `slack_declaration_attachment` | `object` | Optional | The result of attaching Slack declaration context to the incident. |
| `slack_declaration_attachment.status` | `string` | Always | The attachment result. Possible values: `"attached"` \| `"failed"` |
| `slack_declaration_images` | `object` | Optional | The result of copying images from a Slack declaration. |
| `slack_declaration_images.status` | `string` | Always | The image-copy result. Possible values: `"attached"` \| `"partial"` \| `"failed"` |
| `slack_declaration_images.total` | `integer` | Always | The total number of Slack images considered. Minimum: 0. |
| `slack_declaration_images.attached` | `integer` | Always | The number of images copied successfully. Minimum: 0. |
| `slack_declaration_images.failed` | `integer` | Always | The number of images that the API did not copy. Minimum: 0. |
| `declaration_next` | `string` | Optional | The next incident workspace section requested by a signed Slack declaration. |
| `custom_field_values` | `object[]` | Optional | The custom-field values saved in the same transaction as the incident. |
| `custom_field_values[].id` | `integer` | Always | The positive numeric ID of the stored value. Minimum: 1. |
| `custom_field_values[].incident_id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `custom_field_values[].custom_field_id` | `integer` | Always | The positive numeric ID of the custom-field definition. Minimum: 1. |
| `custom_field_values[].value` | `any` | Optional | The stored field value. Its type depends on field_type. |
| `custom_field_values[].created_at` | `string (RFC 3339)` | Always | The initial value storage time. |
| `custom_field_values[].updated_at` | `string (RFC 3339)` | Always | The time of the latest value change. |

The incident field contains the saved incident. custom_field_values contains values saved in the same database transaction. timeline_event contains the incident_declared event. source_timeline_event contains the imported source event. A 201 response does not guarantee a successful evidence import. source_timeline_import identifies the provider and reports the import result.

```json
{
  "incident": {
    "id": 1,
    "revision": 1,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev2",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://acme.pagerduty.com/incidents/PXYZ123",
    "status": "active",
    "status_changed_at": "2025-01-30T12:00:00Z",
    "last_event_at": null,
    "last_event_summary": "",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "EU customers cannot complete payment authorization",
    "customer_impact_status": "unknown",
    "impact_started_at": null,
    "first_reported_at": null,
    "first_responded_at": null,
    "recovered_at": null,
    "duration_seconds": 0,
    "duration_anchor": "created_at",
    "team_id": 42,
    "event_count": 0,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "",
    "incident_responders": [],
    "has_assignees": false
  },
  "timeline_event": {
    "id": 101,
    "revision": 1,
    "incident_id": 1,
    "started_at": "2025-01-30T12:00:00Z",
    "at": "2025-01-30T12:00:00Z",
    "ended_at": null,
    "is_ongoing": false,
    "group_id": null,
    "is_key": false,
    "source": "system",
    "source_ref": "",
    "type": "incident_declared",
    "icon": "🚨",
    "title": "Incident declared",
    "body": "PagerDuty reports elevated payment authorization latency.",
    "collaboration_generation": 1,
    "tags": [],
    "ai_context": "",
    "created_by": "oncall@example.com",
    "comment_count": 0,
    "attachments": [],
    "source_window_started_at": null,
    "source_window_ended_at": null,
    "evidence_links": []
  },
  "source_timeline_event": {
    "id": 102,
    "revision": 1,
    "incident_id": 1,
    "started_at": "2025-01-30T12:00:00.000001Z",
    "at": "2025-01-30T12:00:00.000001Z",
    "ended_at": null,
    "is_ongoing": false,
    "group_id": null,
    "is_key": false,
    "source": "pagerduty",
    "source_ref": "pagerduty:PXYZ123",
    "type": "alert",
    "icon": "🚨",
    "title": "Payment authorization latency",
    "body": "PagerDuty incident PXYZ123 is triggered.",
    "collaboration_generation": 1,
    "tags": [],
    "ai_context": "",
    "created_by": "oncall@example.com",
    "comment_count": 0,
    "attachments": [],
    "source_window_started_at": null,
    "source_window_ended_at": null,
    "evidence_links": []
  },
  "source_timeline_import": {
    "provider": "pagerduty",
    "status": "imported"
  },
  "custom_field_values": [
    {
      "id": 1,
      "incident_id": 1,
      "custom_field_id": 50,
      "value": 1500,
      "created_at": "2025-01-30T12:00:00Z",
      "updated_at": "2025-01-30T12:00:00Z"
    }
  ]
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

Endpoint-specific codes: `idempotency_key_reused`, `idempotency_in_progress`, `idempotency_outcome_unknown`

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

#### Related operations

- [List available workflow statuses](https://tellagen.com/api-reference/configuration#configuration-endpoint-get-api-v1-configuration-workflow-statuses) (`GET /api/v1/configuration/workflow-statuses`)
- [List available severities](https://tellagen.com/api-reference/configuration#configuration-endpoint-get-api-v1-configuration-severities) (`GET /api/v1/configuration/severities`)
- [List services](https://tellagen.com/api-reference/services#services-endpoint-get-api-v1-services) (`GET /api/v1/services`)

### `GET /api/v1/incidents/archived`

**List archived incidents.** Returns one page of archived incidents. The default page size is 50, and the maximum is 100. Results are ordered by archived_at and incident ID. The workspace history limit can exclude older incidents.

Required scope: `incidents:read`

Operation ID: `listArchivedIncidents`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Query parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | No | The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. Maximum: 100. Default: 50. |
| `cursor` | `string` | No | The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. Maximum length: 4096 characters. |
| `scope` | `string` | No | Selects all incidents or only postmortems. The default is all. Default: "all". Allowed values: `"all"` \| `"postmortem"` |
| `status` | `string[]` | No | Includes incidents with any supplied workflow status. Repeating status supplies more than one accepted value. |
| `severity` | `string[]` | No | Includes incidents with any supplied severity key. Repeating severity supplies more than one accepted value. |
| `service` | `string[]` | No | Includes incidents with any supplied service slug. Repeating service supplies more than one accepted value. |
| `team_id` | `integer[]` | No | Includes incidents with any supplied owning-team ID. Repeating team_id supplies more than one accepted value. Each ID must be positive. |
| `created_from` | `string (RFC 3339)` | No | Includes incidents created at or after this RFC 3339 timestamp. |
| `created_to` | `string (RFC 3339)` | No | Includes incidents created at or before this RFC 3339 timestamp. |
| `created_before` | `string (RFC 3339)` | No | Includes incidents created strictly before this RFC 3339 timestamp. It cannot be combined with created_to. |
| `region` | `string[]` | No | Includes incidents with any supplied case-insensitive region. Repeating region supplies more than one accepted value. Maximum items: 100. |
| `lifecycle` | `string[]` | No | Includes any supplied incident lifecycle: ticket, incident, postmortem, or alert. Maximum items: 100. Allowed values: `"ticket"` \| `"incident"` \| `"postmortem"` \| `"alert"` |
| `service_tier` | `string[]` | No | Includes incidents whose canonical tenant service has any supplied tier. Maximum items: 100. Allowed values: `"t0"` \| `"t1"` \| `"t2"` \| `"t3"` |
| `effective_team_id` | `integer[]` | No | Includes incidents assigned directly to any supplied team or inheriting it from the canonical service. Repeating the parameter supplies more than one accepted positive ID. Maximum items: 100. |
| `unassigned_team` | `boolean` | No | When true, also includes incidents with no direct or canonical-service team. Default: false. |
| `mine` | `boolean` | No | When true, includes incidents assigned to the authenticated user, or created by that user when no active assignee exists. API-key-only authentication cannot use this filter. Default: false. |
| `active_only` | `boolean` | No | When true, excludes workflow stages configured as terminal. False does not add a status restriction. |
| `status_scope` | `string` | No | Selects all statuses, nonterminal ongoing statuses, or one configured workflow-stage slug. Minimum length: 1 characters. Maximum length: 2048 characters. |
| `diagnosis` | `string[]` | No | Includes incidents in any supplied diagnosis state. Repeating diagnosis supplies more than one accepted value. Maximum items: 100. Allowed values: `"not_run"` \| `"in_progress"` \| `"completed"` \| `"needs_attention"` \| `"unavailable"` |
| `sort` | `string` | No | Selects the collection sort field. Custom requires sort_custom_field. Omission keeps legacy created_at order. Allowed values: `"created_at"` \| `"last_event_at"` \| `"severity"` \| `"service"` \| `"diagnosis"` \| `"case"` \| `"regions"` \| `"team"` \| `"impact"` \| `"status"` \| `"owner"` \| `"events"` \| `"custom"` |
| `direction` | `string` | No | Sort direction for both the selected key and incident-ID tiebreaker. Default: "desc". Allowed values: `"asc"` \| `"desc"` |
| `sort_custom_field` | `string` | No | Active custom-field slug used when sort is custom. The server resolves and validates its stored type. Minimum length: 1 characters. Maximum length: 64 characters. |
| `custom_filter` | `string[]` | No | A JSON object with slug, operator, and value. Repeat for up to 32 predicates. Values remain typed JSON; arrays preserve choices containing commas. Supported operators depend on the resolved field type: string is/is_not/contains/starts_with; select is/is_not; boolean is; number and monetary eq/gt/lt/gte/lte/between; date and datetime is/before/after/between/gte/lte; time is/before/after; multiselect includes_any/includes_all/excludes. SQL fragments and client-supplied field types are rejected. Maximum items: 32. |
| `include_counts` | `boolean` | No | When true, returns authoritative matched, all, ongoing, and per-status counts before cursor and limit. Default: false. |
| `impact_status` | `string[]` | No | Includes incidents with any supplied customer-impact status. Allowed values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `affected_customers_op` | `string` | No | Selects the operator for the affected-customer comparison. This parameter and affected_customers_value must appear together. Allowed values: `"<"` \| `">"` \| `"="` |
| `affected_customers_value` | `integer` | No | The non-negative affected-customer count for comparison. This parameter and affected_customers_op must appear together. Minimum: 0. |
| `mrr_op` | `string` | No | Selects the operator for the MRR comparison. This parameter and mrr_value must appear together. Allowed values: `"<"` \| `">"` \| `"="` |
| `mrr_value` | `integer` | No | The non-negative MRR amount for comparison, in minor currency units. This parameter and mrr_op must appear together. Minimum: 0. |
| `mrr_currency` | `string` | No | A three-letter ISO currency code. If mrr_basis is source, this parameter is required. Pattern: ^[A-Z]{3}$. |
| `mrr_basis` | `string` | No | Selects normalized workspace currency values or original source currency values. The default is normalized. Default: "normalized". Allowed values: `"normalized"` \| `"source"` |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/archived' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incidents` | `object[]` | Always | The incidents in this page. |
| `incidents[].id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incidents[].revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incidents[].company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incidents[].human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incidents[].title` | `string` | Always | The editable display title of the incident. |
| `incidents[].service` | `string` | Always | The service slug associated with the incident. |
| `incidents[].regions` | `string[]` | Always | The affected regions. |
| `incidents[].severity` | `string` | Always | The configured severity key. |
| `incidents[].slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incidents[].meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incidents[].doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incidents[].status` | `string` | Always | The configured workflow-status key. |
| `incidents[].status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incidents[].last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incidents[].last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incidents[].issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incidents[].severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incidents[].impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incidents[].customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incidents[].impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incidents[].first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incidents[].first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incidents[].recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incidents[].duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incidents[].duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incidents[].team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incidents[].event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incidents[].investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incidents[].investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incidents[].investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incidents[].investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incidents[].investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incidents[].investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incidents[].created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incidents[].created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incidents[].custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incidents[].archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incidents[].archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incidents[].incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incidents[].incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incidents[].has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `has_more` | `boolean` | Always | Deprecated top-level alias for pagination.has_more. |
| `next_cursor` | `string` | Optional | Deprecated top-level alias for pagination.next_cursor. |
| `pagination` | `object` | Always | Pagination details for a collection response. |
| `pagination.limit` | `integer` | Always | The maximum number of items requested for this page. Minimum: 1. Maximum: 100. |
| `pagination.has_more` | `boolean` | Always | Indicates whether another page is available. |
| `pagination.next_cursor` | `string` | Optional | The opaque cursor for the next page. This field is absent on the final page. |
| `restricted_count` | `integer` | Optional | The number of matching incidents excluded by the workspace history limit. Minimum: 0. |
| `history_limited` | `boolean` | Optional | Indicates whether the workspace history limit applies to this response. |
| `mrr_currency` | `string` | Optional | The workspace reporting currency used for normalized MRR values. |
| `mrr_conversion_mode` | `string` | Optional | The workspace mode for MRR currency conversion. Possible values: `"normalized"` \| `"source_only"` |
| `mrr_projection_state` | `string` | Optional | The MRR projection state. Possible values: `"ready"` \| `"stale"` \| `"unavailable"` |
| `supported_mrr_currencies` | `string[]` | Optional | The ISO currency codes supported by MRR filters. |
| `collection_counts` | `object` | Optional | Complete collection counts before cursor and limit when include_counts is true. |
| `collection_counts.matched` | `integer` | Always | Count after every predicate, including status selection. Minimum: 0. |
| `collection_counts.all` | `integer` | Always | Count after non-status predicates, excluding status, status_scope, and active_only. Minimum: 0. |
| `collection_counts.ongoing` | `integer` | Always | Nonterminal count after non-status predicates. Minimum: 0. |
| `collection_counts.by_status` | `object` | Always | Exact counts by normalized stored status after non-status predicates. |

Returns archived incidents, pagination fields, and workspace history-limit details. The filters also apply to restricted_count.

```json
{
  "incidents": [
    {
      "id": 1,
      "revision": 7,
      "company_id": 7,
      "human_id": "INC-2025-001",
      "title": "Payments API requests timing out",
      "service": "payments",
      "regions": [
        "us-east-1"
      ],
      "severity": "sev1",
      "slack_channel_id": "C08ABC123",
      "meet_url": "https://meet.google.com/abc-defg-hij",
      "doc_url": "https://docs.google.com/d/1abc",
      "status": "active",
      "status_changed_at": "2025-01-30T12:05:00Z",
      "last_event_at": "2025-01-30T12:10:00Z",
      "last_event_summary": "Investigating root cause",
      "issue_type": "incident",
      "severity_mode": "manual",
      "impact_summary": "Payment processing delayed for EU customers",
      "customer_impact_status": "confirmed",
      "impact_started_at": "2025-01-30T11:55:00Z",
      "first_reported_at": "2025-01-30T11:58:00Z",
      "first_responded_at": "2025-01-30T12:00:00Z",
      "recovered_at": null,
      "duration_seconds": 900,
      "duration_anchor": "impact_started_at",
      "team_id": 42,
      "event_count": 5,
      "investigation_summary": null,
      "created_at": "2025-01-30T12:00:00Z",
      "created_by": "oncall@example.com",
      "custom_fields": {},
      "archived_at": "2025-02-07T09:30:00Z",
      "archived_by": 42,
      "incident_manager": "oncall@example.com",
      "incident_responders": [
        "responder@example.com"
      ],
      "has_assignees": true
    }
  ],
  "restricted_count": 3,
  "history_limited": true,
  "has_more": false,
  "pagination": {
    "limit": 50,
    "has_more": false
  }
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `GET /api/v1/incident-references/{reference}`

**Get incident by permanent reference.** Returns an incident from its permanent, opaque reference. This endpoint is suitable for stored references and links in other systems. The numeric-ID endpoint accepts only a positive ID returned by this API.

Required scope: `incidents:read`

Operation ID: `getIncidentByReference`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | `string` | Yes | A permanent, opaque reference from Tellagen incident links and messages. This parameter does not accept a numeric incident ID. Minimum length: 1 characters. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/incident-references/{reference}' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete incident record. The reference continues to identify the same incident after editable fields change.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "active",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "Payment processing delayed for EU customers",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": null,
    "duration_seconds": 900,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

#### Related operations

- [Get incident](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incidents-id) (`GET /api/v1/incidents/{id}`)

### `GET /api/v1/incidents/{id}`

**Get incident.** Returns one incident by its positive numeric ID. The permanent-reference endpoint is suitable for stored references, external links, and workflows in other systems.

Required scope: `incidents:read`

Operation ID: `getIncident`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete incident record. Nullable timestamps, team details, archive details, and investigation_summary are always present. These fields can be null. Arrays and custom_fields are never null.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "active",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "Payment processing delayed for EU customers",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": null,
    "duration_seconds": 900,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

#### Related operations

- [Get incident by permanent reference](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incident-references-reference) (`GET /api/v1/incident-references/{reference}`)

### `PATCH /api/v1/incidents/{id}`

**Update incident.** Updates the supplied incident fields and returns the complete incident. Omitted fields stay unchanged. Unknown fields return 400. API v1 accepts status changes through this operation for compatibility. New clients must use the resolve, close, and reopen operations. The API validates submitted timestamps against each other and stored timestamps. Automatic severity can recalculate after relevant field changes.

Required scope: `incidents:write`

Operation ID: `updateIncident`
Contract: `supported`
Retry guidance: Read the current resource and reconcile changes before retrying with its current version. A stale version returns 412.
Prerequisites: Active responder seat, Incident is not archived

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Request headers

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `If-Tellagen-Resource-Version` | `integer` | Yes | The current positive resource version from the latest response. API-key PATCH requests must send this value. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

Use the Tellagen-Resource-Version header from a GET of this resource for `<resource-version>`.

```bash
curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'If-Tellagen-Resource-Version: <resource-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Payments API recovered; monitoring authorization backlog",
  "impact_summary": "Full payment outage in EU region"
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | No | The incident display title. The maximum length is 160 characters. This field is separate from impact_summary. Maximum length: 160 characters. |
| `service` | `string` | No | The service slug. The maximum length is 128 characters. Maximum length: 128 characters. |
| `regions` | `string[]` | No | The complete replacement list of affected regions. An empty array removes all regions. |
| `severity` | `string` | No | A severity key from the workspace configuration. |
| `slack_channel_id` | `string` | No | The stored Slack channel ID. |
| `meet_url` | `string` | No | The absolute HTTP or HTTPS meeting URL. |
| `doc_url` | `string` | No | An absolute HTTP or HTTPS URL for an incident document or source. |
| `status` | `string` | No | A workflow-status key from the workspace configuration. New clients use the resolve, close, and reopen operations for lifecycle changes. |
| `issue_type` | `string` | No | The work type. Existing alert records remain available for compatibility. Allowed values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `team_id` | `integer \| null` | No | The positive ID of an active owning team. A null value removes the current team assignment. |
| `severity_mode` | `string` | No | The severity selection mode. Allowed values: `"auto"` \| `"manual"` |
| `impact_summary` | `string` | No | The customer or operational impact summary. |
| `customer_impact_status` | `string` | No | The customer-impact assessment. Allowed values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `impact_started_at` | `string (RFC 3339)` | No | The RFC 3339 impact start time. |
| `first_reported_at` | `string (RFC 3339)` | No | The RFC 3339 time of the first incident report. |
| `first_responded_at` | `string (RFC 3339)` | No | The RFC 3339 time of the first response. |
| `recovered_at` | `string (RFC 3339)` | No | The RFC 3339 service recovery time. |

Request JSON:

```json
{
  "title": "Payments API recovered; monitoring authorization backlog",
  "impact_summary": "Full payment outage in EU region"
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete updated incident. A transition to resolved changes issue_type to postmortem. A transition from resolved to active changes issue_type to incident.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API recovered; monitoring authorization backlog",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "active",
    "status_changed_at": "2025-01-30T12:00:00Z",
    "last_event_at": "2025-01-30T13:30:00Z",
    "last_event_summary": "Service fully recovered",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "Full payment outage in EU region",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": "2025-01-30T13:30:00Z",
    "duration_seconds": 5700,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 12,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `412` | The resource changed after the client obtained its If-Tellagen-Resource-Version value. |
| `428` | An API-key PATCH request did not include the required If-Tellagen-Resource-Version header. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

#### Related operations

- [Resolve incident](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-resolve) (`POST /api/v1/incidents/{id}/resolve`)
- [Close incident without resolution](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-close) (`POST /api/v1/incidents/{id}/close`)
- [Reopen incident](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-reopen) (`POST /api/v1/incidents/{id}/reopen`)

### `POST /api/v1/incidents/{id}/resolve`

**Resolve incident.** Changes an incident to resolved and changes issue_type to postmortem. The API saves the status, optional recovery edit, and resolution note in a lifecycle event atomically. Existing postmortem drafts and versions remain unchanged. The request body is optional. A stale expected_revision returns 412. An already-resolved incident accepts an empty retry without creating another event; a retry with a note or recovery edit returns 412.

Required scope: `incidents:write`

Operation ID: `resolveIncident`
Contract: `supported`
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance.
Prerequisites: Active responder seat, Incident is not archived

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/resolve' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "resolution_note": "Rolled back the deployment and verified payment processing.",
  "recovered_at": "2025-01-30T12:04:00Z",
  "expected_revision": 6
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `resolution_note` | `string` | No | An optional note stored in the resolution timeline event. Leading and trailing whitespace is removed before enforcing the 1000 Unicode character limit. |
| `recovered_at` | `string` | No | The recovery timestamp in RFC 3339 format. Omit to preserve the current value. An empty string clears it. The timestamp must follow recorded impact, report, and response times and must not be in the future. |
| `expected_revision` | `integer` | No | The incident revision displayed to the responder. A mismatch returns 412 without saving any changes. |

Request JSON:

```json
{
  "resolution_note": "Rolled back the deployment and verified payment processing.",
  "recovered_at": "2025-01-30T12:04:00Z",
  "expected_revision": 6
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete incident and the committed resolution timeline event.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "resolved",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "issue_type": "postmortem",
    "severity_mode": "manual",
    "impact_summary": "Payment processing delayed for EU customers",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": "2025-01-30T13:30:00Z",
    "duration_seconds": 900,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/close`

**Close incident without resolution.** Closes an incident from a non-terminal workflow status without marking it resolved. The API records the reason and comment in a lifecycle event.

Required scope: `incidents:write`

Operation ID: `closeIncident`
Contract: `supported`
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance.
Prerequisites: Active responder seat, Incident is not archived

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/close' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "duplicate",
  "comment": "Tracked by the primary payment incident.",
  "related_incident_id": 99
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | `string` | Yes | The closure reason. Allowed values: `"duplicate"` \| `"false_alarm"` \| `"test_or_accidental"` \| `"not_an_incident"` \| `"other"` |
| `comment` | `string` | Yes | The explanation for the closure. The maximum length is 1000 characters. Minimum length: 1 characters. Maximum length: 1000 characters. |
| `related_incident_id` | `integer` | Conditional | The positive ID of the primary incident. If reason is duplicate, this field is required. Required when: Required when reason is "duplicate". Minimum: 1. |

Request JSON:

```json
{
  "reason": "duplicate",
  "comment": "Tracked by the primary payment incident.",
  "related_incident_id": 99
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete incident after closure.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "closed",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "Payment processing delayed for EU customers",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": null,
    "duration_seconds": 900,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/reopen`

**Reopen incident.** Changes a resolved or closed incident to active. A closed incident requires a comment. A comment is optional for a resolved incident. If issue_type is postmortem, the API changes it to incident.

Required scope: `incidents:write`

Operation ID: `reopenIncident`
Contract: `supported`
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance.
Prerequisites: Active responder seat, Incident is not archived

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/reopen' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "comment": "Customer-visible errors returned."
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | `string` | Conditional | The reason for reopening. A closed incident requires this field. The maximum length is 500 characters. Required when: Required when reopening a closed incident. Maximum length: 500 characters. |

Request JSON:

```json
{
  "comment": "Customer-visible errors returned."
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete incident after it becomes active.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "active",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "Payment processing delayed for EU customers",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": null,
    "duration_seconds": 900,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `GET /api/v1/incidents/{id}/provisioning`

**Get incident integration setup.** Returns durable integration setup state. Pending work resumes after a server restart. Failed work retries automatically. Completed means all persisted setup steps finished.

Required scope: `incidents:read`

Operation ID: `getIncidentProvisioning`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/provisioning' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `status` | `string` | Always | Aggregate state of persisted incident integration steps. Possible values: `"pending"` \| `"failed"` \| `"completed"` |
| `retryable` | `boolean` | Always | True when a failed step can be made eligible for immediate retry. |

Current setup state. Retryable indicates whether failed steps can be retried manually.

```json
{
  "status": "pending",
  "retryable": false
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/provisioning/retry`

**Retry incident integration setup.** Makes failed setup steps eligible to run again. Completed steps and incident history are not repeated. The caller must have an active responder seat. Demo workspaces cannot retry external setup.

Required scope: `incidents:write`

Operation ID: `retryIncidentProvisioning`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: Active responder seat

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/provisioning/retry' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `status` | `string` | Always | Aggregate state of persisted incident integration steps. Possible values: `"pending"` \| `"failed"` \| `"completed"` |
| `retryable` | `boolean` | Always | True when a failed step can be made eligible for immediate retry. |

Current setup state. Retryable indicates whether failed steps can be retried manually.

```json
{
  "status": "pending",
  "retryable": false
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/archive`

**Archive incident.** The caller must have an active responder seat. Archiving removes the incident from default lists without changing its workflow status. A repeated request returns 204 without changing archive details, revision, changelog, or audit records. The API retains incident child records as read-only data.

Required scope: `incidents:write`

Operation ID: `archiveIncident`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: Active responder seat

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/archive' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `204 No Content`

No response body.

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/restore`

**Restore incident.** The caller must have an active responder seat. Restoring returns an archived incident to default lists without changing its workflow status. A repeated request returns the active incident without changing its revision, changelog, or audit records. If the incident has team_id, that team must be active.

Required scope: `incidents:write`

Operation ID: `restoreIncident`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: Active responder seat

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/restore' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `incident` | `object` | Always | The complete public record for an incident. |
| `incident.id` | `integer` | Always | The positive numeric ID of the incident. Minimum: 1. |
| `incident.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `incident.company_id` | `integer` | Always | The ID of the workspace that owns the incident. Minimum: 1. |
| `incident.human_id` | `string` | Always | The permanent incident reference shown to users. |
| `incident.title` | `string` | Always | The editable display title of the incident. |
| `incident.service` | `string` | Always | The service slug associated with the incident. |
| `incident.regions` | `string[]` | Always | The affected regions. |
| `incident.severity` | `string` | Always | The configured severity key. |
| `incident.slack_channel_id` | `string` | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
| `incident.meet_url` | `string` | Always | The incident meeting URL. An empty string means that no meeting is linked. |
| `incident.doc_url` | `string` | Always | The incident document or source URL. An empty string means that no URL is stored. |
| `incident.status` | `string` | Always | The configured workflow-status key. |
| `incident.status_changed_at` | `string (RFC 3339) \| null` | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
| `incident.last_event_at` | `string (RFC 3339) \| null` | Always | The start time of the latest timeline event. A null value means that no event exists. |
| `incident.last_event_summary` | `string` | Always | A summary of the latest timeline event. |
| `incident.issue_type` | `string` | Always | The work type. Possible values: `"ticket"` \| `"incident"` \| `"postmortem"` |
| `incident.severity_mode` | `string` | Always | The severity selection mode. Possible values: `"auto"` \| `"manual"` |
| `incident.impact_summary` | `string` | Always | The current customer or operational impact summary. |
| `incident.customer_impact_status` | `string` | Always | The customer-impact assessment. Possible values: `"unknown"` \| `"none"` \| `"confirmed"` |
| `incident.impact_started_at` | `string (RFC 3339) \| null` | Always | The impact start time. A null value means that the time is unknown. |
| `incident.first_reported_at` | `string (RFC 3339) \| null` | Always | The time of the first incident report. A null value means that the time is unknown. |
| `incident.first_responded_at` | `string (RFC 3339) \| null` | Always | The time of the first response. A null value means that the time is unknown. |
| `incident.recovered_at` | `string (RFC 3339) \| null` | Always | The service recovery time. A null value means that recovery is not recorded. |
| `incident.duration_seconds` | `integer` | Always | The calculated incident duration in whole seconds. Minimum: 0. |
| `incident.duration_anchor` | `string` | Always | The timestamp field from which the API calculates duration. |
| `incident.team_id` | `integer \| null` | Always | The owning-team ID. A null value means that the incident has no owning team. |
| `incident.event_count` | `integer` | Always | The number of timeline events for the incident. Minimum: 0. |
| `incident.investigation_summary` | `object \| null` | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.run_count` | `integer` | Always | The total number of investigation runs. Minimum: 0. |
| `incident.investigation_summary.latest_run` | `object \| null` | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
| `incident.investigation_summary.latest_run.status` | `string` | Always | The current investigation-run status. |
| `incident.investigation_summary.latest_run.started_at` | `string (RFC 3339)` | Always | The investigation-run start time. |
| `incident.investigation_summary.latest_run.completed_at` | `string (RFC 3339)` | Optional | The investigation-run completion time. |
| `incident.created_at` | `string (RFC 3339)` | Always | The incident creation time. |
| `incident.created_by` | `string` | Always | The identifier of the user who created the incident. |
| `incident.custom_fields` | `object` | Always | The incident values keyed by custom-field slug. |
| `incident.archived_at` | `string (RFC 3339) \| null` | Always | The incident archive time. A null value means that the incident is active. |
| `incident.archived_by` | `integer \| null` | Always | The user ID that archived the incident. A null value means that the incident is active. |
| `incident.incident_manager` | `string` | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
| `incident.incident_responders` | `string[]` | Always | The user identifiers of assigned responders. |
| `incident.has_assignees` | `boolean` | Always | Indicates whether the incident has a manager or at least one responder. |
| `timeline_event` | `object` | Optional | The complete public record for a timeline event. |
| `timeline_event.id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.revision` | `integer` | Always | The resource version for concurrency control. Minimum: 1. |
| `timeline_event.incident_id` | `integer` | Always | The positive numeric ID of the incident. |
| `timeline_event.started_at` | `string (RFC 3339)` | Always | The event start time. |
| `timeline_event.at` | `string (RFC 3339)` | Always | A deprecated response alias for started_at. Both fields contain the same value. |
| `timeline_event.ended_at` | `string (RFC 3339) \| null` | Always | The event end time. A null value means that the event has no end time. |
| `timeline_event.is_ongoing` | `boolean` | Always | Indicates whether the event is still in progress. |
| `timeline_event.group_id` | `integer \| null` | Always | The timeline-group ID. A null value means that the event has no group. |
| `timeline_event.is_key` | `boolean` | Always | Indicates whether responders marked this as a key incident event. |
| `timeline_event.source` | `string` | Always | The system or actor that created the event. |
| `timeline_event.source_ref` | `string` | Always | The source-specific reference for the event. |
| `timeline_event.type` | `string` | Always | The event type used for grouping and display. |
| `timeline_event.icon` | `string` | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
| `timeline_event.title` | `string` | Always | The optional display title of the event. |
| `timeline_event.body` | `string` | Always | The event description. |
| `timeline_event.collaboration_generation` | `integer` | Always | The version of collaborative content associated with the event. |
| `timeline_event.tags` | `string[]` | Always | The normalized event tags. |
| `timeline_event.ai_context` | `string` | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
| `timeline_event.created_by` | `string` | Always | The identifier of the user or system that created the event. |
| `timeline_event.comment_count` | `integer` | Always | The number of comments on the event. |
| `timeline_event.attachments` | `object[]` | Always | The files attached to the event. |
| `timeline_event.attachments[].id` | `integer` | Always | The positive numeric ID of the attachment. |
| `timeline_event.attachments[].timeline_event_id` | `integer` | Always | The positive numeric ID of the timeline event. |
| `timeline_event.attachments[].filename` | `string` | Always | The original file name. |
| `timeline_event.attachments[].url` | `string` | Always | A temporary download URL. An empty string means that no URL is currently available. |
| `timeline_event.attachments[].url_available` | `boolean` | Always | Indicates whether url contains an available download URL. |
| `timeline_event.attachments[].content_type` | `string` | Always | The media type of the attached file. |
| `timeline_event.attachments[].size_bytes` | `integer` | Always | The file size in bytes. |
| `timeline_event.attachments[].created_at` | `string (RFC 3339)` | Always | The attachment creation time. |
| `timeline_event.attachments[].created_by` | `string` | Always | The identifier of the user who attached the file. |
| `timeline_event.source_window_started_at` | `string (RFC 3339) \| null` | Always | The start of the source-data window. A null value means that no window is recorded. |
| `timeline_event.source_window_ended_at` | `string (RFC 3339) \| null` | Always | The end of the source-data window. A null value means that no window is recorded. |
| `timeline_event.evidence_links` | `object[]` | Always | The evidence references associated with the event. |
| `timeline_event.evidence_links[].source` | `string` | Always | The system or provider that supplied the evidence. |
| `timeline_event.evidence_links[].url` | `string` | Always | The absolute URL of the evidence. |
| `timeline_event.evidence_links[].label` | `string` | Optional | A short display name for the evidence. |
| `timeline_event.evidence_links[].summary` | `string` | Optional | A short summary of the evidence. |
| `timeline_event.evidence_links[].artifact_id` | `string` | Optional | The identifier of a stored evidence artifact. |
| `timeline_event.evidence_links[].artifact_digest` | `string` | Optional | The digest used to make sure that the artifact content did not change. |
| `timeline_event.evidence_links[].result_bytes` | `integer` | Optional | The original evidence result size in bytes. |
| `timeline_event.evidence_links[].truncated` | `boolean` | Optional | Indicates whether the stored evidence omits part of the original result. |

Returns the complete active incident. If its saved team is not active, the API returns 409 invalid_relationship_state.

```json
{
  "incident": {
    "id": 1,
    "revision": 7,
    "company_id": 7,
    "human_id": "INC-2025-001",
    "title": "Payments API requests timing out",
    "service": "payments",
    "regions": [
      "us-east-1"
    ],
    "severity": "sev1",
    "slack_channel_id": "C08ABC123",
    "meet_url": "https://meet.google.com/abc-defg-hij",
    "doc_url": "https://docs.google.com/d/1abc",
    "status": "active",
    "status_changed_at": "2025-01-30T12:05:00Z",
    "last_event_at": "2025-01-30T12:10:00Z",
    "last_event_summary": "Investigating root cause",
    "issue_type": "incident",
    "severity_mode": "manual",
    "impact_summary": "Payment processing delayed for EU customers",
    "customer_impact_status": "confirmed",
    "impact_started_at": "2025-01-30T11:55:00Z",
    "first_reported_at": "2025-01-30T11:58:00Z",
    "first_responded_at": "2025-01-30T12:00:00Z",
    "recovered_at": null,
    "duration_seconds": 900,
    "duration_anchor": "impact_started_at",
    "team_id": 42,
    "event_count": 5,
    "investigation_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "oncall@example.com",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "oncall@example.com",
    "incident_responders": [
      "responder@example.com"
    ],
    "has_assignees": true
  }
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Tellagen-Resource-Version` | `integer` | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |

#### Endpoint error responses

Endpoint-specific codes: `invalid_relationship_state`

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/rename-slack-channel`

**Reapply the Slack channel-name template (deprecated).** This operation is deprecated. It reapplies the workspace channel-name template. It rejects every request body, including whitespace. The replacement is PATCH /api/v1/incidents/{id}/slack/channel-name with mode workspace_template. Every response includes the RFC 9745 Deprecation date and a link to the replacement operation. The Sunset header is absent because Tellagen has not set an end date.

Required scope: `incidents:write`

Operation ID: `syncIncidentSlackChannelName`
Contract: `supported`
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance.
Prerequisites: Active responder seat, Incident is not archived, Linked Slack channel

**Deprecated.**
Announced: `2026-08-31`. Sunset review: `2027-03-01`.
Successor: `PATCH /api/v1/incidents/{id}/slack/channel-name`

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/rename-slack-channel' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `channel_name` | `string` | Always | The new Slack channel name. |

Returns the new Slack channel name.

```json
{
  "channel_name": "inc-2025-001-payments"
}
```

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `Deprecation` | `string` | Always | The date of the deprecation announcement in RFC 9745 format. Pattern: ^@[0-9]+$. |
| `Link` | `string` | Always | A link to the replacement operation with rel="successor-version". |

#### Endpoint error responses

Endpoint-specific codes: `invalid_slack_channel_name_request`, `slack_not_configured`, `incident_slack_channel_missing`, `slack_channel_not_found`, `slack_channel_name_taken`, `invalid_resource_state`

| Status | Meaning |
| --- | --- |
| `400` | The compatibility action received a non-empty request body. |
| `401` | Authentication failed. |
| `403` | The API key lacks access or an active responder seat. |
| `404` | The incident does not exist. |
| `409` | Slack is not configured, the linked channel is missing, the incident is immutable, or the resolved name is already used. |
| `429` | The workspace rate limit is exceeded. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/incidents/{id}/slack/channel-name/preview`

**Preview an incident Slack channel name.** Calculates and validates the channel name without renaming the Slack channel or creating an audit record. The workspace_template mode must omit name. The custom mode requires name.

Required scope: `incidents:write`

Operation ID: `previewIncidentSlackChannelName`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: Active responder seat, Incident is not archived, Linked Slack channel

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/slack/channel-name/preview' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "mode": "custom",
  "name": "Payments War Room"
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `string` | Yes | Selects how the API creates the Slack channel name. Must match exactly one of 2 schema variants. Allowed values: `"workspace_template"` \| `"custom"` |
| `name` | `string` | Conditional | The proposed channel name for custom mode. It must contain an ASCII letter or digit. The preview and update operations normalize it identically. Required when: Required when mode is "custom". Minimum length: 1 characters. Pattern: .*[A-Za-z0-9].*. |

Request JSON:

```json
{
  "mode": "custom",
  "name": "Payments War Room"
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `channel_id` | `string` | Always | The Slack channel ID. |
| `previous_name` | `string` | Always | The channel name before the request. |
| `new_name` | `string` | Always | The validated channel name. The maximum length is 80 characters. Minimum length: 1 characters. Maximum length: 80 characters. |
| `mode` | `string` | Always | The naming mode. Possible values: `"workspace_template"` \| `"custom"` |

Returns the current and proposed channel names. A 409 response uses slack_not_configured, incident_slack_channel_missing, slack_channel_not_found, or slack_channel_name_taken.

```json
{
  "channel_id": "C08ABC123",
  "previous_name": "inc-2025-001-payments",
  "new_name": "payments-war-room",
  "mode": "custom"
}
```

#### Endpoint error responses

Endpoint-specific codes: `invalid_slack_channel_name_request`, `slack_not_configured`, `incident_slack_channel_missing`, `slack_channel_not_found`, `slack_channel_name_taken`, `invalid_resource_state`

| Status | Meaning |
| --- | --- |
| `400` | The naming request is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | Slack is not configured, the linked channel is missing, or the resolved name is already used. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

#### Related operations

- [Update an incident Slack channel name](https://tellagen.com/api-reference/incidents#incidents-endpoint-patch-api-v1-incidents-id-slack-channel-name) (`PATCH /api/v1/incidents/{id}/slack/channel-name`)

### `PATCH /api/v1/incidents/{id}/slack/channel-name`

**Update an incident Slack channel name.** Renames the linked Slack channel with workspace_template or custom mode. The API saves the old name, new name, mode, actor, and time in the incident audit log. It also publishes the saved audit entry as an incident event. If the audit save fails after Slack renames the channel, the API tries to restore the old name and returns an error.

Required scope: `incidents:write`

Operation ID: `updateIncidentSlackChannelName`
Contract: `supported`
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance.
Prerequisites: Active responder seat, Incident is not archived, Linked Slack channel

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer` | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/slack/channel-name' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "mode": "custom",
  "name": "Payments War Room"
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | `string` | Yes | Selects how the API creates the Slack channel name. Must match exactly one of 2 schema variants. Allowed values: `"workspace_template"` \| `"custom"` |
| `name` | `string` | Conditional | The proposed channel name for custom mode. It must contain an ASCII letter or digit. The preview and update operations normalize it identically. Required when: Required when mode is "custom". Minimum length: 1 characters. Pattern: .*[A-Za-z0-9].*. |

Request JSON:

```json
{
  "mode": "custom",
  "name": "Payments War Room"
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `channel_id` | `string` | Always | The Slack channel ID. |
| `previous_name` | `string` | Always | The channel name before the request. |
| `new_name` | `string` | Always | The validated channel name. The maximum length is 80 characters. Minimum length: 1 characters. Maximum length: 80 characters. |
| `mode` | `string` | Always | The naming mode. Possible values: `"workspace_template"` \| `"custom"` |

Returns the renamed channel. The preview operation validates the same request without changing the channel. A 409 response uses slack_not_configured, incident_slack_channel_missing, slack_channel_not_found, or slack_channel_name_taken.

```json
{
  "channel_id": "C08ABC123",
  "previous_name": "inc-2025-001-payments",
  "new_name": "payments-war-room",
  "mode": "custom"
}
```

#### Endpoint error responses

Endpoint-specific codes: `invalid_slack_channel_name_request`, `slack_not_configured`, `incident_slack_channel_missing`, `slack_channel_not_found`, `slack_channel_name_taken`, `invalid_resource_state`

| Status | Meaning |
| --- | --- |
| `400` | The naming request is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | Slack is not configured, the linked channel is missing, or the resolved name is already used. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

#### Related operations

- [Preview an incident Slack channel name](https://tellagen.com/api-reference/incidents#incidents-endpoint-post-api-v1-incidents-id-slack-channel-name-preview) (`POST /api/v1/incidents/{id}/slack/channel-name/preview`)