API ReferenceTimeline

Timeline

Record updates, decisions, and evidence on an incident timeline.

Search API docsAll documentation

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

MethodScope

Endpoints

List timeline events

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

Lists timeline events from oldest to newest by default. Descending order reverses the time and ID order.

Different filters must all match. Multiple tags or groups match any selected value. The time range includes started_from and excludes started_to.

The matched_count field counts all matching events before pagination. The filter_counts field gives suggestions based only on the time range. The latest_started_at field gives the latest event time across the incident.

Use the returned cursor with the same incident, filters, and order. Changes between requests can move events between pages.

Required scope: incidents:read

Example request

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

bash

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

Success: 200

Returns timeline events, pagination fields, and counts for the complete filtered collection.

Success response JSON

json

{
  "events": [
    {
      "id": 100,
      "revision": 4,
      "incident_id": 1,
      "started_at": "2026-08-31T12:10:00Z",
      "at": "2026-08-31T12:10:00Z",
      "ended_at": null,
      "is_ongoing": false,
      "group_id": null,
      "is_key": false,
      "source": "api",
      "source_ref": "api:123:deploy-42",
      "type": "change",
      "icon": "🔧",
      "title": "Payment service restart",
      "body": "Restarted the payment service.",
      "collaboration_generation": 0,
      "tags": [],
      "ai_context": "",
      "created_by": "[email protected]",
      "comment_count": 0,
      "attachments": [
        {
          "id": 501,
          "timeline_event_id": 100,
          "filename": "restart-log.txt",
          "url": "https://files.example.com/signed/restart-log.txt",
          "url_available": true,
          "content_type": "text/plain",
          "size_bytes": 2048,
          "created_at": "2026-08-31T12:11:00Z",
          "created_by": "[email protected]"
        }
      ],
      "source_window_started_at": null,
      "source_window_ended_at": null,
      "evidence_links": []
    }
  ],
  "filter_counts": {
    "all_events": 1,
    "recorded_events": 1,
    "key_events": 0,
    "type_counts": {
      "change": 1
    },
    "source_counts": {
      "api": 1
    },
    "tag_counts": {}
  },
  "matched_count": 1,
  "latest_started_at": "2026-08-31T12:10:00Z",
  "has_more": false,
  "pagination": {
    "limit": 50,
    "has_more": false
  }
}

Parameters, headers, and fields

Operation ID: listTimelineEvents

Path parameters

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

Query parameters

Query parameters
Field	Description
`limit` integer Optional	The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50.
`cursor` string Optional	The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters.
`order` string Optional	Sort direction for both started_at and id. Default: "asc". Allowed values: `"asc""desc"`
`type_or_source` string Optional	Case-insensitive type or source, with outer whitespace ignored. ai matches sources ai, ai_investigation, investigation, or type investigation with source manual.
`tag` string[] Optional	Match any repeated tag case-insensitively. Tag whitespace is significant.
`key_only` boolean Optional	Include only key events when true. Accepts true or false. Default: false.
`group` integer \| string[] Optional	Match any repeated positive group ID or ungrouped for null group. Allowed values: `"ungrouped"`
`q` string Optional	Literal case-insensitive substring of title, body, ai_context, space-joined tags or group name; outer query whitespace is ignored. Percent and underscore are literal characters. Fields match independently. Null group text is no group ungrouped; empty or unavailable group name is unknown group followed by a hash and its ID.
`suggestions` string Optional	Include, exclude or select only ai_suggested events, identified by lowercase type without trimming. Only mode applies other predicates only when explicitly supplied; it does not inherit workspace filters. Default: "include". Allowed values: `"include""exclude""only"`
`started_from` string (RFC 3339) Optional	Includes events with started_at equal to or later than this RFC 3339 time.
`started_to` string (RFC 3339) Optional	Includes events with started_at earlier than this RFC 3339 time.

Response `200`

Returns timeline events, pagination fields, and counts for the complete filtered collection.

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

