API ReferenceIncidents
All endpoints
Incidents
Creates, lists, reads, updates, archives, restores, and changes the lifecycle state of incidents.
GET/api/v1/incidentsList incidents
#Returns one page of active incidents. The default page size is 50, and the maximum is 100. Values repeated within one set filter combine with OR; different filters combine with AND. Filters apply before pagination and also apply to restricted_count. Omitted sort keeps the legacy created_at-descending order. Extended collection queries use opaque v3 cursors bound to the company, normalized predicates, resolved metadata, and exact typed sort key. Legacy v1/v2 cursors remain accepted only with the legacy default order and legacy-compatible predicates. Pagination is deterministic keyset traversal for unchanged rows, not a cross-request database snapshot.
- Operation ID
- listIncidents
- Scope
- incidents:read
- Prerequisites
- None
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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,
"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
}
}
}Request and response contract
Query parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | No | The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50. |
cursor | string | No | The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters. |
scope | string | No | Selects all incidents or only postmortems. The default is all. Default: "all". Allowed values: "all""postmortem" |
status | string[] | No | Includes incidents with any supplied workflow status. Repeating status supplies more than one accepted value. |
severity | string[] | No | Includes incidents with any supplied severity key. Repeating severity supplies more than one accepted value. |
service | string[] | No | Includes incidents with any supplied service slug. Repeating service supplies more than one accepted value. |
team_id | integer[] | No | Includes incidents with any supplied owning-team ID. Repeating team_id supplies more than one accepted value. Each ID must be positive. |
created_from | string (RFC 3339) | No | Includes incidents created at or after this RFC 3339 timestamp. |
created_to | string (RFC 3339) | No | Includes incidents created at or before this RFC 3339 timestamp. |
created_before | string (RFC 3339) | No | Includes incidents created strictly before this RFC 3339 timestamp. It cannot be combined with created_to. |
region | string[] | No | Includes incidents with any supplied case-insensitive region. Repeating region supplies more than one accepted value. Maximum items: 100. |
lifecycle | string[] | No | Includes any supplied incident lifecycle: ticket, incident, postmortem, or alert. Maximum items: 100. Allowed values: "ticket""incident""postmortem""alert" |
service_tier | string[] | No | Includes incidents whose canonical tenant service has any supplied tier. Maximum items: 100. Allowed values: "t0""t1""t2""t3" |
effective_team_id | integer[] | No | Includes incidents assigned directly to any supplied team or inheriting it from the canonical service. Repeating the parameter supplies more than one accepted positive ID. Maximum items: 100. |
unassigned_team | boolean | No | When true, also includes incidents with no direct or canonical-service team. Default: false. |
mine | boolean | No | When true, includes incidents assigned to the authenticated user, or created by that user when no active assignee exists. API-key-only authentication cannot use this filter. Default: false. |
active_only | boolean | No | When true, excludes workflow stages configured as terminal. False does not add a status restriction. |
status_scope | string | No | Selects all statuses, nonterminal ongoing statuses, or one configured workflow-stage slug. Minimum length: 1 characters. · Maximum length: 2048 characters. |
diagnosis | string[] | No | Includes incidents in any supplied diagnosis state. Repeating diagnosis supplies more than one accepted value. Maximum items: 100. Allowed values: "not_run""in_progress""completed""needs_attention""unavailable" |
sort | string | No | Selects the collection sort field. Custom requires sort_custom_field. Omission keeps legacy created_at order. Allowed values: "created_at""last_event_at""severity""service""diagnosis""case""regions""team""impact""status""owner""events""custom" |
direction | string | No | Sort direction for both the selected key and incident-ID tiebreaker. Default: "desc". Allowed values: "asc""desc" |
sort_custom_field | string | No | Active custom-field slug used when sort is custom. The server resolves and validates its stored type. Minimum length: 1 characters. · Maximum length: 64 characters. |
custom_filter | string[] | No | A JSON object with slug, operator, and value. Repeat for up to 32 predicates. Values remain typed JSON; arrays preserve choices containing commas. Supported operators depend on the resolved field type: string is/is_not/contains/starts_with; select is/is_not; boolean is; number and monetary eq/gt/lt/gte/lte/between; date and datetime is/before/after/between/gte/lte; time is/before/after; multiselect includes_any/includes_all/excludes. SQL fragments and client-supplied field types are rejected. Maximum items: 32. |
include_counts | boolean | No | When true, returns authoritative matched, all, ongoing, and per-status counts before cursor and limit. Default: false. |
impact_status | string[] | No | Includes incidents with any supplied customer-impact status. Allowed values: "unknown""none""confirmed" |
affected_customers_op | string | No | Selects the operator for the affected-customer comparison. This parameter and affected_customers_value must appear together. Allowed values: "<"">""=" |
affected_customers_value | integer | No | The non-negative affected-customer count for comparison. This parameter and affected_customers_op must appear together. Minimum: 0. |
mrr_op | string | No | Selects the operator for the MRR comparison. This parameter and mrr_value must appear together. Allowed values: "<"">""=" |
mrr_value | integer | No | The non-negative MRR amount for comparison, in minor currency units. This parameter and mrr_op must appear together. Minimum: 0. |
mrr_currency | string | No | A three-letter ISO currency code. If mrr_basis is source, this parameter is required. Pattern: ^[A-Z]{3}$. |
mrr_basis | string | No | Selects normalized workspace currency values or original source currency values. The default is normalized. Default: "normalized". Allowed values: "normalized""source" |
Response 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.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incidents | object[] | Always | The incidents in this page. |
incidents[].id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incidents[].revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incidents[].company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incidents[].human_id | string | Always | The permanent incident reference shown to users. |
incidents[].title | string | Always | The editable display title of the incident. |
incidents[].service | string | Always | The service slug associated with the incident. |
incidents[].regions | string[] | Always | The affected regions. |
incidents[].severity | string | Always | The configured severity key. |
incidents[].slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incidents[].meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incidents[].doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incidents[].status | string | Always | The configured workflow-status key. |
incidents[].status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incidents[].last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incidents[].last_event_summary | string | Always | A summary of the latest timeline event. |
incidents[].issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incidents[].severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incidents[].impact_summary | string | Always | The current customer or operational impact summary. |
incidents[].customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incidents[].impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incidents[].first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incidents[].first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incidents[].recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incidents[].duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incidents[].duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incidents[].team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incidents[].event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incidents[].investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incidents[].investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incidents[].investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incidents[].investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incidents[].investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incidents[].investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incidents[].created_at | string (RFC 3339) | Always | The incident creation time. |
incidents[].created_by | string | Always | The identifier of the user who created the incident. |
incidents[].custom_fields | object | Always | The incident values keyed by custom-field slug. |
incidents[].archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incidents[].archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incidents[].incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incidents[].incident_responders | string[] | Always | The user identifiers of assigned responders. |
incidents[].has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
has_more | boolean | Always | Deprecated top-level alias for pagination.has_more. |
next_cursor | string | Optional | Deprecated top-level alias for pagination.next_cursor. |
pagination | object | Always | Pagination details for a collection response. |
pagination.limit | integer | Always | The maximum number of items requested for this page. Minimum: 1. · Maximum: 100. |
pagination.has_more | boolean | Always | Indicates whether another page is available. |
pagination.next_cursor | string | Optional | The opaque cursor for the next page. This field is absent on the final page. |
restricted_count | integer | Optional | The number of matching incidents excluded by the workspace history limit. Minimum: 0. |
history_limited | boolean | Optional | Indicates whether the workspace history limit applies to this response. |
mrr_currency | string | Optional | The workspace reporting currency used for normalized MRR values. |
mrr_conversion_mode | string | Optional | The workspace mode for MRR currency conversion. Possible values: "normalized""source_only" |
mrr_projection_state | string | Optional | The MRR projection state. Possible values: "ready""stale""unavailable" |
supported_mrr_currencies | string[] | Optional | The ISO currency codes supported by MRR filters. |
collection_counts | object | Optional | Complete collection counts before cursor and limit when include_counts is true. |
collection_counts.matched | integer | Always | Count after every predicate, including status selection. Minimum: 0. |
collection_counts.all | integer | Always | Count after non-status predicates, excluding status, status_scope, and active_only. Minimum: 0. |
collection_counts.ongoing | integer | Always | Nonterminal count after non-status predicates. Minimum: 0. |
collection_counts.by_status | object | Always | Exact counts by normalized stored status after non-status predicates. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidentsCreate incident
#The API validates every field before it creates the incident. Unknown JSON fields return 400. The API trims text and removes duplicate regions. It rejects values that exceed their length limits. It validates the team before saving the incident. The incident, declaration history, changelog, and outgoing setup work commit together. If Slack is configured and create_slack_channel is true, a durable worker creates the channel after the incident is saved. Use getIncidentProvisioning to inspect setup state and retryIncidentProvisioning to retry failed steps.
- Operation ID
- createIncident
- Scope
- incidents:write
- Prerequisites
- None
- Retry guidance
- Retry an identical request with the same Idempotency-Key used on the first attempt, within 24 hours. Never retry an unknown outcome automatically. Retry rules
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,
"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"
}
]
}Related operations: List available workflow statusesList available severitiesList services
Request and response contract
Request headers
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | No | A key for safe retries of a create request. It must contain 1–128 visible, non-space ASCII characters. The same key applies only to an identical request. Minimum length: 1 characters. · Maximum length: 128 characters. · Pattern: ^[\x21-\x7E]+$. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
title | string | No | The incident display title. The maximum length is 160 characters. If title is omitted, the API derives it from impact_summary or service. Maximum length: 160 characters. |
service | string | No | The service slug. The maximum length is 128 characters. Maximum length: 128 characters. |
regions | string[] | No | The affected regions. The API trims each value and removes duplicates. |
severity | string | No | A severity key from the workspace configuration. If severity is omitted, the API uses the configured default severity. |
short_title | string | Conditional | A short slug for the incident reference and Slack channel name. The API normalizes it and limits it to 12 characters. If short_title_required is true, this field is required. This field is not the incident title. Required when Required when the workspace configuration enables short titles. Maximum length: 12 characters. |
impact_summary | string | No | The customer or operational impact summary. This field is separate from title and can change independently. |
declaration_evidence | string | No | Alert or log text for the incident_declared timeline event. This field records responder evidence and does not set customer_impact_status. |
doc_url | string | No | An absolute HTTP or HTTPS URL stored as an incident reference. The API can import a supported initial report as a separate timeline event. |
import_source_timeline_event | boolean | Conditional | If this value is true, the API imports a supported Slack or PagerDuty doc_url as a timeline event. This value requires doc_url. A signed Slack declaration can require import regardless of this value. Required when This field may be true only when doc_url is provided. |
team_id | integer | No | A positive owning-team ID. If the team does not exist, the API returns 404. If the team is archived, the API returns 400. If the request omits team_id, the API uses the service owner. Minimum: 1. |
issue_type | string | No | The work type. If the request omits issue_type, the API uses incident. Allowed values: "ticket""incident""postmortem" |
status | string | No | An initial workflow-status key from the workspace configuration. If the request omits status, the API uses the configured default status. |
severity_mode | string | No | The severity selection mode. If the request omits severity_mode, the API uses auto. Allowed values: "auto""manual" |
create_slack_channel | boolean | No | Controls Slack channel creation. If the request omits create_slack_channel, the API uses the workspace Slack configuration. Slack must be configured before the API can create a channel. |
invite_usergroups | string[] | No | The Slack user-group IDs to invite. If the request omits invite_usergroups, the API uses the workspace Slack configuration. |
custom_field_values | object[] | No | Custom-field values for the new incident. The API validates every value and each required_on_creation field before Slack work. It saves these values and the incident in one database transaction. |
custom_field_values[].field_id | integer | Yes | The positive ID of the custom-field definition. Minimum: 1. |
custom_field_values[].value | any | Yes | The value for the custom field. The accepted type depends on field_type. |
Response 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.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
source_timeline_event | object | Optional | The complete public record for a timeline event. |
source_timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
source_timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
source_timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
source_timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
source_timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
source_timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
source_timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
source_timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
source_timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
source_timeline_event.source | string | Always | The system or actor that created the event. |
source_timeline_event.source_ref | string | Always | The source-specific reference for the event. |
source_timeline_event.type | string | Always | The event type used for grouping and display. |
source_timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
source_timeline_event.title | string | Always | The optional display title of the event. |
source_timeline_event.body | string | Always | The event description. |
source_timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
source_timeline_event.tags | string[] | Always | The normalized event tags. |
source_timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
source_timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
source_timeline_event.comment_count | integer | Always | The number of comments on the event. |
source_timeline_event.attachments | object[] | Always | The files attached to the event. |
source_timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
source_timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
source_timeline_event.attachments[].filename | string | Always | The original file name. |
source_timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
source_timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
source_timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
source_timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
source_timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
source_timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
source_timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
source_timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
source_timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
source_timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
source_timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
source_timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
source_timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
source_timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
source_timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
source_timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
source_timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
source_timeline_import | object | Optional | The result of importing an initial report as a timeline event. |
source_timeline_import.status | string | Always | The import result. Possible values: "imported""failed""unavailable""invalid""unsupported" |
source_timeline_import.provider | string | Optional | The detected source provider. When the provider is unavailable, this field is absent. |
slack_declaration_attachment | object | Optional | The result of attaching Slack declaration context to the incident. |
slack_declaration_attachment.status | string | Always | The attachment result. Possible values: "attached""failed" |
slack_declaration_images | object | Optional | The result of copying images from a Slack declaration. |
slack_declaration_images.status | string | Always | The image-copy result. Possible values: "attached""partial""failed" |
slack_declaration_images.total | integer | Always | The total number of Slack images considered. Minimum: 0. |
slack_declaration_images.attached | integer | Always | The number of images copied successfully. Minimum: 0. |
slack_declaration_images.failed | integer | Always | The number of images that the API did not copy. Minimum: 0. |
declaration_next | string | Optional | The next incident workspace section requested by a signed Slack declaration. |
custom_field_values | object[] | Optional | The custom-field values saved in the same transaction as the incident. |
custom_field_values[].id | integer | Always | The positive numeric ID of the stored value. Minimum: 1. |
custom_field_values[].incident_id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
custom_field_values[].custom_field_id | integer | Always | The positive numeric ID of the custom-field definition. Minimum: 1. |
custom_field_values[].value | any | Optional | The stored field value. Its type depends on field_type. |
custom_field_values[].created_at | string (RFC 3339) | Always | The initial value storage time. |
custom_field_values[].updated_at | string (RFC 3339) | Always | The time of the latest value change. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
GET/api/v1/incidents/archivedList archived incidents
#Returns one page of archived incidents. The default page size is 50, and the maximum is 100. Results are ordered by archived_at and incident ID. The workspace history limit can exclude older incidents.
- Operation ID
- listArchivedIncidents
- Scope
- incidents:read
- Prerequisites
- None
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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,
"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
}
}Request and response contract
Query parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | No | The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50. |
cursor | string | No | The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters. |
scope | string | No | Selects all incidents or only postmortems. The default is all. Default: "all". Allowed values: "all""postmortem" |
status | string[] | No | Includes incidents with any supplied workflow status. Repeating status supplies more than one accepted value. |
severity | string[] | No | Includes incidents with any supplied severity key. Repeating severity supplies more than one accepted value. |
service | string[] | No | Includes incidents with any supplied service slug. Repeating service supplies more than one accepted value. |
team_id | integer[] | No | Includes incidents with any supplied owning-team ID. Repeating team_id supplies more than one accepted value. Each ID must be positive. |
created_from | string (RFC 3339) | No | Includes incidents created at or after this RFC 3339 timestamp. |
created_to | string (RFC 3339) | No | Includes incidents created at or before this RFC 3339 timestamp. |
created_before | string (RFC 3339) | No | Includes incidents created strictly before this RFC 3339 timestamp. It cannot be combined with created_to. |
region | string[] | No | Includes incidents with any supplied case-insensitive region. Repeating region supplies more than one accepted value. Maximum items: 100. |
lifecycle | string[] | No | Includes any supplied incident lifecycle: ticket, incident, postmortem, or alert. Maximum items: 100. Allowed values: "ticket""incident""postmortem""alert" |
service_tier | string[] | No | Includes incidents whose canonical tenant service has any supplied tier. Maximum items: 100. Allowed values: "t0""t1""t2""t3" |
effective_team_id | integer[] | No | Includes incidents assigned directly to any supplied team or inheriting it from the canonical service. Repeating the parameter supplies more than one accepted positive ID. Maximum items: 100. |
unassigned_team | boolean | No | When true, also includes incidents with no direct or canonical-service team. Default: false. |
mine | boolean | No | When true, includes incidents assigned to the authenticated user, or created by that user when no active assignee exists. API-key-only authentication cannot use this filter. Default: false. |
active_only | boolean | No | When true, excludes workflow stages configured as terminal. False does not add a status restriction. |
status_scope | string | No | Selects all statuses, nonterminal ongoing statuses, or one configured workflow-stage slug. Minimum length: 1 characters. · Maximum length: 2048 characters. |
diagnosis | string[] | No | Includes incidents in any supplied diagnosis state. Repeating diagnosis supplies more than one accepted value. Maximum items: 100. Allowed values: "not_run""in_progress""completed""needs_attention""unavailable" |
sort | string | No | Selects the collection sort field. Custom requires sort_custom_field. Omission keeps legacy created_at order. Allowed values: "created_at""last_event_at""severity""service""diagnosis""case""regions""team""impact""status""owner""events""custom" |
direction | string | No | Sort direction for both the selected key and incident-ID tiebreaker. Default: "desc". Allowed values: "asc""desc" |
sort_custom_field | string | No | Active custom-field slug used when sort is custom. The server resolves and validates its stored type. Minimum length: 1 characters. · Maximum length: 64 characters. |
custom_filter | string[] | No | A JSON object with slug, operator, and value. Repeat for up to 32 predicates. Values remain typed JSON; arrays preserve choices containing commas. Supported operators depend on the resolved field type: string is/is_not/contains/starts_with; select is/is_not; boolean is; number and monetary eq/gt/lt/gte/lte/between; date and datetime is/before/after/between/gte/lte; time is/before/after; multiselect includes_any/includes_all/excludes. SQL fragments and client-supplied field types are rejected. Maximum items: 32. |
include_counts | boolean | No | When true, returns authoritative matched, all, ongoing, and per-status counts before cursor and limit. Default: false. |
impact_status | string[] | No | Includes incidents with any supplied customer-impact status. Allowed values: "unknown""none""confirmed" |
affected_customers_op | string | No | Selects the operator for the affected-customer comparison. This parameter and affected_customers_value must appear together. Allowed values: "<"">""=" |
affected_customers_value | integer | No | The non-negative affected-customer count for comparison. This parameter and affected_customers_op must appear together. Minimum: 0. |
mrr_op | string | No | Selects the operator for the MRR comparison. This parameter and mrr_value must appear together. Allowed values: "<"">""=" |
mrr_value | integer | No | The non-negative MRR amount for comparison, in minor currency units. This parameter and mrr_op must appear together. Minimum: 0. |
mrr_currency | string | No | A three-letter ISO currency code. If mrr_basis is source, this parameter is required. Pattern: ^[A-Z]{3}$. |
mrr_basis | string | No | Selects normalized workspace currency values or original source currency values. The default is normalized. Default: "normalized". Allowed values: "normalized""source" |
Response 200
Returns archived incidents, pagination fields, and workspace history-limit details. The filters also apply to restricted_count.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incidents | object[] | Always | The incidents in this page. |
incidents[].id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incidents[].revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incidents[].company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incidents[].human_id | string | Always | The permanent incident reference shown to users. |
incidents[].title | string | Always | The editable display title of the incident. |
incidents[].service | string | Always | The service slug associated with the incident. |
incidents[].regions | string[] | Always | The affected regions. |
incidents[].severity | string | Always | The configured severity key. |
incidents[].slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incidents[].meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incidents[].doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incidents[].status | string | Always | The configured workflow-status key. |
incidents[].status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incidents[].last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incidents[].last_event_summary | string | Always | A summary of the latest timeline event. |
incidents[].issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incidents[].severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incidents[].impact_summary | string | Always | The current customer or operational impact summary. |
incidents[].customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incidents[].impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incidents[].first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incidents[].first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incidents[].recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incidents[].duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incidents[].duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incidents[].team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incidents[].event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incidents[].investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incidents[].investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incidents[].investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incidents[].investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incidents[].investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incidents[].investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incidents[].created_at | string (RFC 3339) | Always | The incident creation time. |
incidents[].created_by | string | Always | The identifier of the user who created the incident. |
incidents[].custom_fields | object | Always | The incident values keyed by custom-field slug. |
incidents[].archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incidents[].archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incidents[].incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incidents[].incident_responders | string[] | Always | The user identifiers of assigned responders. |
incidents[].has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
has_more | boolean | Always | Deprecated top-level alias for pagination.has_more. |
next_cursor | string | Optional | Deprecated top-level alias for pagination.next_cursor. |
pagination | object | Always | Pagination details for a collection response. |
pagination.limit | integer | Always | The maximum number of items requested for this page. Minimum: 1. · Maximum: 100. |
pagination.has_more | boolean | Always | Indicates whether another page is available. |
pagination.next_cursor | string | Optional | The opaque cursor for the next page. This field is absent on the final page. |
restricted_count | integer | Optional | The number of matching incidents excluded by the workspace history limit. Minimum: 0. |
history_limited | boolean | Optional | Indicates whether the workspace history limit applies to this response. |
mrr_currency | string | Optional | The workspace reporting currency used for normalized MRR values. |
mrr_conversion_mode | string | Optional | The workspace mode for MRR currency conversion. Possible values: "normalized""source_only" |
mrr_projection_state | string | Optional | The MRR projection state. Possible values: "ready""stale""unavailable" |
supported_mrr_currencies | string[] | Optional | The ISO currency codes supported by MRR filters. |
collection_counts | object | Optional | Complete collection counts before cursor and limit when include_counts is true. |
collection_counts.matched | integer | Always | Count after every predicate, including status selection. Minimum: 0. |
collection_counts.all | integer | Always | Count after non-status predicates, excluding status, status_scope, and active_only. Minimum: 0. |
collection_counts.ongoing | integer | Always | Nonterminal count after non-status predicates. Minimum: 0. |
collection_counts.by_status | object | Always | Exact counts by normalized stored status after non-status predicates. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
GET/api/v1/incident-references/{reference}Get incident by permanent reference
#Returns an incident from its permanent, opaque reference. This endpoint is suitable for stored references and links in other systems. The numeric-ID endpoint accepts only a positive ID returned by this API.
- Operation ID
- getIncidentByReference
- Scope
- incidents:read
- Prerequisites
- None
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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,
"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
Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | Yes | A permanent, opaque reference from Tellagen incident links and messages. This parameter does not accept a numeric incident ID. Minimum length: 1 characters. |
Response 200
Returns the complete incident record. The reference continues to identify the same incident after editable fields change.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
GET/api/v1/incidents/{id}Get incident
#Returns one incident by its positive numeric ID. The permanent-reference endpoint is suitable for stored references, external links, and workflows in other systems.
- Operation ID
- getIncident
- Scope
- incidents:read
- Prerequisites
- None
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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,
"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
Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Response 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.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
PATCH/api/v1/incidents/{id}Update incident
#Updates the supplied incident fields and returns the complete incident. Omitted fields stay unchanged. Unknown fields return 400. API v1 accepts status changes through this operation for compatibility. New clients must use the resolve, close, and reopen operations. The API validates submitted timestamps against each other and stored timestamps. Automatic severity can recalculate after relevant field changes.
- Operation ID
- updateIncident
- Scope
- incidents:write
- Prerequisites
- Active responder seatIncident is not archived
- Retry guidance
- Read the current resource and reconcile changes before retrying with its current version. A stale version returns 412. Retry rules
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,
"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: Resolve incidentClose incident without resolutionReopen incident
Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Request headers
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
If-Tellagen-Resource-Version | integer | Yes | The current positive resource version from the latest response. API-key PATCH requests must send this value. Minimum: 1. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
title | string | No | The incident display title. The maximum length is 160 characters. This field is separate from impact_summary. Maximum length: 160 characters. |
service | string | No | The service slug. The maximum length is 128 characters. Maximum length: 128 characters. |
regions | string[] | No | The complete replacement list of affected regions. An empty array removes all regions. |
severity | string | No | A severity key from the workspace configuration. |
slack_channel_id | string | No | The stored Slack channel ID. |
meet_url | string | No | The absolute HTTP or HTTPS meeting URL. |
doc_url | string | No | An absolute HTTP or HTTPS URL for an incident document or source. |
status | string | No | A workflow-status key from the workspace configuration. New clients use the resolve, close, and reopen operations for lifecycle changes. |
issue_type | string | No | The work type. Existing alert records remain available for compatibility. Allowed values: "ticket""incident""postmortem" |
team_id | integer | null | No | The positive ID of an active owning team. A null value removes the current team assignment. |
severity_mode | string | No | The severity selection mode. Allowed values: "auto""manual" |
impact_summary | string | No | The customer or operational impact summary. |
customer_impact_status | string | No | The customer-impact assessment. Allowed values: "unknown""none""confirmed" |
impact_started_at | string (RFC 3339) | No | The RFC 3339 impact start time. |
first_reported_at | string (RFC 3339) | No | The RFC 3339 time of the first incident report. |
first_responded_at | string (RFC 3339) | No | The RFC 3339 time of the first response. |
recovered_at | string (RFC 3339) | No | The RFC 3339 service recovery time. |
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 means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (9)
Error responses (9)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 412
- The resource changed after the client obtained its If-Tellagen-Resource-Version value.
- 428
- An API-key PATCH request did not include the required If-Tellagen-Resource-Version header.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/resolveResolve incident
#Changes an incident to resolved and changes issue_type to postmortem. The API saves the status, optional recovery edit, and resolution note in a lifecycle event atomically. Existing postmortem drafts and versions remain unchanged. The request body is optional. A stale expected_revision returns 412. An already-resolved incident accepts an empty retry without creating another event; a retry with a note or recovery edit returns 412.
- Operation ID
- resolveIncident
- Scope
- incidents:write
- Prerequisites
- Active responder seatIncident is not archived
- Retry guidance
- Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules
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,
"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
}
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
resolution_note | string | No | An optional note stored in the resolution timeline event. Leading and trailing whitespace is removed before enforcing the 1000 Unicode character limit. |
recovered_at | string | No | The recovery timestamp in RFC 3339 format. Omit to preserve the current value. An empty string clears it. The timestamp must follow recorded impact, report, and response times and must not be in the future. |
expected_revision | integer | No | The incident revision displayed to the responder. A mismatch returns 412 without saving any changes. |
Response 200
Returns the complete incident and the committed resolution timeline event.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/closeClose incident without resolution
#Closes an incident from a non-terminal workflow status without marking it resolved. The API records the reason and comment in a lifecycle event.
- Operation ID
- closeIncident
- Scope
- incidents:write
- Prerequisites
- Active responder seatIncident is not archived
- Retry guidance
- Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules
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,
"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
}
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | Yes | The closure reason. Allowed values: "duplicate""false_alarm""test_or_accidental""not_an_incident""other" |
comment | string | Yes | The explanation for the closure. The maximum length is 1000 characters. Minimum length: 1 characters. · Maximum length: 1000 characters. |
related_incident_id | integer | Conditional | The positive ID of the primary incident. If reason is duplicate, this field is required. Required when Required when reason is "duplicate". Minimum: 1. |
Response 200
Returns the complete incident after closure.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/reopenReopen incident
#Changes a resolved or closed incident to active. A closed incident requires a comment. A comment is optional for a resolved incident. If issue_type is postmortem, the API changes it to incident.
- Operation ID
- reopenIncident
- Scope
- incidents:write
- Prerequisites
- Active responder seatIncident is not archived
- Retry guidance
- Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules
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,
"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
}
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
comment | string | Conditional | The reason for reopening. A closed incident requires this field. The maximum length is 500 characters. Required when Required when reopening a closed incident. Maximum length: 500 characters. |
Response 200
Returns the complete incident after it becomes active.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
GET/api/v1/incidents/{id}/provisioningGet incident integration setup
#Returns durable integration setup state. Pending work resumes after a server restart. Failed work retries automatically. Completed means all persisted setup steps finished.
- Operation ID
- getIncidentProvisioning
- Scope
- incidents:read
- Prerequisites
- None
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Response 200
Current setup state. Retryable indicates whether failed steps can be retried manually.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
status | string | Always | Aggregate state of persisted incident integration steps. Possible values: "pending""failed""completed" |
retryable | boolean | Always | True when a failed step can be made eligible for immediate retry. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/provisioning/retryRetry incident integration setup
#Makes failed setup steps eligible to run again. Completed steps and incident history are not repeated. The caller must have an active responder seat. Demo workspaces cannot retry external setup.
- Operation ID
- retryIncidentProvisioning
- Scope
- incidents:write
- Prerequisites
- Active responder seat
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Response 200
Current setup state. Retryable indicates whether failed steps can be retried manually.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
status | string | Always | Aggregate state of persisted incident integration steps. Possible values: "pending""failed""completed" |
retryable | boolean | Always | True when a failed step can be made eligible for immediate retry. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/archiveArchive incident
#The caller must have an active responder seat. Archiving removes the incident from default lists without changing its workflow status. A repeated request returns 204 without changing archive details, revision, changelog, or audit records. The API retains incident child records as read-only data.
- Operation ID
- archiveIncident
- Scope
- incidents:write
- Prerequisites
- Active responder seat
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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.
Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Returns 204 with no body.
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/restoreRestore incident
#The caller must have an active responder seat. Restoring returns an archived incident to default lists without changing its workflow status. A repeated request returns the active incident without changing its revision, changelog, or audit records. If the incident has team_id, that team must be active.
- Operation ID
- restoreIncident
- Scope
- incidents:write
- Prerequisites
- Active responder seat
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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,
"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
}
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Response 200
Returns the complete active incident. If its saved team is not active, the API returns 409 invalid_relationship_state.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
incident | object | Always | The complete public record for an incident. |
incident.id | integer | Always | The positive numeric ID of the incident. Minimum: 1. |
incident.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
incident.company_id | integer | Always | The ID of the workspace that owns the incident. Minimum: 1. |
incident.human_id | string | Always | The permanent incident reference shown to users. |
incident.title | string | Always | The editable display title of the incident. |
incident.service | string | Always | The service slug associated with the incident. |
incident.regions | string[] | Always | The affected regions. |
incident.severity | string | Always | The configured severity key. |
incident.slack_channel_id | string | Always | The linked Slack channel ID. An empty string means that no channel is linked. |
incident.meet_url | string | Always | The incident meeting URL. An empty string means that no meeting is linked. |
incident.doc_url | string | Always | The incident document or source URL. An empty string means that no URL is stored. |
incident.status | string | Always | The configured workflow-status key. |
incident.status_changed_at | string (RFC 3339) | null | Always | The time of the latest workflow-status change. A null value means that this time is unavailable. |
incident.last_event_at | string (RFC 3339) | null | Always | The start time of the latest timeline event. A null value means that no event exists. |
incident.last_event_summary | string | Always | A summary of the latest timeline event. |
incident.issue_type | string | Always | The work type. Possible values: "ticket""incident""postmortem" |
incident.severity_mode | string | Always | The severity selection mode. Possible values: "auto""manual" |
incident.impact_summary | string | Always | The current customer or operational impact summary. |
incident.customer_impact_status | string | Always | The customer-impact assessment. Possible values: "unknown""none""confirmed" |
incident.impact_started_at | string (RFC 3339) | null | Always | The impact start time. A null value means that the time is unknown. |
incident.first_reported_at | string (RFC 3339) | null | Always | The time of the first incident report. A null value means that the time is unknown. |
incident.first_responded_at | string (RFC 3339) | null | Always | The time of the first response. A null value means that the time is unknown. |
incident.recovered_at | string (RFC 3339) | null | Always | The service recovery time. A null value means that recovery is not recorded. |
incident.duration_seconds | integer | Always | The calculated incident duration in whole seconds. Minimum: 0. |
incident.duration_anchor | string | Always | The timestamp field from which the API calculates duration. |
incident.team_id | integer | null | Always | The owning-team ID. A null value means that the incident has no owning team. |
incident.event_count | integer | Always | The number of timeline events for the incident. Minimum: 0. |
incident.investigation_summary | object | null | Always | A summary of investigation runs. A null value means that no investigation data exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.run_count | integer | Always | The total number of investigation runs. Minimum: 0. |
incident.investigation_summary.latest_run | object | null | Always | The most recent investigation run. A null value means that no run exists. Must match exactly one of 2 schema variants. |
incident.investigation_summary.latest_run.status | string | Always | The current investigation-run status. |
incident.investigation_summary.latest_run.started_at | string (RFC 3339) | Always | The investigation-run start time. |
incident.investigation_summary.latest_run.completed_at | string (RFC 3339) | Optional | The investigation-run completion time. |
incident.created_at | string (RFC 3339) | Always | The incident creation time. |
incident.created_by | string | Always | The identifier of the user who created the incident. |
incident.custom_fields | object | Always | The incident values keyed by custom-field slug. |
incident.archived_at | string (RFC 3339) | null | Always | The incident archive time. A null value means that the incident is active. |
incident.archived_by | integer | null | Always | The user ID that archived the incident. A null value means that the incident is active. |
incident.incident_manager | string | Always | The user identifier of the incident manager. An empty string means that no manager is assigned. |
incident.incident_responders | string[] | Always | The user identifiers of assigned responders. |
incident.has_assignees | boolean | Always | Indicates whether the incident has a manager or at least one responder. |
timeline_event | object | Optional | The complete public record for a timeline event. |
timeline_event.id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.revision | integer | Always | The resource version for concurrency control. Minimum: 1. |
timeline_event.incident_id | integer | Always | The positive numeric ID of the incident. |
timeline_event.started_at | string (RFC 3339) | Always | The event start time. |
timeline_event.at | string (RFC 3339) | Always | A deprecated response alias for started_at. Both fields contain the same value. |
timeline_event.ended_at | string (RFC 3339) | null | Always | The event end time. A null value means that the event has no end time. |
timeline_event.is_ongoing | boolean | Always | Indicates whether the event is still in progress. |
timeline_event.group_id | integer | null | Always | The timeline-group ID. A null value means that the event has no group. |
timeline_event.is_key | boolean | Always | Indicates whether responders marked this as a key incident event. |
timeline_event.source | string | Always | The system or actor that created the event. |
timeline_event.source_ref | string | Always | The source-specific reference for the event. |
timeline_event.type | string | Always | The event type used for grouping and display. |
timeline_event.icon | string | Always | The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters. |
timeline_event.title | string | Always | The optional display title of the event. |
timeline_event.body | string | Always | The event description. |
timeline_event.collaboration_generation | integer | Always | The version of collaborative content associated with the event. |
timeline_event.tags | string[] | Always | The normalized event tags. |
timeline_event.ai_context | string | Always | The saved AI context for a generated event. An empty string means that no context is stored. |
timeline_event.created_by | string | Always | The identifier of the user or system that created the event. |
timeline_event.comment_count | integer | Always | The number of comments on the event. |
timeline_event.attachments | object[] | Always | The files attached to the event. |
timeline_event.attachments[].id | integer | Always | The positive numeric ID of the attachment. |
timeline_event.attachments[].timeline_event_id | integer | Always | The positive numeric ID of the timeline event. |
timeline_event.attachments[].filename | string | Always | The original file name. |
timeline_event.attachments[].url | string | Always | A temporary download URL. An empty string means that no URL is currently available. |
timeline_event.attachments[].url_available | boolean | Always | Indicates whether url contains an available download URL. |
timeline_event.attachments[].content_type | string | Always | The media type of the attached file. |
timeline_event.attachments[].size_bytes | integer | Always | The file size in bytes. |
timeline_event.attachments[].created_at | string (RFC 3339) | Always | The attachment creation time. |
timeline_event.attachments[].created_by | string | Always | The identifier of the user who attached the file. |
timeline_event.source_window_started_at | string (RFC 3339) | null | Always | The start of the source-data window. A null value means that no window is recorded. |
timeline_event.source_window_ended_at | string (RFC 3339) | null | Always | The end of the source-data window. A null value means that no window is recorded. |
timeline_event.evidence_links | object[] | Always | The evidence references associated with the event. |
timeline_event.evidence_links[].source | string | Always | The system or provider that supplied the evidence. |
timeline_event.evidence_links[].url | string | Always | The absolute URL of the evidence. |
timeline_event.evidence_links[].label | string | Optional | A short display name for the evidence. |
timeline_event.evidence_links[].summary | string | Optional | A short summary of the evidence. |
timeline_event.evidence_links[].artifact_id | string | Optional | The identifier of a stored evidence artifact. |
timeline_event.evidence_links[].artifact_digest | string | Optional | The digest used to make sure that the artifact content did not change. |
timeline_event.evidence_links[].result_bytes | integer | Optional | The original evidence result size in bytes. |
timeline_event.evidence_links[].truncated | boolean | Optional | Indicates whether the stored evidence omits part of the original result. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Tellagen-Resource-Version | integer | Always | The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1. |
Errors and recovery (7)
Error responses (7)
- 400
- The API rejected the request because its syntax or one of its values is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/rename-slack-channelReapply the Slack channel-name template (deprecated)
#This operation is deprecated. It reapplies the workspace channel-name template. It rejects every request body, including whitespace. The replacement is PATCH /api/v1/incidents/{id}/slack/channel-name with mode workspace_template. Every response includes the RFC 9745 Deprecation date and a link to the replacement operation. The Sunset header is absent because Tellagen has not set an end date.
- Operation ID
- syncIncidentSlackChannelName
- Scope
- incidents:write
- Retry guidance
- Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules
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"
}Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Response 200
Returns the new Slack channel name.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
channel_name | string | Always | The new Slack channel name. |
Response headers
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
Deprecation | string | Always | The date of the deprecation announcement in RFC 9745 format. Pattern: ^@[0-9]+$. |
Link | string | Always | A link to the replacement operation with rel="successor-version". |
Errors and recovery (7)
Error responses (7)
- 400
- The compatibility action received a non-empty request body.
- 401
- Authentication failed.
- 403
- The API key lacks access or an active responder seat.
- 404
- The incident does not exist.
- 409
- Slack is not configured, the linked channel is missing, the incident is immutable, or the resolved name is already used.
- 429
- The workspace rate limit is exceeded.
- 500
- An internal server error prevented completion of the request.
POST/api/v1/incidents/{id}/slack/channel-name/previewPreview an incident Slack channel name
#Calculates and validates the channel name without renaming the Slack channel or creating an audit record. The workspace_template mode must omit name. The custom mode requires name.
- Operation ID
- previewIncidentSlackChannelName
- Scope
- incidents:write
- Retry guidance
- This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules
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
Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | Selects how the API creates the Slack channel name. Must match exactly one of 2 schema variants. Allowed values: "workspace_template""custom" |
name | string | Conditional | The proposed channel name for custom mode. It must contain an ASCII letter or digit. The preview and update operations normalize it identically. Required when Required when mode is "custom". Minimum length: 1 characters. · Pattern: .*[A-Za-z0-9].*. |
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 means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
channel_id | string | Always | The Slack channel ID. |
previous_name | string | Always | The channel name before the request. |
new_name | string | Always | The validated channel name. The maximum length is 80 characters. Minimum length: 1 characters. · Maximum length: 80 characters. |
mode | string | Always | The naming mode. Possible values: "workspace_template""custom" |
Errors and recovery (7)
Error responses (7)
- 400
- The naming request is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- Slack is not configured, the linked channel is missing, or the resolved name is already used.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.
PATCH/api/v1/incidents/{id}/slack/channel-nameUpdate an incident Slack channel name
#Renames the linked Slack channel with workspace_template or custom mode. The API saves the old name, new name, mode, actor, and time in the incident audit log. It also publishes the saved audit entry as an incident event. If the audit save fails after Slack renames the channel, the API tries to restore the old name and returns an error.
- Operation ID
- updateIncidentSlackChannelName
- Scope
- incidents:write
- Retry guidance
- Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules
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
Request and response contract
Path parameters
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1. |
Request body
Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.
| Field | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | Selects how the API creates the Slack channel name. Must match exactly one of 2 schema variants. Allowed values: "workspace_template""custom" |
name | string | Conditional | The proposed channel name for custom mode. It must contain an ASCII letter or digit. The preview and update operations normalize it identically. Required when Required when mode is "custom". Minimum length: 1 characters. · Pattern: .*[A-Za-z0-9].*. |
Response 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.
Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.
| Field | Type | Returned | Description |
|---|---|---|---|
channel_id | string | Always | The Slack channel ID. |
previous_name | string | Always | The channel name before the request. |
new_name | string | Always | The validated channel name. The maximum length is 80 characters. Minimum length: 1 characters. · Maximum length: 80 characters. |
mode | string | Always | The naming mode. Possible values: "workspace_template""custom" |
Errors and recovery (7)
Error responses (7)
- 400
- The naming request is invalid.
- 401
- The request does not contain valid authentication.
- 403
- Authentication succeeded, but the caller lacks the required API scope or workspace permission.
- 404
- The requested resource does not exist or is not available to the caller.
- 409
- Slack is not configured, the linked channel is missing, or the resolved name is already used.
- 429
- The workspace exceeded an active request limit.
- 500
- An internal server error prevented completion of the request.