API ReferenceIncidents

Incidents

Create incidents from alerts, record their progress, and resolve them after recovery.

Search API docsAll documentation

Search all guides and API reference text. Method and scope filter endpoints only.

MethodScope

Endpoints

List incidents

GET/api/v1/incidents

Lists incidents that are not archived, newest first by default. The default page size is 50. The maximum is 100.

Repeated values for one filter match either value. Different filters must all match. Filters also apply to restricted_count.

Use the returned cursor with the same filters and sort order. Changes between requests can move incidents between pages.

Required scope: incidents:read

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: 200

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.

Success response JSON

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,
      "status_update_summary": {
        "latest_recorded_at": "2025-01-30T12:05:00Z",
        "next_update_at": "2025-01-30T12:35:00Z",
        "latest_excerpt": "Rolling back the payments deploy"
      },
      "postmortem_summary": {
        "has_work": false,
        "has_working_draft": false,
        "latest_version_id": null,
        "latest_version_kind": null,
        "work_state": "none"
      },
      "created_at": "2025-01-30T12:00:00Z",
      "created_by": "[email protected]",
      "custom_fields": {},
      "archived_at": null,
      "archived_by": null,
      "incident_manager": "[email protected]",
      "incident_responders": [
        "[email protected]"
      ],
      "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
    }
  }
}

Parameters, headers, and fields

Operation ID: listIncidents

Query parameters

Query parameters
Field	Description
`limit` integer Optional	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 Optional	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 Optional	Selects all incidents or only postmortems. The default is all. With scope=postmortem, incidents whose postmortem work is missing or in review are listed even when they are older than the workspace history limit, and restricted_count counts only the incidents still hidden. Default: "all". Allowed values: `"all""postmortem"`
`status` string[] Optional	Includes incidents with any supplied workflow status. Repeating status supplies more than one accepted value.
`severity` string[] Optional	Includes incidents with any supplied severity key. Repeating severity supplies more than one accepted value.
`service` string[] Optional	Includes incidents with any supplied service slug. Repeating service supplies more than one accepted value.
`team_id` integer[] Optional	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) Optional	Includes incidents created at or after this RFC 3339 timestamp.
`created_to` string (RFC 3339) Optional	Includes incidents created at or before this RFC 3339 timestamp.
`created_before` string (RFC 3339) Optional	Includes incidents created strictly before this RFC 3339 timestamp. It cannot be combined with created_to.
`region` string[] Optional	Includes incidents with any supplied case-insensitive region. Repeating region supplies more than one accepted value. Maximum items: 100.
`lifecycle` string[] Optional	Includes any supplied incident lifecycle: ticket, incident, postmortem, or alert. Maximum items: 100. Allowed values: `"ticket""incident""postmortem""alert"`
`service_tier` string[] Optional	Includes incidents whose canonical tenant service has any supplied tier. Maximum items: 100. Allowed values: `"t0""t1""t2""t3"`
`effective_team_id` integer[] Optional	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 Optional	When true, also includes incidents with no direct or canonical-service team. Default: false.
`mine` boolean Optional	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 Optional	When true, excludes workflow stages configured as terminal. False does not add a status restriction.
`status_scope` string Optional	Selects all statuses, nonterminal ongoing statuses, or one configured workflow-stage slug. Minimum length: 1 characters. · Maximum length: 2048 characters.
`diagnosis` string[] Optional	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 Optional	Selects the collection sort field. Custom requires sort_custom_field. Owner orders by the active incident manager's email; incidents without an incident manager sort last in both directions. Signal orders by priority, with active incidents before resolved ones, then severity rank in the active severity catalog, then latest activity; it defaults to direction=asc, most urgent first. Omission keeps legacy created_at order. Allowed values: `"created_at""last_event_at""severity""service""diagnosis""case""regions""team""impact""status""owner""events""custom""signal"`
`direction` string Optional	Sort direction for both the selected key and incident-ID tiebreaker. Defaults to desc, except asc when sort is signal. Default: "desc". Allowed values: `"asc""desc"`
`sort_custom_field` string Optional	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[] Optional	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 Optional	When true, returns authoritative matched, all, ongoing, and per-status counts before cursor and limit. Default: false.
`impact_status` string[] Optional	Includes incidents with any supplied customer-impact status. Allowed values: `"unknown""none""confirmed"`
`affected_customers_op` string Optional	Selects the operator for the affected-customer comparison. This parameter and affected_customers_value must appear together. Allowed values: `"<"">""="`
`affected_customers_value` integer Optional	The non-negative affected-customer count for comparison. This parameter and affected_customers_op must appear together. Minimum: 0.
`mrr_op` string Optional	Selects the operator for the MRR comparison. This parameter and mrr_value must appear together. Allowed values: `"<"">""="`
`mrr_value` integer Optional	The non-negative MRR amount for comparison, in minor currency units. This parameter and mrr_op must appear together. Minimum: 0.
`mrr_currency` string Optional	A three-letter ISO currency code. If mrr_basis is source, this parameter is required. Pattern: ^[A-Z]{3}$.
`mrr_basis` string Optional	Selects normalized workspace currency values or original source currency values. The default is normalized. Default: "normalized". Allowed values: `"normalized""source"`