Response fields
Field	Description
`events` object[] Always returned	The timeline events in this page.
`events[].id` integer Always returned	The positive numeric ID of the timeline event.
`events[].revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`events[].incident_id` integer Always returned	The positive numeric ID of the incident.
`events[].started_at` string (RFC 3339) Always returned	The event start time.
`events[].at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`events[].ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`events[].is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`events[].group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`events[].is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`events[].source` string Always returned	The system or actor that created the event.
`events[].source_ref` string Always returned	The source-specific reference for the event.
`events[].type` string Always returned	The event type used for grouping and display.
`events[].icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`events[].title` string Always returned	The optional display title of the event.
`events[].body` string Always returned	The event description.
`events[].collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`events[].tags` string[] Always returned	The normalized event tags.
`events[].ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`events[].created_by` string Always returned	The identifier of the user or system that created the event.
`events[].comment_count` integer Always returned	The number of comments on the event.
`events[].attachments` object[] Always returned	The files attached to the event.
`events[].attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`events[].attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`events[].attachments[].filename` string Always returned	The original file name.
`events[].attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`events[].attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`events[].attachments[].content_type` string Always returned	The media type of the attached file.
`events[].attachments[].size_bytes` integer Always returned	The file size in bytes.
`events[].attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`events[].attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`events[].source_window_started_at` string (RFC 3339) \| null Always returned	The start of the source-data window. A null value means that no window is recorded.
`events[].source_window_ended_at` string (RFC 3339) \| null Always returned	The end of the source-data window. A null value means that no window is recorded.
`events[].evidence_links` object[] Always returned	The evidence references associated with the event.
`events[].evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`events[].evidence_links[].url` string Always returned	The absolute URL of the evidence.
`events[].evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`events[].evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`events[].evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`events[].evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`events[].evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`events[].evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`events[].operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`events[].operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`events[].operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`events[].operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`events[].operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`events[].operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`events[].operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`events[].operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`events[].operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`
`filter_counts` object Always returned	Counts for all events that match the timeline time filters.
`filter_counts.all_events` integer Always returned	The total number of events in the time-filtered collection, including AI suggestions.
`filter_counts.recorded_events` integer Always returned	The number of events in the time-filtered collection that are not AI suggestions. It matches matched_count for suggestions=exclude with no other filters. Minimum: 0.
`filter_counts.key_events` integer Always returned	The number of key events in the time-filtered collection that are not AI suggestions. Minimum: 0.
`filter_counts.type_counts` object Always returned	Event counts keyed by event type.
`filter_counts.source_counts` object Always returned	Event counts keyed by event source.
`filter_counts.tag_counts` object Always returned	Event counts keyed by tag.
`matched_count` integer Always returned	Complete active predicate count before cursor and limit. Minimum: 0.
`latest_started_at` string (RFC 3339) \| null Always returned	Latest started_at in the incident independent of filters; null for an empty incident.
`has_more` boolean Always returned	Indicates whether another page is available.
`next_cursor` string Sometimes returned	The opaque cursor for the next page. This field is absent on the final page.
`pagination` object Always returned	Pagination details for a collection response.
`pagination.limit` integer Always returned	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more` boolean Always returned	Indicates whether another page is available.
`pagination.next_cursor` string Sometimes returned	The opaque cursor for the next page. This field is absent on the final page.

Errors and recovery (7)

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

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Create timeline event

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

Creates a timeline event. Include operational_update with type operational_update to record a structured human-authored status snapshot; the API derives its delivery_state and canonical body. Add share to a status update to also post it to Slack as it is recorded; the API stores the update and one delivery per destination together, returns the deliveries, and posts in the background (status_update_delivery_disabled when the workspace has not turned delivery on). For API-key requests, the API sets source to api. The API controls source, AI context, evidence provenance, and reserved event types.

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

Example request

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

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/{id}/timeline' \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "body": "Restarted the payment service.",
  "started_at": "2026-08-31T12:10:00Z",
  "type": "change",
  "icon": "🔧",
  "external_reference": "deploy-42"
}'

Success: 201

Returns the created timeline event.

Success response JSON

json

{
  "event": {
    "id": 100,
    "revision": 4,
    "incident_id": 1,
    "started_at": "2026-08-31T12:10:00Z",
    "at": "2026-08-31T12:10:00Z",
    "ended_at": null,
    "is_ongoing": false,
    "group_id": null,
    "is_key": false,
    "source": "api",
    "source_ref": "api:123:deploy-42",
    "type": "change",
    "icon": "🔧",
    "title": "Payment service restart",
    "body": "Restarted the payment service.",
    "collaboration_generation": 0,
    "tags": [],
    "ai_context": "",
    "created_by": "[email protected]",
    "comment_count": 0,
    "attachments": [
      {
        "id": 501,
        "timeline_event_id": 100,
        "filename": "restart-log.txt",
        "url": "https://files.example.com/signed/restart-log.txt",
        "url_available": true,
        "content_type": "text/plain",
        "size_bytes": 2048,
        "created_at": "2026-08-31T12:11:00Z",
        "created_by": "[email protected]"
      }
    ],
    "source_window_started_at": null,
    "source_window_ended_at": null,
    "evidence_links": []
  }
}

Parameters, headers, and fields

Operation ID: createTimelineEvent

Path parameters

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

Request headers

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

Request body

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

Request body fields
Field	Description
`body` string Required	The event description. It must contain at least one non-space character. Minimum length: 1 characters.
`started_at` string (RFC 3339) Optional	The RFC 3339 start time. If the request omits started_at, the API uses the current time.
`at` string (RFC 3339) Optional	A deprecated request alias for started_at. If both fields are present, their values must match.
`ended_at` string (RFC 3339) Optional	The RFC 3339 end time. It must be later than started_at.
`is_ongoing` boolean Optional	Controls whether the event is ongoing. If this value is true, ended_at must be omitted.
`group_id` integer \| null Optional	The positive timeline-group ID for this incident. A null value creates an event without a group.
`is_key` boolean Optional	Controls whether responders see this as a key incident event.
`type` string Optional	The client-defined event type. The API rejects event types reserved for generated events.
`icon` string Optional	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`title` string Optional	The optional display title of the event.
`tags` string[] Optional	The event tags. The API normalizes each value.
`external_reference` string Optional	A client correlation reference for API-key requests. The API trims, limits, and namespaces the value. The maximum length is 200 characters. Maximum length: 200 characters.
`operational_update` object \| null Optional	The structured human-authored status payload. Use this only with type operational_update; delivery_state is derived by the server and cannot be supplied here. A null value is treated as absent. Must match exactly one of 2 schema variants.
`operational_update.current_impact` string Required	The current customer or system impact in human-authored text. Minimum length: 1 characters. · Maximum length: 2000 characters.
`operational_update.current_action` string Required	The response work currently in progress. Minimum length: 1 characters. · Maximum length: 2000 characters.
`operational_update.next_update_at` string (RFC 3339) \| null Required	The planned next update time as RFC 3339
`operational_update.audience` string Required	The intended audience for the status update. Allowed values: `"responders""stakeholders""customers"`
`operational_update.channel` string Required	Use manual_external only when the caller will deliver the copied message themselves. Allowed values: `"incident_record""manual_external"`
`operational_update.destination` string Required	Required for manual_external and empty for incident_record. Maximum length: 200 characters.
`operational_update.communications_owner_user_id` integer \| null Required	An active incident participant responsible for coordinating manual delivery
`share` object Optional	Where to deliver a status update as it is recorded. It is request-only: the API stores one delivery per destination, never the share itself. It needs type operational_update with channel incident_record. Other Slack channels must be announcement channels an admin configured in Settings → Status updates. Email goes to workspace members at once; any other address first confirms once by email, and its delivery waits as awaiting_confirmation. Email needs the status_updates:email scope (403 status_update_email_scope_required), and an API key can name email groups only (403 status_update_adhoc_email_api_key for email_addresses).
`share.slack_incident_channel` boolean Optional	Posts a new message to the incident's Slack channel. The incident must have a channel (status_update_no_incident_channel).
`share.slack_channel_ids` string[] Optional	Announcement channels to post to as well, by Slack channel ID. Each must be configured in Settings → Status updates; any other channel is rejected with status_update_channel_not_configured. Tellagen never joins these channels, and later updates for the same incident reply in the thread of its latest post there. Maximum items: 5.
`share.email_group_ids` integer[] Optional	Email groups from Settings → Status updates. An unknown or deleted group is rejected with status_update_email_group_not_found. One update emails at most 100 people (status_update_too_many_recipients). An address that unsubscribed, bounced or complained gets a suppressed delivery, never an email. Maximum items: 50.
`share.email_addresses` string[] Optional	Addresses typed in while posting (sessions only). They need the workspace rule that allows them (status_update_adhoc_email_not_allowed), and external addresses need a paid plan and the confirmed-external rule (status_update_external_email_not_allowed). At most 20 (status_update_too_many_recipients). Maximum items: 20.

Response `201`

Returns the created timeline event.

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

Response fields
Field	Description
`event` object Always returned	The complete public record for a timeline event.
`event.id` integer Always returned	The positive numeric ID of the timeline event.
`event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`event.incident_id` integer Always returned	The positive numeric ID of the incident.
`event.started_at` string (RFC 3339) Always returned	The event start time.
`event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`event.source` string Always returned	The system or actor that created the event.
`event.source_ref` string Always returned	The source-specific reference for the event.
`event.type` string Always returned	The event type used for grouping and display.
`event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`event.title` string Always returned	The optional display title of the event.
`event.body` string Always returned	The event description.
`event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`event.tags` string[] Always returned	The normalized event tags.
`event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`event.created_by` string Always returned	The identifier of the user or system that created the event.
`event.comment_count` integer Always returned	The number of comments on the event.
`event.attachments` object[] Always returned	The files attached to the event.
`event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`event.attachments[].filename` string Always returned	The original file name.
`event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`event.attachments[].content_type` string Always returned	The media type of the attached file.
`event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`event.source_window_started_at` string (RFC 3339) \| null Always returned	The start of the source-data window. A null value means that no window is recorded.
`event.source_window_ended_at` string (RFC 3339) \| null Always returned	The end of the source-data window. A null value means that no window is recorded.
`event.evidence_links` object[] Always returned	The evidence references associated with the event.
`event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`
`deliveries` object[] Sometimes returned	The destinations recorded with a shared status update, one per destination. Only the create response of a request with share includes it.
`deliveries[].id` integer Always returned	The delivery ID.
`deliveries[].timeline_event_id` integer Always returned	The status update this delivery belongs to.
`deliveries[].incident_id` integer Always returned	The incident ID.
`deliveries[].kind` string Always returned	The provider. Possible values: `"slack""email"`
`deliveries[].destination` string Always returned	Why the destination was chosen. Possible values: `"incident_channel""announcement_channel""email"`
`deliveries[].target` string Always returned	The Slack channel ID.
`deliveries[].target_label` string Always returned	The Slack channel name without #, when known; otherwise empty.
`deliveries[].status` string Always returned	queued waits for its first or next attempt; sending is being posted; sent is delivered; failed needs a person (for example, invite the app) and is retried only on request; dead stopped after the attempt limit or 2 hours; skipped was never attempted (a demo workspace or Slack not connected). Possible values: `"queued""sending""sent""failed""dead""skipped""awaiting_confirmation""suppressed"`
`deliveries[].attempts` integer Always returned	The number of attempts so far. Minimum: 0.
`deliveries[].next_attempt_at` string (RFC 3339) \| null Always returned	When a queued delivery is attempted next; null in every other state.
`deliveries[].permalink` string Always returned	The Slack message link once sent; otherwise empty.
`deliveries[].error_code` string Always returned	Why the delivery is not sent, such as not_in_channel, channel_not_found, channel_archived, slack_auth, slack_not_connected, rate_limited, temporary, expired, not_configured (the announcement channel was removed in Settings before the post went out), or demo. Empty when nothing is wrong.
`deliveries[].error_message` string Always returned	The reason in words
`deliveries[].can_retry` boolean Always returned	True for a failed or dead Slack delivery.
`deliveries[].sent_at` string (RFC 3339) \| null Always returned	When the delivery was sent.
`deliveries[].created_at` string (RFC 3339) Always returned	When the update was recorded with this destination.
`deliveries[].updated_at` string (RFC 3339) Always returned	When the delivery state last changed.

Response headers

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

Errors and recovery (7)

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

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

idempotency_key_reused idempotency_in_progress idempotency_outcome_unknown

Get timeline event

GET/api/v1/timeline/{id}

Returns one timeline event. Attachment download URLs expire. If url_available is false or a URL expires, a new GET request can return a new URL.

Required scope: incidents:read

Example request

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

bash

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

Success: 200

Returns the timeline event.

Success response JSON

json

{
  "event": {
    "id": 100,
    "revision": 4,
    "incident_id": 1,
    "started_at": "2026-08-31T12:10:00Z",
    "at": "2026-08-31T12:10:00Z",
    "ended_at": null,
    "is_ongoing": false,
    "group_id": null,
    "is_key": false,
    "source": "api",
    "source_ref": "api:123:deploy-42",
    "type": "change",
    "icon": "🔧",
    "title": "Payment service restart",
    "body": "Restarted the payment service.",
    "collaboration_generation": 0,
    "tags": [],
    "ai_context": "",
    "created_by": "[email protected]",
    "comment_count": 0,
    "attachments": [
      {
        "id": 501,
        "timeline_event_id": 100,
        "filename": "restart-log.txt",
        "url": "https://files.example.com/signed/restart-log.txt",
        "url_available": true,
        "content_type": "text/plain",
        "size_bytes": 2048,
        "created_at": "2026-08-31T12:11:00Z",
        "created_by": "[email protected]"
      }
    ],
    "source_window_started_at": null,
    "source_window_ended_at": null,
    "evidence_links": []
  }
}

Parameters, headers, and fields

Operation ID: getTimelineEvent

Path parameters

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

Response `200`

Returns the timeline event.

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

Response fields
Field	Description
`event` object Always returned	The complete public record for a timeline event.
`event.id` integer Always returned	The positive numeric ID of the timeline event.
`event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`event.incident_id` integer Always returned	The positive numeric ID of the incident.
`event.started_at` string (RFC 3339) Always returned	The event start time.
`event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`event.source` string Always returned	The system or actor that created the event.
`event.source_ref` string Always returned	The source-specific reference for the event.
`event.type` string Always returned	The event type used for grouping and display.
`event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`event.title` string Always returned	The optional display title of the event.
`event.body` string Always returned	The event description.
`event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`event.tags` string[] Always returned	The normalized event tags.
`event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`event.created_by` string Always returned	The identifier of the user or system that created the event.
`event.comment_count` integer Always returned	The number of comments on the event.
`event.attachments` object[] Always returned	The files attached to the event.
`event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`event.attachments[].filename` string Always returned	The original file name.
`event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`event.attachments[].content_type` string Always returned	The media type of the attached file.
`event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`event.source_window_started_at` string (RFC 3339) \| null Always returned	The start of the source-data window. A null value means that no window is recorded.
`event.source_window_ended_at` string (RFC 3339) \| null Always returned	The end of the source-data window. A null value means that no window is recorded.
`event.evidence_links` object[] Always returned	The evidence references associated with the event.
`event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`
`deliveries` object[] Sometimes returned	The destinations recorded with a shared status update, one per destination. Only the create response of a request with share includes it.
`deliveries[].id` integer Always returned	The delivery ID.
`deliveries[].timeline_event_id` integer Always returned	The status update this delivery belongs to.
`deliveries[].incident_id` integer Always returned	The incident ID.
`deliveries[].kind` string Always returned	The provider. Possible values: `"slack""email"`
`deliveries[].destination` string Always returned	Why the destination was chosen. Possible values: `"incident_channel""announcement_channel""email"`
`deliveries[].target` string Always returned	The Slack channel ID.
`deliveries[].target_label` string Always returned	The Slack channel name without #, when known; otherwise empty.
`deliveries[].status` string Always returned	queued waits for its first or next attempt; sending is being posted; sent is delivered; failed needs a person (for example, invite the app) and is retried only on request; dead stopped after the attempt limit or 2 hours; skipped was never attempted (a demo workspace or Slack not connected). Possible values: `"queued""sending""sent""failed""dead""skipped""awaiting_confirmation""suppressed"`
`deliveries[].attempts` integer Always returned	The number of attempts so far. Minimum: 0.
`deliveries[].next_attempt_at` string (RFC 3339) \| null Always returned	When a queued delivery is attempted next; null in every other state.
`deliveries[].permalink` string Always returned	The Slack message link once sent; otherwise empty.
`deliveries[].error_code` string Always returned	Why the delivery is not sent, such as not_in_channel, channel_not_found, channel_archived, slack_auth, slack_not_connected, rate_limited, temporary, expired, not_configured (the announcement channel was removed in Settings before the post went out), or demo. Empty when nothing is wrong.
`deliveries[].error_message` string Always returned	The reason in words
`deliveries[].can_retry` boolean Always returned	True for a failed or dead Slack delivery.
`deliveries[].sent_at` string (RFC 3339) \| null Always returned	When the delivery was sent.
`deliveries[].created_at` string (RFC 3339) Always returned	When the update was recorded with this destination.
`deliveries[].updated_at` string (RFC 3339) Always returned	When the delivery state last changed.

Response headers

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

Errors and recovery (7)

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

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Update timeline event

PATCH/api/v1/timeline/{id}

Validates the final event state, then updates the supplied fields. Typed operational status snapshots are immutable; attempts to change their body, title, type, or start time return a validation error and the caller should post another status update. If the request changes no value, the API returns 400 without side effects.

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

Example request

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

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

bash

curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/timeline/{id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'If-Tellagen-Resource-Version: <resource-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "body": "Restarted the payment service and confirmed recovery.",
  "ended_at": "2026-08-31T12:18:00Z"
}'

Success: 200

Returns the updated timeline event.

Success response JSON

json

{
  "event": {
    "id": 100,
    "revision": 4,
    "incident_id": 1,
    "started_at": "2026-08-31T12:10:00Z",
    "at": "2026-08-31T12:10:00Z",
    "ended_at": "2026-08-31T12:18:00Z",
    "is_ongoing": false,
    "group_id": null,
    "is_key": false,
    "source": "api",
    "source_ref": "api:123:deploy-42",
    "type": "change",
    "icon": "🔧",
    "title": "Payment service restart",
    "body": "Restarted the payment service and confirmed recovery.",
    "collaboration_generation": 0,
    "tags": [],
    "ai_context": "",
    "created_by": "[email protected]",
    "comment_count": 0,
    "attachments": [
      {
        "id": 501,
        "timeline_event_id": 100,
        "filename": "restart-log.txt",
        "url": "https://files.example.com/signed/restart-log.txt",
        "url_available": true,
        "content_type": "text/plain",
        "size_bytes": 2048,
        "created_at": "2026-08-31T12:11:00Z",
        "created_by": "[email protected]"
      }
    ],
    "source_window_started_at": null,
    "source_window_ended_at": null,
    "evidence_links": []
  }
}

Parameters, headers, and fields

Operation ID: updateTimelineEvent

Path parameters

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

Request headers

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

Request body

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

Request body fields
Field	Description
`body` string Optional	The replacement event description. It must contain at least one non-space character. Minimum length: 1 characters.
`title` string Optional	The replacement event title. An empty string removes the title.
`started_at` string (RFC 3339) Optional	The replacement RFC 3339 start time.
`at` string (RFC 3339) Optional	A deprecated request alias for started_at. If both fields are present, their values must match.
`ended_at` string (RFC 3339) Optional	The replacement RFC 3339 end time. It must be later than started_at.
`clear_ended_at` boolean Optional	A true value removes ended_at.
`is_ongoing` boolean Optional	Controls whether the event is ongoing.
`group_id` integer \| null Optional	The positive timeline-group ID. A null value removes the event from its current group.
`is_key` boolean Optional	Controls whether responders see this as a key incident event.
`type` string Optional	The client-defined event type. The API rejects event types reserved for generated events.
`icon` string Optional	The replacement event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`tags` string[] Optional	The complete replacement list of event tags. The API normalizes each value.

Response `200`

Returns the updated timeline event.

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

Response fields
Field	Description
`event` object Always returned	The complete public record for a timeline event.
`event.id` integer Always returned	The positive numeric ID of the timeline event.
`event.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`event.incident_id` integer Always returned	The positive numeric ID of the incident.
`event.started_at` string (RFC 3339) Always returned	The event start time.
`event.at` string (RFC 3339) Always returned	A deprecated response alias for started_at. Both fields contain the same value.
`event.ended_at` string (RFC 3339) \| null Always returned	The event end time. A null value means that the event has no end time.
`event.is_ongoing` boolean Always returned	Indicates whether the event is still in progress.
`event.group_id` integer \| null Always returned	The timeline-group ID. A null value means that the event has no group.
`event.is_key` boolean Always returned	Indicates whether responders marked this as a key incident event.
`event.source` string Always returned	The system or actor that created the event.
`event.source_ref` string Always returned	The source-specific reference for the event.
`event.type` string Always returned	The event type used for grouping and display.
`event.icon` string Always returned	The event icon. The maximum length is 8 Unicode characters. Maximum length: 8 characters.
`event.title` string Always returned	The optional display title of the event.
`event.body` string Always returned	The event description.
`event.collaboration_generation` integer Always returned	The version of collaborative content associated with the event.
`event.tags` string[] Always returned	The normalized event tags.
`event.ai_context` string Always returned	The saved AI context for a generated event. An empty string means that no context is stored.
`event.created_by` string Always returned	The identifier of the user or system that created the event.
`event.comment_count` integer Always returned	The number of comments on the event.
`event.attachments` object[] Always returned	The files attached to the event.
`event.attachments[].id` integer Always returned	The positive numeric ID of the attachment.
`event.attachments[].timeline_event_id` integer Always returned	The positive numeric ID of the timeline event.
`event.attachments[].filename` string Always returned	The original file name.
`event.attachments[].url` string Always returned	A temporary download URL. An empty string means that no URL is currently available.
`event.attachments[].url_available` boolean Always returned	Indicates whether url contains an available download URL.
`event.attachments[].content_type` string Always returned	The media type of the attached file.
`event.attachments[].size_bytes` integer Always returned	The file size in bytes.
`event.attachments[].created_at` string (RFC 3339) Always returned	The attachment creation time.
`event.attachments[].created_by` string Always returned	The identifier of the user who attached the file.
`event.source_window_started_at` string (RFC 3339) \| null Always returned	The start of the source-data window. A null value means that no window is recorded.
`event.source_window_ended_at` string (RFC 3339) \| null Always returned	The end of the source-data window. A null value means that no window is recorded.
`event.evidence_links` object[] Always returned	The evidence references associated with the event.
`event.evidence_links[].source` string Always returned	The system or provider that supplied the evidence.
`event.evidence_links[].url` string Always returned	The absolute URL of the evidence.
`event.evidence_links[].label` string Sometimes returned	A short display name for the evidence.
`event.evidence_links[].summary` string Sometimes returned	A short summary of the evidence.
`event.evidence_links[].artifact_id` string Sometimes returned	The identifier of a stored evidence artifact.
`event.evidence_links[].artifact_digest` string Sometimes returned	The digest used to make sure that the artifact content did not change.
`event.evidence_links[].result_bytes` integer Sometimes returned	The original evidence result size in bytes.
`event.evidence_links[].truncated` boolean Sometimes returned	Indicates whether the stored evidence omits part of the original result.
`event.operational_update` object \| null Sometimes returned	The validated operational status payload. Null or absent for ordinary and legacy timeline events. Must match exactly one of 2 schema variants.
`event.operational_update.current_impact` string Always returned	The current customer or system impact in human-authored text. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`event.operational_update.current_action` string Always returned	The response work currently in progress. Leading and trailing whitespace is removed before the Unicode length limit is enforced. Minimum length: 1 characters. · Maximum length: 2000 characters.
`event.operational_update.next_update_at` string (RFC 3339) \| null Always returned	The planned next update time as RFC 3339
`event.operational_update.audience` string Always returned	The intended audience for the status update. Possible values: `"responders""stakeholders""customers"`
`event.operational_update.channel` string Always returned	Records the destination workflow. manual_external means the caller must deliver the copied message themselves. Possible values: `"incident_record""manual_external"`
`event.operational_update.destination` string Always returned	The human-readable external destination for manual_external Maximum length: 200 characters.
`event.operational_update.communications_owner_user_id` integer \| null Always returned	The active incident participant responsible for coordinating manual delivery
`event.operational_update.delivery_state` string Always returned	The server-derived delivery state. Tellagen does not claim that a manual external message was sent. Possible values: `"recorded""pending_manual_delivery"`
`deliveries` object[] Sometimes returned	The destinations recorded with a shared status update, one per destination. Only the create response of a request with share includes it.
`deliveries[].id` integer Always returned	The delivery ID.
`deliveries[].timeline_event_id` integer Always returned	The status update this delivery belongs to.
`deliveries[].incident_id` integer Always returned	The incident ID.
`deliveries[].kind` string Always returned	The provider. Possible values: `"slack""email"`
`deliveries[].destination` string Always returned	Why the destination was chosen. Possible values: `"incident_channel""announcement_channel""email"`
`deliveries[].target` string Always returned	The Slack channel ID.
`deliveries[].target_label` string Always returned	The Slack channel name without #, when known; otherwise empty.
`deliveries[].status` string Always returned	queued waits for its first or next attempt; sending is being posted; sent is delivered; failed needs a person (for example, invite the app) and is retried only on request; dead stopped after the attempt limit or 2 hours; skipped was never attempted (a demo workspace or Slack not connected). Possible values: `"queued""sending""sent""failed""dead""skipped""awaiting_confirmation""suppressed"`
`deliveries[].attempts` integer Always returned	The number of attempts so far. Minimum: 0.
`deliveries[].next_attempt_at` string (RFC 3339) \| null Always returned	When a queued delivery is attempted next; null in every other state.
`deliveries[].permalink` string Always returned	The Slack message link once sent; otherwise empty.
`deliveries[].error_code` string Always returned	Why the delivery is not sent, such as not_in_channel, channel_not_found, channel_archived, slack_auth, slack_not_connected, rate_limited, temporary, expired, not_configured (the announcement channel was removed in Settings before the post went out), or demo. Empty when nothing is wrong.
`deliveries[].error_message` string Always returned	The reason in words
`deliveries[].can_retry` boolean Always returned	True for a failed or dead Slack delivery.
`deliveries[].sent_at` string (RFC 3339) \| null Always returned	When the delivery was sent.
`deliveries[].created_at` string (RFC 3339) Always returned	When the update was recorded with this destination.
`deliveries[].updated_at` string (RFC 3339) Always returned	When the delivery state last changed.

