Skip to main content
POST
Create a work item

Restrictions

Usage

  • Requires the On-call Pro license.
  • action: the incident must not be closed, the caller needs edit access to it, and post_mortem_id must be empty.
  • follow_up: the incident must be closed. With post_mortem_id, the caller needs edit access to that report and the incident must be linked to it. Without it, the caller needs edit access to the incident, and the server binds the incident’s post-mortem if one exists; otherwise the item stays unbound until a report is created.
  • Set either assignees (entries {type, id?}; type is person or ai_sre, and an ai_sre entry omits id) or the legacy assignee_ids (all person), not both — sending both returns an error.
  • Person assignees must be active members who can already read the incident or post-mortem — assignment never grants access.
  • Newly added person assignees are notified; assigning ai_sre starts an AI SRE session that works on the item.
  • Retrying with the same idempotency_key from the same caller returns the original item with idempotent_replay: true; if that item was deleted, the call returns RequestLocked.
  • Every call is recorded in the account audit log. Don’t put secrets in request fields.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Parameters for creating an incident work item.

item_type
enum<string>
required

Work item type.

  • action: a to-do on an incident that is not closed yet; must not set post_mortem_id.
  • follow_up: a post-mortem follow-up on a closed incident; post_mortem_id is optional.
Available options:
action,
follow_up
title
string
required

Item title, at most 512 characters; leading and trailing spaces are trimmed and it must not be blank.

Maximum string length: 512
incident_id
string
required

Incident ID (MongoDB ObjectID) the item is anchored to.

Pattern: ^[0-9a-fA-F]{24}$
idempotency_key
string
required

Client-generated idempotency key (max 128 characters; letters, digits, _, -, ., : only).

Maximum string length: 128
Pattern: ^[A-Za-z0-9_\-.:]+$
description
string

Optional longer description (max 65,535 characters).

Maximum string length: 65535
status
enum<string>

Initial status. One of open, in_progress, done, cancelled; defaults to open when omitted or blank.

Available options:
open,
in_progress,
done,
cancelled
Maximum string length: 64
priority
string

Optional free-form priority, at most 64 characters. The console uses high, medium and low; any other string is stored as-is.

Maximum string length: 64
post_mortem_id
string

Post-mortem ID (32-character hex string). Forbidden for action. Optional for follow_up: when set, the incident must be linked to that report; when omitted, the incident's post-mortem is used if it exists.

assignee_ids
integer<int64>[]

Legacy alias for the initial assignees. Equivalent to assignees with every entry type person. Mutually exclusive with assignees: sending both returns an error. Assignees must be active members who can already read the anchor; assignment never grants access.

Maximum array length: 20
assignees
object[]

Initial assignees. Each entry is {type, id?}. type is person or ai_sre; an ai_sre entry omits id. Mutually exclusive with assignee_ids: sending both returns an error. assignee_ids is the legacy alias and is equivalent to an all-person list. At most 20 entries. Person assignees must be active members who can already read the anchor; assignment never grants access.

Maximum array length: 20

Response

Success

Success response envelope. On every 2xx response, request_id identifies the call (also mirrored in the Flashcat-Request-Id header) and data holds the endpoint-specific payload. Failure responses use a different shape — see ErrorResponse.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

Result of creating a work item.