Response `200`

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incidents` object[] Always returned	The incidents in this page.
`incidents[].id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incidents[].revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incidents[].company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incidents[].human_id` string Always returned	The permanent incident reference shown to users.
`incidents[].title` string Always returned	The editable display title of the incident.
`incidents[].service` string Always returned	The service slug associated with the incident.
`incidents[].regions` string[] Always returned	The affected regions.
`incidents[].severity` string Always returned	The configured severity key.
`incidents[].slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incidents[].meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incidents[].doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incidents[].status` string Always returned	The configured workflow-status key.
`incidents[].status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incidents[].last_event_summary` string Always returned	A summary of the latest timeline event.
`incidents[].issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incidents[].severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incidents[].impact_summary` string Always returned	The current customer or operational impact summary.
`incidents[].customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incidents[].impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incidents[].first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incidents[].recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incidents[].duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incidents[].duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incidents[].team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incidents[].event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incidents[].investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incidents[].investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incidents[].investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incidents[].investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incidents[].status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incidents[].status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incidents[].status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incidents[].status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incidents[].status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incidents[].status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incidents[].postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incidents[].postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incidents[].postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incidents[].postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incidents[].postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incidents[].postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incidents[].created_at` string (RFC 3339) Always returned	The incident creation time.
`incidents[].created_by` string Always returned	The identifier of the user who created the incident.
`incidents[].custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incidents[].archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incidents[].archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incidents[].incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incidents[].incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incidents[].has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`has_more` boolean Always returned	Deprecated top-level alias for pagination.has_more.
`next_cursor` string Sometimes returned	Deprecated top-level alias for pagination.next_cursor.
`pagination` object Always returned	Pagination details for a collection response.
`pagination.limit` integer Always returned	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more` boolean Always returned	Indicates whether another page is available.
`pagination.next_cursor` string Sometimes returned	The opaque cursor for the next page. This field is absent on the final page.
`restricted_count` integer Sometimes returned	The number of matching incidents excluded by the workspace history limit. Minimum: 0.
`history_limited` boolean Sometimes returned	Indicates whether the workspace history limit applies to this response.
`mrr_currency` string Sometimes returned	The workspace reporting currency used for normalized MRR values.
`mrr_conversion_mode` string Sometimes returned	The workspace mode for MRR currency conversion. Possible values: `"normalized""source_only"`
`mrr_projection_state` string Sometimes returned	The MRR projection state. Possible values: `"ready""stale""unavailable"`
`supported_mrr_currencies` string[] Sometimes returned	The ISO currency codes supported by MRR filters.
`collection_counts` object Sometimes returned	Complete collection counts before cursor and limit when include_counts is true.
`collection_counts.matched` integer Always returned	Count after every predicate, including status selection. Minimum: 0.
`collection_counts.all` integer Always returned	Count after non-status predicates, excluding status, status_scope, and active_only. Minimum: 0.
`collection_counts.ongoing` integer Always returned	Nonterminal count after non-status predicates. Minimum: 0.
`collection_counts.by_status` object Always returned	Exact counts by normalized stored status after non-status predicates.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Create incident

POST/api/v1/incidents

Creates an incident from an alert or another tool. The API validates all fields before it saves the incident and its declaration event.

If Slack is configured and create_slack_channel is true, Tellagen creates the channel after it saves the incident. The getIncidentProvisioning endpoint shows progress. The retryIncidentProvisioning endpoint retries failed steps.

Required scope: incidents:write

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
}'

Success: 201

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.

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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"
    }
  ]
}

Parameters, headers, and fields

Operation ID: createIncident

Request headers

Request headers
Field	Description
`Idempotency-Key` string Optional	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]+$.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`title` string Optional	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 Optional	The service slug. The maximum length is 128 characters. Maximum length: 128 characters.
`regions` string[] Optional	The affected regions. The API trims each value and removes duplicates.
`severity` string Optional	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 Optional	The customer or operational impact summary. This field is separate from title and can change independently.
`declaration_evidence` string Optional	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 Optional	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 Optional	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 Optional	The work type. If the request omits issue_type, the API uses incident. Allowed values: `"ticket""incident""postmortem"`
`status` string Optional	An initial workflow-status key from the workspace configuration. If the request omits status, the API uses the configured default status.
`severity_mode` string Optional	The severity selection mode. If the request omits severity_mode, the API uses auto. Allowed values: `"auto""manual"`
`create_slack_channel` boolean Optional	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[] Optional	The Slack user-group IDs to invite. If the request omits invite_usergroups, the API uses the workspace Slack configuration.
`custom_field_values` object[] Optional	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 Required	The positive ID of the custom-field definition. Minimum: 1.
`custom_field_values[].value` any Required	The value for the custom field. The accepted type depends on field_type.

Response `201`

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`
`source_timeline_event` object Sometimes returned	The complete public record for a timeline event.
`source_timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`source_timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`source_timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`source_timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`source_timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`source_timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`source_timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`source_timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`source_timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`source_timeline_event.source` string Always returned	The system or actor that created the event.
`source_timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`source_timeline_event.type` string Always returned	The event type used for grouping and display.
`source_timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`source_timeline_event.title` string Always returned	The optional display title of the event.
`source_timeline_event.body` string Always returned	The event description.
`source_timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`source_timeline_event.tags` string[] Always returned	The normalized event tags.
`source_timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`source_timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`source_timeline_event.comment_count` integer Always returned	The number of comments on the event.
`source_timeline_event.attachments` object[] Always returned	The files attached to the event.
`source_timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`source_timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`source_timeline_event.attachments[].filename` string Always returned	The original file name.
`source_timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`source_timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`source_timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`source_timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`source_timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`source_timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`source_timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`source_timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`source_timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`source_timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`source_timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`source_timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`source_timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`source_timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`source_timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`source_timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`source_timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`source_timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`source_timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`source_timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`source_timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`source_timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`source_timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`source_timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`source_timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`
`source_timeline_import` object Sometimes returned	The result of importing an initial report as a timeline event.
`source_timeline_import.status` string Always returned	The import result. Possible values: `"imported""failed""unavailable""invalid""unsupported"`
`source_timeline_import.provider` string Sometimes returned	The detected source provider. When the provider is unavailable, this field is absent.
`slack_declaration_attachment` object Sometimes returned	The result of attaching Slack declaration context to the incident.
`slack_declaration_attachment.status` string Always returned	The attachment result. Possible values: `"attached""failed"`
`slack_declaration_images` object Sometimes returned	The result of copying images from a Slack declaration.
`slack_declaration_images.status` string Always returned	The image-copy result. Possible values: `"attached""partial""failed"`
`slack_declaration_images.total` integer Always returned	The total number of Slack images considered. Minimum: 0.
`slack_declaration_images.attached` integer Always returned	The number of images copied successfully. Minimum: 0.
`slack_declaration_images.failed` integer Always returned	The number of images that the API did not copy. Minimum: 0.
`declaration_next` string Sometimes returned	The next incident workspace section requested by a signed Slack declaration.
`custom_field_values` object[] Sometimes returned	The custom-field values saved in the same transaction as the incident.
`custom_field_values[].id` integer Always returned	The positive numeric ID of the stored value. Minimum: 1.
`custom_field_values[].incident_id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`custom_field_values[].custom_field_id` integer Always returned	The positive numeric ID of the custom-field definition. Minimum: 1.
`custom_field_values[].value` any Sometimes returned	The stored field value. Its type depends on field_type.
`custom_field_values[].created_at` string (RFC 3339) Always returned	The initial value storage time.
`custom_field_values[].updated_at` string (RFC 3339) Always returned	The time of the latest value change.

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

Within 24 hours, retry with the original Idempotency-Key and identical body. If the result is unknown, do not retry automatically. Check whether the resource exists. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

idempotency_key_reused idempotency_in_progress idempotency_outcome_unknown

List archived incidents

GET/api/v1/incidents/archived

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

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: 200

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

Success response JSON

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,
      "status_update_summary": {
        "latest_recorded_at": null,
        "next_update_at": null,
        "latest_excerpt": null
      },
      "postmortem_summary": {
        "has_work": false,
        "has_working_draft": false,
        "latest_version_id": null,
        "latest_version_kind": null,
        "work_state": "none"
      },
      "created_at": "2025-01-30T12:00:00Z",
      "created_by": "[email protected]",
      "custom_fields": {},
      "archived_at": "2025-02-07T09:30:00Z",
      "archived_by": 42,
      "incident_manager": "[email protected]",
      "incident_responders": [
        "[email protected]"
      ],
      "has_assignees": true
    }
  ],
  "restricted_count": 3,
  "history_limited": true,
  "has_more": false,
  "pagination": {
    "limit": 50,
    "has_more": false
  }
}

Parameters, headers, and fields

Operation ID: listArchivedIncidents

Query parameters

Query parameters
Field	Description
`limit` integer Optional	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 Optional	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 Optional	Selects all incidents or only postmortems. The default is all. With scope=postmortem, incidents whose postmortem work is missing or in review are listed even when they are older than the workspace history limit, and restricted_count counts only the incidents still hidden. Default: "all". Allowed values: `"all""postmortem"`
`status` string[] Optional	Includes incidents with any supplied workflow status. Repeating status supplies more than one accepted value.
`severity` string[] Optional	Includes incidents with any supplied severity key. Repeating severity supplies more than one accepted value.
`service` string[] Optional	Includes incidents with any supplied service slug. Repeating service supplies more than one accepted value.
`team_id` integer[] Optional	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) Optional	Includes incidents created at or after this RFC 3339 timestamp.
`created_to` string (RFC 3339) Optional	Includes incidents created at or before this RFC 3339 timestamp.
`created_before` string (RFC 3339) Optional	Includes incidents created strictly before this RFC 3339 timestamp. It cannot be combined with created_to.
`region` string[] Optional	Includes incidents with any supplied case-insensitive region. Repeating region supplies more than one accepted value. Maximum items: 100.
`lifecycle` string[] Optional	Includes any supplied incident lifecycle: ticket, incident, postmortem, or alert. Maximum items: 100. Allowed values: `"ticket""incident""postmortem""alert"`
`service_tier` string[] Optional	Includes incidents whose canonical tenant service has any supplied tier. Maximum items: 100. Allowed values: `"t0""t1""t2""t3"`
`effective_team_id` integer[] Optional	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 Optional	When true, also includes incidents with no direct or canonical-service team. Default: false.
`mine` boolean Optional	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 Optional	When true, excludes workflow stages configured as terminal. False does not add a status restriction.
`status_scope` string Optional	Selects all statuses, nonterminal ongoing statuses, or one configured workflow-stage slug. Minimum length: 1 characters. · Maximum length: 2048 characters.
`diagnosis` string[] Optional	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 Optional	Selects the collection sort field. Custom requires sort_custom_field. Owner orders by the active incident manager's email; incidents without an incident manager sort last in both directions. Signal orders by priority, with active incidents before resolved ones, then severity rank in the active severity catalog, then latest activity; it defaults to direction=asc, most urgent first. Omission keeps legacy created_at order. Allowed values: `"created_at""last_event_at""severity""service""diagnosis""case""regions""team""impact""status""owner""events""custom""signal"`
`direction` string Optional	Sort direction for both the selected key and incident-ID tiebreaker. Defaults to desc, except asc when sort is signal. Default: "desc". Allowed values: `"asc""desc"`
`sort_custom_field` string Optional	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[] Optional	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 Optional	When true, returns authoritative matched, all, ongoing, and per-status counts before cursor and limit. Default: false.
`impact_status` string[] Optional	Includes incidents with any supplied customer-impact status. Allowed values: `"unknown""none""confirmed"`
`affected_customers_op` string Optional	Selects the operator for the affected-customer comparison. This parameter and affected_customers_value must appear together. Allowed values: `"<"">""="`
`affected_customers_value` integer Optional	The non-negative affected-customer count for comparison. This parameter and affected_customers_op must appear together. Minimum: 0.
`mrr_op` string Optional	Selects the operator for the MRR comparison. This parameter and mrr_value must appear together. Allowed values: `"<"">""="`
`mrr_value` integer Optional	The non-negative MRR amount for comparison, in minor currency units. This parameter and mrr_op must appear together. Minimum: 0.
`mrr_currency` string Optional	A three-letter ISO currency code. If mrr_basis is source, this parameter is required. Pattern: ^[A-Z]{3}$.
`mrr_basis` string Optional	Selects normalized workspace currency values or original source currency values. The default is normalized. Default: "normalized". Allowed values: `"normalized""source"`

Response `200`

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

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incidents` object[] Always returned	The incidents in this page.
`incidents[].id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incidents[].revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incidents[].company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incidents[].human_id` string Always returned	The permanent incident reference shown to users.
`incidents[].title` string Always returned	The editable display title of the incident.
`incidents[].service` string Always returned	The service slug associated with the incident.
`incidents[].regions` string[] Always returned	The affected regions.
`incidents[].severity` string Always returned	The configured severity key.
`incidents[].slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incidents[].meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incidents[].doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incidents[].status` string Always returned	The configured workflow-status key.
`incidents[].status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incidents[].last_event_summary` string Always returned	A summary of the latest timeline event.
`incidents[].issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incidents[].severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incidents[].impact_summary` string Always returned	The current customer or operational impact summary.
`incidents[].customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incidents[].impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incidents[].first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incidents[].recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incidents[].duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incidents[].duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incidents[].team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incidents[].event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incidents[].investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incidents[].investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incidents[].investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incidents[].investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incidents[].status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incidents[].status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incidents[].status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incidents[].status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incidents[].status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incidents[].status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incidents[].status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incidents[].postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incidents[].postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incidents[].postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incidents[].postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incidents[].postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incidents[].postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incidents[].created_at` string (RFC 3339) Always returned	The incident creation time.
`incidents[].created_by` string Always returned	The identifier of the user who created the incident.
`incidents[].custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incidents[].archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incidents[].archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incidents[].incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incidents[].incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incidents[].has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`has_more` boolean Always returned	Deprecated top-level alias for pagination.has_more.
`next_cursor` string Sometimes returned	Deprecated top-level alias for pagination.next_cursor.
`pagination` object Always returned	Pagination details for a collection response.
`pagination.limit` integer Always returned	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more` boolean Always returned	Indicates whether another page is available.
`pagination.next_cursor` string Sometimes returned	The opaque cursor for the next page. This field is absent on the final page.
`restricted_count` integer Sometimes returned	The number of matching incidents excluded by the workspace history limit. Minimum: 0.
`history_limited` boolean Sometimes returned	Indicates whether the workspace history limit applies to this response.
`mrr_currency` string Sometimes returned	The workspace reporting currency used for normalized MRR values.
`mrr_conversion_mode` string Sometimes returned	The workspace mode for MRR currency conversion. Possible values: `"normalized""source_only"`
`mrr_projection_state` string Sometimes returned	The MRR projection state. Possible values: `"ready""stale""unavailable"`
`supported_mrr_currencies` string[] Sometimes returned	The ISO currency codes supported by MRR filters.
`collection_counts` object Sometimes returned	Complete collection counts before cursor and limit when include_counts is true.
`collection_counts.matched` integer Always returned	Count after every predicate, including status selection. Minimum: 0.
`collection_counts.all` integer Always returned	Count after non-status predicates, excluding status, status_scope, and active_only. Minimum: 0.
`collection_counts.ongoing` integer Always returned	Nonterminal count after non-status predicates. Minimum: 0.
`collection_counts.by_status` object Always returned	Exact counts by normalized stored status after non-status predicates.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Get incident by permanent reference