Response headers

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

Errors and recovery (9)

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

Error responses (9)

400 401 403 404 409 412 428 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
412: The resource changed after the client obtained its If-Tellagen-Resource-Version value.
428: An API-key PATCH request did not include the required If-Tellagen-Resource-Version header.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Delete timeline event

DELETE/api/v1/timeline/{id}

Deletes the event and its attachment records. The API removes stored attachment objects asynchronously. Findings promoted from the event return to draft. A repeated request returns 404. Concurrent attachment changes return 409. The request is safe to retry after this conflict.

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

Example request

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

bash

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

Success: 204

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

Parameters, headers, and fields

Operation ID: deleteTimelineEvent

Path parameters

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

Returns 204 with no body.

Errors and recovery (7)

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

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

List status update deliveries

GET/api/v1/timeline/{id}/deliveries

Returns where a status update was delivered, one row per destination, with its live state. A timeline event that was recorded without share returns an empty list.

This API is in preview while email delivery is added.

Required scope: incidents:read

Example request

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

bash

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

Success: 200

Returns the status update's deliveries.

Success response JSON

json

{
  "timeline_event_id": 100,
  "incident_id": 1,
  "deliveries": [
    {
      "id": 7,
      "timeline_event_id": 100,
      "incident_id": 1,
      "kind": "slack",
      "destination": "incident_channel",
      "target": "C0123ABCD",
      "target_label": "inc-1516",
      "status": "sent",
      "attempts": 1,
      "next_attempt_at": null,
      "permalink": "https://example.slack.com/archives/C0123ABCD/p1788134400000100",
      "error_code": "",
      "error_message": "",
      "can_retry": false,
      "sent_at": "2026-08-31T12:10:04Z",
      "created_at": "2026-08-31T12:10:00Z",
      "updated_at": "2026-08-31T12:10:04Z"
    }
  ]
}