GET/api/v1/incident-references/{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

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: 200

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

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Related operations: Get incident

Parameters, headers, and fields

Operation ID: getIncidentByReference

Path parameters

Path parameters
Field	Description
`reference` string Required	A permanent, opaque reference from Tellagen incident links and messages. This parameter does not accept a numeric incident ID. Minimum length: 1 characters.

Response `200`

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

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Get incident

GET/api/v1/incidents/{id}

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

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: 200

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.

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Related operations: Get incident by permanent reference

Parameters, headers, and fields

Operation ID: getIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Response `200`

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Update incident

PATCH/api/v1/incidents/{id}

Updates only the fields that you send. Other fields keep their current values. The response contains the complete incident.

Use resolve, close, or reopen to change the workflow status. This endpoint still accepts status changes for existing API v1 clients. The API checks new timestamps against existing timestamps. Field changes can also change automatic severity.

Required scope: incidents:write
Also required: Active responder seat Incident is not archived

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"
}'

Success: 200

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.

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Parameters, headers, and fields

Operation ID: updateIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	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

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

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

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

Response `200`

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.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (9)

If the API returns 412, read the resource again. Compare the latest changes before you retry with the new version. Retries and updates

Error responses (9)

400 401 403 404 409 412 428 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

List incident actions

GET/api/v1/incidents/{id}/actions