Parameters, headers, and fields

Operation ID: listStatusUpdateDeliveries

Path parameters

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

Response `200`

Returns the status update's deliveries.

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

Response fields
Field	Description
`timeline_event_id` integer Always returned	The status update's timeline event ID.
`incident_id` integer Always returned	The incident ID.
`deliveries` object[] Always returned	One row per destination, incident channel first. Empty when the update was recorded without sharing.
`deliveries[].id` integer Always returned	The delivery ID.
`deliveries[].timeline_event_id` integer Always returned	The status update this delivery belongs to.
`deliveries[].incident_id` integer Always returned	The incident ID.
`deliveries[].kind` string Always returned	The provider. Possible values: `"slack""email"`
`deliveries[].destination` string Always returned	Why the destination was chosen. Possible values: `"incident_channel""announcement_channel""email"`
`deliveries[].target` string Always returned	The Slack channel ID.
`deliveries[].target_label` string Always returned	The Slack channel name without #, when known; otherwise empty.
`deliveries[].status` string Always returned	queued waits for its first or next attempt; sending is being posted; sent is delivered; failed needs a person (for example, invite the app) and is retried only on request; dead stopped after the attempt limit or 2 hours; skipped was never attempted (a demo workspace or Slack not connected). Possible values: `"queued""sending""sent""failed""dead""skipped""awaiting_confirmation""suppressed"`
`deliveries[].attempts` integer Always returned	The number of attempts so far. Minimum: 0.
`deliveries[].next_attempt_at` string (RFC 3339) \| null Always returned	When a queued delivery is attempted next; null in every other state.
`deliveries[].permalink` string Always returned	The Slack message link once sent; otherwise empty.
`deliveries[].error_code` string Always returned	Why the delivery is not sent, such as not_in_channel, channel_not_found, channel_archived, slack_auth, slack_not_connected, rate_limited, temporary, expired, not_configured (the announcement channel was removed in Settings before the post went out), or demo. Empty when nothing is wrong.
`deliveries[].error_message` string Always returned	The reason in words
`deliveries[].can_retry` boolean Always returned	True for a failed or dead Slack delivery.
`deliveries[].sent_at` string (RFC 3339) \| null Always returned	When the delivery was sent.
`deliveries[].created_at` string (RFC 3339) Always returned	When the update was recorded with this destination.
`deliveries[].updated_at` string (RFC 3339) Always returned	When the delivery state last changed.

Errors and recovery (7)

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

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Retry a status update delivery

POST/api/v1/timeline/{id}/deliveries/{deliveryId}/retry

Queues a failed or stopped Slack delivery again with a fresh attempt budget and a new 2-hour window. Any other state returns 409 with status_update_delivery_not_retryable. A post to an announcement channel that was removed from Settings → Status updates returns 400 with status_update_channel_not_configured. The workspace must have status update delivery turned on.

This API is in preview while email delivery is added.

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

Example request

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

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/timeline/{id}/deliveries/{deliveryId}/retry' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the queued delivery.

Success response JSON

json

{
  "delivery": {
    "id": 7,
    "timeline_event_id": 100,
    "incident_id": 1,
    "kind": "slack",
    "destination": "incident_channel",
    "target": "C0123ABCD",
    "target_label": "inc-1516",
    "status": "queued",
    "attempts": 0,
    "next_attempt_at": "2026-08-31T12:20:00Z",
    "permalink": "",
    "error_code": "",
    "error_message": "",
    "can_retry": false,
    "sent_at": null,
    "created_at": "2026-08-31T12:10:00Z",
    "updated_at": "2026-08-31T12:20:00Z"
  }
}

Parameters, headers, and fields

Operation ID: retryStatusUpdateDelivery

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric timeline-event ID returned by this API. Minimum: 1.
`deliveryId` integer Required	A positive numeric status update delivery ID returned by this API. Minimum: 1.