Returns the incident actions that match the repeated status filters. If status is omitted, the API returns open, in_progress, blocked, and waiting actions. The response is ordered by priority, due time, and creation time. The total field equals the number of returned actions.

Required scope: incidents:read

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}/actions' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the matching action records and their count. Blocker fields are present for blocked or waiting actions; an unassigned unblock owner is represented by a null value or an omitted response field.

Success response JSON

json

{
  "actions": [
    {
      "id": 301,
      "incident_id": 1,
      "title": "Confirm provider recovery",
      "description": "Confirm the provider has restored the payment path.",
      "status": "blocked",
      "priority": "high",
      "category": "immediate",
      "operational_caveat": "",
      "blocker_reason": "Waiting for provider confirmation",
      "unblock_owner_user_id": 42,
      "source": "custom",
      "assignee_user_id": 7,
      "due_at": "2026-08-31T13:00:00Z",
      "created_by": "[email protected]",
      "completed_at": null,
      "created_at": "2026-08-31T12:15:00Z",
      "updated_at": "2026-08-31T12:20:00Z",
      "supporting_evidence": []
    }
  ],
  "total": 1
}

Parameters, headers, and fields

Operation ID: listIncidentActions

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Query parameters

Query parameters
Field	Description
`status` string[] Optional	Repeated action statuses to include. The default is open, in_progress, blocked, and waiting. Allowed values: `"open""in_progress""blocked""waiting""completed""canceled"`

Response `200`

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`actions` object[] Always returned	The incident actions matching the requested statuses.
`actions[].id` integer Always returned	The positive numeric ID of the action. Minimum: 1.
`actions[].incident_id` integer Always returned	The positive numeric ID of the incident that owns the action. Minimum: 1.
`actions[].title` string Always returned	The action title after trimming. The maximum length is 160 Unicode characters. Minimum length: 1 characters. · Maximum length: 160 characters.
`actions[].description` string Always returned	The action details after trimming. The maximum length is 2 Maximum length: 2000 characters.
`actions[].status` string Always returned	The response-work state of an incident action. Possible values: `"open""in_progress""blocked""waiting""completed""canceled"`
`actions[].priority` string Always returned	The urgency assigned to an incident action. Possible values: `"critical""high""medium""low"`
`actions[].category` string Always returned	The response-work category assigned to an incident action. Possible values: `"immediate""prevent_recurrence""investigate""monitor""unspecified"`
`actions[].operational_caveat` string Sometimes returned	The diagnostic guidance caveat for the action. This is separate from blocker_reason and is omitted when empty.
`actions[].blocker_reason` string Sometimes returned	The human dependency explanation. It is present and nonempty for blocked or waiting actions and omitted after leaving those states. Maximum length: 2000 characters.
`actions[].unblock_owner_user_id` integer \| null Sometimes returned	The active incident manager or responder responsible for clearing the dependency. A null value means unassigned and this field may be omitted from responses. Minimum: 1.
`actions[].source` string Always returned	The source that created an incident action. Possible values: `"custom""diagnostic""suggestion"`
`actions[].source_suggestion_id` integer \| null Sometimes returned	The source suggestion ID when the action was accepted from a diagnostic suggestion. This field is omitted for other sources. Minimum: 1.
`actions[].assignee_user_id` integer \| null Sometimes returned	The active incident participant responsible for carrying out the action. A null value means unassigned and this field may be omitted from responses. Minimum: 1.
`actions[].due_at` string (RFC 3339) \| null Sometimes returned	The action due time in RFC 3339 format. A null value means no due time and this field may be omitted from responses.
`actions[].completed_at` string (RFC 3339) \| null Sometimes returned	The completion time in RFC 3339 format. It is null or omitted while the action is not completed.
`actions[].created_by` string Always returned	The identifier of the user who created the action.
`actions[].created_at` string (RFC 3339) Always returned	The action creation time.
`actions[].updated_at` string (RFC 3339) Always returned	The time of the latest action change.
`actions[].supporting_evidence` object[] Always returned	Evidence references attached to the action.
`actions[].supporting_evidence[].source` string Always returned	The system or provider that supplied the evidence.
`actions[].supporting_evidence[].url` string Always returned	The absolute URL of the evidence.
`actions[].supporting_evidence[].label` string Sometimes returned	A short display name for the evidence.
`actions[].supporting_evidence[].summary` string Sometimes returned	A short summary of the evidence.
`actions[].supporting_evidence[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`actions[].supporting_evidence[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`actions[].supporting_evidence[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`actions[].supporting_evidence[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`total` integer Always returned	The number of actions in the actions array. Minimum: 0.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Create incident action

POST/api/v1/incidents/{id}/actions

Creates an open action on an active incident. The API validates the title, description, priority, assignee, and due time before saving. New actions do not accept blocker fields; use the update operation to move an action to blocked or waiting with a required blocker reason.

Required scope: incidents:write
Also required: Active responder seat Incident is not archived

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}/actions' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Confirm provider recovery",
  "description": "Confirm the provider has restored the payment path.",
  "priority": "high",
  "assignee_user_id": 7,
  "due_at": "2026-08-31T13:00:00Z"
}'

Success: 201

Returns the created open action.

Success response JSON

json

{
  "action": {
    "id": 301,
    "incident_id": 1,
    "title": "Confirm provider recovery",
    "description": "Confirm the provider has restored the payment path.",
    "status": "open",
    "priority": "high",
    "category": "unspecified",
    "operational_caveat": "",
    "source": "custom",
    "assignee_user_id": 7,
    "due_at": "2026-08-31T13:00:00Z",
    "created_by": "[email protected]",
    "completed_at": null,
    "created_at": "2026-08-31T12:15:00Z",
    "updated_at": "2026-08-31T12:15:00Z",
    "supporting_evidence": []
  }
}

Parameters, headers, and fields

Operation ID: createIncidentAction

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`title` string Required	The action title. Leading and trailing whitespace is removed before the maximum of 160 Unicode characters is enforced. Minimum length: 1 characters. · Maximum length: 160 characters.
`description` string Optional	Optional action details. Leading and trailing whitespace is removed before the maximum of 2 Maximum length: 2000 characters.
`priority` string Optional	The urgency assigned to an incident action. Allowed values: `"critical""high""medium""low"`
`assignee_user_id` integer \| null Optional	The positive ID of an active incident manager or responder. A null value leaves the action unassigned. Minimum: 1.
`due_at` string (RFC 3339) \| null Optional	The due time in RFC 3339 format

Response `201`