Response `200`

Returns the queued delivery.

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

Response fields
Field	Description
`delivery` object Always returned	One destination of a recorded status update and its delivery state. A delivery that cannot be sent within 2 hours, or after 6 attempts, stops (dead).
`delivery.id` integer Always returned	The delivery ID.
`delivery.timeline_event_id` integer Always returned	The status update this delivery belongs to.
`delivery.incident_id` integer Always returned	The incident ID.
`delivery.kind` string Always returned	The provider. Possible values: `"slack""email"`
`delivery.destination` string Always returned	Why the destination was chosen. Possible values: `"incident_channel""announcement_channel""email"`
`delivery.target` string Always returned	The Slack channel ID.
`delivery.target_label` string Always returned	The Slack channel name without #, when known; otherwise empty.
`delivery.status` string Always returned	queued waits for its first or next attempt; sending is being posted; sent is delivered; failed needs a person (for example, invite the app) and is retried only on request; dead stopped after the attempt limit or 2 hours; skipped was never attempted (a demo workspace or Slack not connected). Possible values: `"queued""sending""sent""failed""dead""skipped""awaiting_confirmation""suppressed"`
`delivery.attempts` integer Always returned	The number of attempts so far. Minimum: 0.
`delivery.next_attempt_at` string (RFC 3339) \| null Always returned	When a queued delivery is attempted next; null in every other state.
`delivery.permalink` string Always returned	The Slack message link once sent; otherwise empty.
`delivery.error_code` string Always returned	Why the delivery is not sent, such as not_in_channel, channel_not_found, channel_archived, slack_auth, slack_not_connected, rate_limited, temporary, expired, not_configured (the announcement channel was removed in Settings before the post went out), or demo. Empty when nothing is wrong.
`delivery.error_message` string Always returned	The reason in words
`delivery.can_retry` boolean Always returned	True for a failed or dead Slack delivery.
`delivery.sent_at` string (RFC 3339) \| null Always returned	When the delivery was sent.
`delivery.created_at` string (RFC 3339) Always returned	When the update was recorded with this destination.
`delivery.updated_at` string (RFC 3339) Always returned	When the delivery state last changed.

Errors and recovery (7)

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

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Read this resource as Markdown · OpenAPI specification

Timeline

Endpoints

List timeline events

Example request

Success: 200

Path parameters

Query parameters

Response 200

Error responses (7)

Create timeline event

Example request

Success: 201

Path parameters

Request headers

Request body

Response 201

Response headers

Error responses (7)

Get timeline event

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Update timeline event

Example request

Success: 200

Path parameters

Request headers

Request body

Response 200

Response headers

Error responses (9)

Delete timeline event

Example request

Success: 204

Path parameters

Error responses (7)

List status update deliveries

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Retry a status update delivery

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`

Response `200`