Returns the created open action.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`action` object Always returned	The complete public record for an incident action. A blocker reason is required for blocked and waiting actions. Blocker fields are omitted when they are empty or unassigned.
`action.id` integer Always returned	The positive numeric ID of the action. Minimum: 1.
`action.incident_id` integer Always returned	The positive numeric ID of the incident that owns the action. Minimum: 1.
`action.title` string Always returned	The action title after trimming. The maximum length is 160 Unicode characters. Minimum length: 1 characters. · Maximum length: 160 characters.
`action.description` string Always returned	The action details after trimming. The maximum length is 2 Maximum length: 2000 characters.
`action.status` string Always returned	The response-work state of an incident action. Possible values: `"open""in_progress""blocked""waiting""completed""canceled"`
`action.priority` string Always returned	The urgency assigned to an incident action. Possible values: `"critical""high""medium""low"`
`action.category` string Always returned	The response-work category assigned to an incident action. Possible values: `"immediate""prevent_recurrence""investigate""monitor""unspecified"`
`action.operational_caveat` string Sometimes returned	The diagnostic guidance caveat for the action. This is separate from blocker_reason and is omitted when empty.
`action.blocker_reason` string Sometimes returned	The human dependency explanation. It is present and nonempty for blocked or waiting actions and omitted after leaving those states. Maximum length: 2000 characters.
`action.unblock_owner_user_id` integer \| null Sometimes returned	The active incident manager or responder responsible for clearing the dependency. A null value means unassigned and this field may be omitted from responses. Minimum: 1.
`action.source` string Always returned	The source that created an incident action. Possible values: `"custom""diagnostic""suggestion"`
`action.source_suggestion_id` integer \| null Sometimes returned	The source suggestion ID when the action was accepted from a diagnostic suggestion. This field is omitted for other sources. Minimum: 1.
`action.assignee_user_id` integer \| null Sometimes returned	The active incident participant responsible for carrying out the action. A null value means unassigned and this field may be omitted from responses. Minimum: 1.
`action.due_at` string (RFC 3339) \| null Sometimes returned	The action due time in RFC 3339 format. A null value means no due time and this field may be omitted from responses.
`action.completed_at` string (RFC 3339) \| null Sometimes returned	The completion time in RFC 3339 format. It is null or omitted while the action is not completed.
`action.created_by` string Always returned	The identifier of the user who created the action.
`action.created_at` string (RFC 3339) Always returned	The action creation time.
`action.updated_at` string (RFC 3339) Always returned	The time of the latest action change.
`action.supporting_evidence` object[] Always returned	Evidence references attached to the action.
`action.supporting_evidence[].source` string Always returned	The system or provider that supplied the evidence.
`action.supporting_evidence[].url` string Always returned	The absolute URL of the evidence.
`action.supporting_evidence[].label` string Sometimes returned	A short display name for the evidence.
`action.supporting_evidence[].summary` string Sometimes returned	A short summary of the evidence.
`action.supporting_evidence[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`action.supporting_evidence[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`action.supporting_evidence[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`action.supporting_evidence[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Update incident action

PATCH/api/v1/incident-actions/{id}

Updates the supplied action fields after validating the merged result. Omitted fields stay unchanged. Set status to blocked or waiting only with a nonempty trimmed blocker_reason of at most 2,000 Unicode characters; an unblock_owner_user_id, when supplied, must identify an active incident manager or responder. A null blocker_reason or unblock_owner_user_id clears that field when the resulting status is not blocked or waiting. Leaving a blocked or waiting status clears both blocker fields. The update is serialized with other action changes so a stale read cannot persist an invalid status and blocker combination.

Required scope: incidents:write
Also required: Active responder seat Incident is not archived

Example request

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

bash

curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/incident-actions/{id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "waiting",
  "blocker_reason": "Waiting for the maintenance window.",
  "unblock_owner_user_id": null
}'

Success: 200

Returns the updated action. Blocker fields are present only while the action is blocked or waiting; an unassigned unblock owner is represented by a null value or an omitted response field.

Success response JSON

json

{
  "action": {
    "id": 301,
    "incident_id": 1,
    "title": "Confirm provider recovery",
    "description": "Confirm the provider has restored the payment path.",
    "status": "waiting",
    "priority": "high",
    "category": "immediate",
    "operational_caveat": "",
    "blocker_reason": "Waiting for the maintenance window.",
    "unblock_owner_user_id": null,
    "source": "custom",
    "assignee_user_id": 7,
    "due_at": "2026-08-31T13:00:00Z",
    "created_by": "[email protected]",
    "completed_at": null,
    "created_at": "2026-08-31T12:15:00Z",
    "updated_at": "2026-08-31T12:25:00Z",
    "supporting_evidence": []
  }
}

Parameters, headers, and fields

Operation ID: updateIncidentAction

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident-action ID returned by this API. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`title` string Optional	The replacement action title after trimming. The maximum length is 160 Unicode characters. Minimum length: 1 characters. · Maximum length: 160 characters.
`description` string Optional	The replacement action details after trimming. The maximum length is 2 Maximum length: 2000 characters.
`status` string Optional	The response-work state of an incident action. Allowed values: `"open""in_progress""blocked""waiting""completed""canceled"`
`priority` string Optional	The urgency assigned to an incident action. Allowed values: `"critical""high""medium""low"`
`assignee_user_id` integer \| null Optional	The positive ID of an active incident manager or responder Minimum: 1.
`due_at` string (RFC 3339) \| null Optional	The replacement due time in RFC 3339 format
`blocker_reason` string \| null Optional	The trimmed dependency explanation Maximum length: 2000 characters.
`unblock_owner_user_id` integer \| null Optional	The active incident manager or responder responsible for clearing the dependency, or null to clear the owner while the merged status remains blocked or waiting. Both blocker fields are cleared automatically when the merged status is another state. Minimum: 1.

Response `200`

Returns the updated action. Blocker fields are present only while the action is blocked or waiting; an unassigned unblock owner is represented by a null value or an omitted response field.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`action` object Always returned	The complete public record for an incident action. A blocker reason is required for blocked and waiting actions. Blocker fields are omitted when they are empty or unassigned.
`action.id` integer Always returned	The positive numeric ID of the action. Minimum: 1.
`action.incident_id` integer Always returned	The positive numeric ID of the incident that owns the action. Minimum: 1.
`action.title` string Always returned	The action title after trimming. The maximum length is 160 Unicode characters. Minimum length: 1 characters. · Maximum length: 160 characters.
`action.description` string Always returned	The action details after trimming. The maximum length is 2 Maximum length: 2000 characters.
`action.status` string Always returned	The response-work state of an incident action. Possible values: `"open""in_progress""blocked""waiting""completed""canceled"`
`action.priority` string Always returned	The urgency assigned to an incident action. Possible values: `"critical""high""medium""low"`
`action.category` string Always returned	The response-work category assigned to an incident action. Possible values: `"immediate""prevent_recurrence""investigate""monitor""unspecified"`
`action.operational_caveat` string Sometimes returned	The diagnostic guidance caveat for the action. This is separate from blocker_reason and is omitted when empty.
`action.blocker_reason` string Sometimes returned	The human dependency explanation. It is present and nonempty for blocked or waiting actions and omitted after leaving those states. Maximum length: 2000 characters.
`action.unblock_owner_user_id` integer \| null Sometimes returned	The active incident manager or responder responsible for clearing the dependency. A null value means unassigned and this field may be omitted from responses. Minimum: 1.
`action.source` string Always returned	The source that created an incident action. Possible values: `"custom""diagnostic""suggestion"`
`action.source_suggestion_id` integer \| null Sometimes returned	The source suggestion ID when the action was accepted from a diagnostic suggestion. This field is omitted for other sources. Minimum: 1.
`action.assignee_user_id` integer \| null Sometimes returned	The active incident participant responsible for carrying out the action. A null value means unassigned and this field may be omitted from responses. Minimum: 1.
`action.due_at` string (RFC 3339) \| null Sometimes returned	The action due time in RFC 3339 format. A null value means no due time and this field may be omitted from responses.
`action.completed_at` string (RFC 3339) \| null Sometimes returned	The completion time in RFC 3339 format. It is null or omitted while the action is not completed.
`action.created_by` string Always returned	The identifier of the user who created the action.
`action.created_at` string (RFC 3339) Always returned	The action creation time.
`action.updated_at` string (RFC 3339) Always returned	The time of the latest action change.
`action.supporting_evidence` object[] Always returned	Evidence references attached to the action.
`action.supporting_evidence[].source` string Always returned	The system or provider that supplied the evidence.
`action.supporting_evidence[].url` string Always returned	The absolute URL of the evidence.
`action.supporting_evidence[].label` string Sometimes returned	A short display name for the evidence.
`action.supporting_evidence[].summary` string Sometimes returned	A short summary of the evidence.
`action.supporting_evidence[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`action.supporting_evidence[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`action.supporting_evidence[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`action.supporting_evidence[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Resolve incident

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

Marks the incident resolved and changes issue_type to postmortem. Tellagen saves the status, recovery time, and resolution note together. Existing postmortem drafts and versions stay unchanged.

The request body is optional. An outdated expected_revision returns 412. If the incident is already resolved, an empty request succeeds without another event. A repeated request with a note or recovery edit returns 412.

Required scope: incidents:write
Also required: Active responder seat Incident is not archived

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
}'

Success: 200

Returns the complete incident and the committed resolution timeline event.

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Parameters, headers, and fields

Operation ID: resolveIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`resolution_note` string Optional	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 Optional	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 Optional	The incident revision displayed to the responder. A mismatch returns 412 without saving any changes.

Response `200`

Returns the complete incident and the committed resolution timeline event.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Close incident without resolution

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

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
Also required: Active responder seat Incident is not archived

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
}'

Success: 200

Returns the complete incident after closure.

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Parameters, headers, and fields

Operation ID: closeIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`reason` string Required	The closure reason. Allowed values: `"duplicate""false_alarm""test_or_accidental""not_an_incident""other"`
`comment` string Required	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.

Response `200`

Returns the complete incident after closure.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Reopen incident

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

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
Also required: Active responder seat Incident is not archived

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."
}'

Success: 200

Returns the complete incident after it becomes active.

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Parameters, headers, and fields

Operation ID: reopenIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	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.

Response `200`

Returns the complete incident after it becomes active.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Get incident integration setup

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

Shows progress for integration tasks, such as Slack channel creation. Pending tasks resume after a server restart. Failed tasks retry automatically. The completed state means that all saved tasks finished.

Required scope: incidents:read

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: 200

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

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: getIncidentProvisioning

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Response `200`

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

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`status` string Always returned	Aggregate state of persisted incident integration steps. Possible values: `"pending""failed""completed"`
`retryable` boolean Always returned	True when a failed step can be made eligible for immediate retry.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Retry incident integration setup

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

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
Also required: Active responder seat

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: 200

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

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: retryIncidentProvisioning

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Response `200`

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

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`status` string Always returned	Aggregate state of persisted incident integration steps. Possible values: `"pending""failed""completed"`
`retryable` boolean Always returned	True when a failed step can be made eligible for immediate retry.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Archive incident

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

Removes the incident from default lists without changing its workflow status. The incident and its related records remain available as read-only data.

A repeated request returns 204 without changes to archive details, revision, changelog, or audit records. The API key owner needs an active responder seat.

Required scope: incidents:write
Also required: Active responder seat

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: 204

No response body. Do not try to parse this response as JSON.

Parameters, headers, and fields

Operation ID: archiveIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Returns 204 with no body.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Restore incident

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

Returns an archived incident to default lists without changing its workflow status. If the incident has a team_id, that team must be active.

A repeated request returns the incident without changes to its revision, changelog, or audit records. The API key owner needs an active responder seat.

Required scope: incidents:write
Also required: Active responder seat

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: 200

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

Success response JSON

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,
    "status_update_summary": null,
    "postmortem_summary": null,
    "created_at": "2025-01-30T12:00:00Z",
    "created_by": "[email protected]",
    "custom_fields": {},
    "archived_at": null,
    "archived_by": null,
    "incident_manager": "[email protected]",
    "incident_responders": [
      "[email protected]"
    ],
    "has_assignees": true
  }
}

Parameters, headers, and fields

Operation ID: restoreIncident

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Response `200`

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

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`incident` object Always returned	The complete public record for an incident.
`incident.id` integer Always returned	The positive numeric ID of the incident. Minimum: 1.
`incident.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`incident.company_id` integer Always returned	The ID of the workspace that owns the incident. Minimum: 1.
`incident.human_id` string Always returned	The permanent incident reference shown to users.
`incident.title` string Always returned	The editable display title of the incident.
`incident.service` string Always returned	The service slug associated with the incident.
`incident.regions` string[] Always returned	The affected regions.
`incident.severity` string Always returned	The configured severity key.
`incident.slack_channel_id` string Always returned	The linked Slack channel ID. An empty string means that no channel is linked.
`incident.meet_url` string Always returned	The incident meeting URL. An empty string means that no meeting is linked.
`incident.doc_url` string Always returned	The incident document or source URL. An empty string means that no URL is stored.
`incident.status` string Always returned	The configured workflow-status key.
`incident.status_changed_at` string (RFC 3339) \| null Always returned	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 returned	The start time of the latest timeline event. A null value means that no event exists.
`incident.last_event_summary` string Always returned	A summary of the latest timeline event.
`incident.issue_type` string Always returned	The work type. Possible values: `"ticket""incident""postmortem"`
`incident.severity_mode` string Always returned	The severity selection mode. Possible values: `"auto""manual"`
`incident.impact_summary` string Always returned	The current customer or operational impact summary.
`incident.customer_impact_status` string Always returned	The customer-impact assessment. Possible values: `"unknown""none""confirmed"`
`incident.impact_started_at` string (RFC 3339) \| null Always returned	The impact start time. A null value means that the time is unknown.
`incident.first_reported_at` string (RFC 3339) \| null Always returned	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 returned	The time of the first response. A null value means that the time is unknown.
`incident.recovered_at` string (RFC 3339) \| null Always returned	The service recovery time. A null value means that recovery is not recorded.
`incident.duration_seconds` integer Always returned	The calculated incident duration in whole seconds. Minimum: 0.
`incident.duration_anchor` string Always returned	The timestamp field from which the API calculates duration.
`incident.team_id` integer \| null Always returned	The owning-team ID. A null value means that the incident has no owning team.
`incident.event_count` integer Always returned	The number of timeline events for the incident. Minimum: 0.
`incident.investigation_summary` object \| null Always returned	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 returned	The total number of investigation runs. Minimum: 0.
`incident.investigation_summary.latest_run` object \| null Always returned	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 returned	The current investigation-run status.
`incident.investigation_summary.latest_run.started_at` string (RFC 3339) Always returned	The investigation-run start time.
`incident.investigation_summary.latest_run.completed_at` string (RFC 3339) Sometimes returned	The investigation-run completion time.
`incident.status_update_summary` object \| null Always returned	The latest recorded status update and the next update time that it set. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load status-update data. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_recorded_at` string (RFC 3339) \| null Always returned	The time of the latest status update. A null value means that no status update has been recorded.
`incident.status_update_summary.next_update_at` string (RFC 3339) \| null Always returned	The next update time set by the latest status update. A null value means that no time was set.
`incident.status_update_summary.latest_excerpt` string \| null Always returned	One line from the latest status update: its current action, or its current impact when the action is blank, trimmed. Text longer than 120 characters keeps its first 117 characters and ends with an ellipsis (…). A null value means that no status update has been recorded. Only incident collection responses load this field; single-incident and mutation responses return status_update_summary as null. Maximum length: 120 characters.
`incident.status_update_summary.latest_delivery` object \| null Sometimes returned	How the latest status update was posted to Slack. A null value means that the update was recorded without sharing, that no status update has been recorded, or that the workspace does not have status update delivery turned on. Must match exactly one of 2 schema variants.
`incident.status_update_summary.latest_delivery.sent` integer Always returned	Delivered. Minimum: 0.
`incident.status_update_summary.latest_delivery.pending` integer Always returned	Queued or being posted. Minimum: 0.
`incident.status_update_summary.latest_delivery.failed` integer Always returned	Failed or stopped without reaching Slack; a person can retry these. Minimum: 0.
`incident.status_update_summary.latest_delivery.unconfirmed` integer Always returned	Slack did not confirm these posts and may have accepted them. Check the channel before retrying. Minimum: 0.
`incident.status_update_summary.latest_delivery.skipped` integer Always returned	Never attempted. Minimum: 0.
`incident.postmortem_summary` object \| null Always returned	The postmortem work recorded for the incident and whether the incident still needs it. Incident collection responses always include this object. Single-incident and mutation responses return null because they do not load postmortem data. Must match exactly one of 2 schema variants.
`incident.postmortem_summary.has_work` boolean Always returned	Indicates whether a postmortem draft with content, a postmortem version, or a revision request exists.
`incident.postmortem_summary.has_working_draft` boolean Always returned	Indicates whether the working postmortem draft has content or prepared evidence.
`incident.postmortem_summary.latest_version_id` integer \| null Always returned	The ID of the latest postmortem version. A null value means that no version exists.
`incident.postmortem_summary.latest_version_kind` string \| null Always returned	The kind of the latest postmortem version. submitted is a human submission. draft, llm, and legacy need human review before submission. A null value means that no version exists. Possible values: `"submitted""draft""llm""legacy"null`
`incident.postmortem_summary.work_state` string Always returned	Whether the incident still needs postmortem work. none means that no postmortem is due: the incident is not resolved or closed, or it is archived without a submitted postmortem. missing means that a resolved or closed incident has no postmortem version. in_review means that the latest version needs human submission. complete means that the latest version is a human submission. missing and in_review need work; the postmortem queue (scope=postmortem) shows those incidents even when the plan's history window hides other finished incidents. Only incident collection responses load this field; single-incident and mutation responses return postmortem_summary as null. Possible values: `"none""missing""in_review""complete"`
`incident.created_at` string (RFC 3339) Always returned	The incident creation time.
`incident.created_by` string Always returned	The identifier of the user who created the incident.
`incident.custom_fields` object Always returned	The incident values keyed by custom-field slug.
`incident.archived_at` string (RFC 3339) \| null Always returned	The incident archive time. A null value means that the incident is active.
`incident.archived_by` integer \| null Always returned	The user ID that archived the incident. A null value means that the incident is active.
`incident.incident_manager` string Always returned	The user identifier of the incident manager. An empty string means that no manager is assigned.
`incident.incident_responders` string[] Always returned	The user identifiers of assigned responders.
`incident.has_assignees` boolean Always returned	Indicates whether the incident has a manager or at least one responder.
`timeline_event` object Sometimes returned	The complete public record for a timeline event.
`timeline_event.id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`timeline_event.incident_id` integer Always returned	The positive numeric ID of the incident.
`timeline_event.started_at` string (RFC 3339) Always returned	The event start time.
`timeline_event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`timeline_event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`timeline_event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`timeline_event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`timeline_event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`timeline_event.source` string Always returned	The system or actor that created the event.
`timeline_event.source_ref` string Always returned	The source-specific reference for the event.
`timeline_event.type` string Always returned	The event type used for grouping and display.
`timeline_event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`timeline_event.title` string Always returned	The optional display title of the event.
`timeline_event.body` string Always returned	The event description.
`timeline_event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`timeline_event.tags` string[] Always returned	The normalized event tags.
`timeline_event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`timeline_event.created_by` string Always returned	The identifier of the user or system that created the event.
`timeline_event.comment_count` integer Always returned	The number of comments on the event.
`timeline_event.attachments` object[] Always returned	The files attached to the event.
`timeline_event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`timeline_event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`timeline_event.attachments[].filename` string Always returned	The original file name.
`timeline_event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`timeline_event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`timeline_event.attachments[].content_type` string Always returned	The media type of the attached file.
`timeline_event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`timeline_event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`timeline_event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`timeline_event.source_window_started_at` string (RFC 3339) \| null Always returned	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 returned	The end of the source-data window. A null value means that no window is recorded.
`timeline_event.evidence_links` object[] Always returned	The evidence references associated with the event.
`timeline_event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`timeline_event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`timeline_event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`timeline_event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`timeline_event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`timeline_event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`timeline_event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`timeline_event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`timeline_event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`timeline_event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`timeline_event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`timeline_event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`timeline_event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`timeline_event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`timeline_event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`timeline_event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`

Response headers

Response headers
Field	Description
`Tellagen-Resource-Version` integer Always returned	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

invalid_relationship_state

Reapply the Slack channel-name template (deprecated)

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

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
Also required: Active responder seat Incident is not archived Linked Slack channel

Deprecated operation

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

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: 200

Returns the new Slack channel name.

Success response JSON

json

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

Parameters, headers, and fields

Operation ID: syncIncidentSlackChannelName

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Response `200`

Returns the new Slack channel name.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`channel_name` string Always returned	The new Slack channel name.

Response headers

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

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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.

invalid_slack_channel_name_request slack_not_configured incident_slack_channel_missing slack_channel_not_found slack_channel_name_taken invalid_resource_state

Preview an incident Slack channel name

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

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
Also required: Active responder seat Incident is not archived Linked Slack channel

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"
}'

Success: 200

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.

Success response JSON

json

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

Related operations: Update an incident Slack channel name

Parameters, headers, and fields

Operation ID: previewIncidentSlackChannelName

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`mode` string Required	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]..

Response `200`

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.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`channel_id` string Always returned	The Slack channel ID.
`previous_name` string Always returned	The channel name before the request.
`new_name` string Always returned	The validated channel name. The maximum length is 80 characters. Minimum length: 1 characters. · Maximum length: 80 characters.
`mode` string Always returned	The naming mode. Possible values: `"workspace_template""custom"`

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

invalid_slack_channel_name_request slack_not_configured incident_slack_channel_missing slack_channel_not_found slack_channel_name_taken invalid_resource_state

Update an incident Slack channel name

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

Renames the linked Slack channel with workspace_template or custom mode. The audit log records the old name, new name, mode, person, and time. Tellagen also publishes the audit entry as an incident event.

If the audit save fails, Tellagen attempts to restore the old channel name and returns an error.

Required scope: incidents:write
Also required: Active responder seat Incident is not archived Linked Slack channel

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"
}'

Success: 200

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.

Success response JSON

json

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

Related operations: Preview an incident Slack channel name

Parameters, headers, and fields

Operation ID: updateIncidentSlackChannelName

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`mode` string Required	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]..

Response `200`

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`channel_id` string Always returned	The Slack channel ID.
`previous_name` string Always returned	The channel name before the request.
`new_name` string Always returned	The validated channel name. The maximum length is 80 characters. Minimum length: 1 characters. · Maximum length: 80 characters.
`mode` string Always returned	The naming mode. Possible values: `"workspace_template""custom"`

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

invalid_slack_channel_name_request slack_not_configured incident_slack_channel_missing slack_channel_not_found slack_channel_name_taken invalid_resource_state

Read this resource as Markdown · OpenAPI specification

Incidents

Endpoints

List incidents

Example request

Success: 200

Query parameters

Response 200

Error responses (7)

Create incident

Example request

Success: 201

Request headers

Request body

Response 201

Response headers

Error responses (7)

List archived incidents

Example request

Success: 200

Query parameters

Response 200

Error responses (7)

Get incident by permanent reference

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Get incident

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Update incident

Example request

Success: 200

Path parameters

Request headers

Request body

Response 200

Response headers

Error responses (9)

List incident actions

Example request

Success: 200

Path parameters

Query parameters

Response 200

Error responses (7)

Create incident action

Example request

Success: 201

Path parameters

Request body

Response 201

Error responses (7)

Update incident action

Example request

Success: 200

Path parameters

Request body

Response 200

Error responses (7)

Resolve incident

Example request

Success: 200

Path parameters

Request body

Response 200

Response headers

Error responses (7)

Close incident without resolution

Example request

Success: 200

Path parameters

Request body

Response 200

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`