Skip to content

docs(api): add AI SRE assignee fields to the work-item OpenAPI spec #442

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
debidong merged 1 commit into from
Sep 23, 2026
+352 −16
Merged

docs(api): add AI SRE assignee fields to the work-item OpenAPI spec #442

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
184 changes: 176 additions & 8 deletions api-reference/openapi.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6592,13 +6592,21 @@
"description": "Parameters for creating an incident work item.",
"properties": {
"assignee_ids": {
"description": "Initial assignee member IDs. Assignees must be active members who can already read the anchor; assignment never grants access.",
"description": "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.",
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"assignees": {
"description": "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.",
"items": {
"$ref": "#/components/schemas/WorkItemAssignee"
},
"maxItems": 20,
"type": "array"
},
"description": {
"description": "Optional longer description (max 65,535 characters).",
"maxLength": 65535,
Expand Down Expand Up @@ -14456,13 +14464,21 @@
"type": "object"
},
"ListWorkItemRequest": {
"description": "Filters for listing work items. At least one of `incident_id`, `post_mortem_id`, or `assignee_id` is required.",
"description": "Filters for listing work items. At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.",
"properties": {
"assignee_id": {
"description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin.",
"description": "Restrict results to items assigned to this member ID. Listing by assignee alone requires being that assignee or an account admin. Ignored when `assignee_type` is `ai_sre`.",
"format": "int64",
"type": "integer"
},
"assignee_type": {
"description": "Filter by assignee type: `person` or `ai_sre`. `ai_sre` returns items assigned to AI SRE (an AI caller uses this to list its own tasks) and does not require `assignee_id`. `person` together with `assignee_id` restricts results to that member. Omitted with a positive `assignee_id` means `person`.",
"enum": [
"person",
"ai_sre"
],
"type": "string"
},
"cursor": {
"description": "Pagination cursor from a previous response's `next_cursor`.",
"type": "string"
Expand Down Expand Up @@ -18130,13 +18146,21 @@
"description": "Full replacement of a work item's assignee set.",
"properties": {
"assignee_ids": {
"description": "New assignee member IDs, replacing the current set. An empty array clears all assignees.",
"description": "Legacy alias for the replacement assignee set. Equivalent to `assignees` with every entry `type` `person`. Mutually exclusive with `assignees`: sending both returns an error. An empty array clears all assignees.",
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"assignees": {
"description": "Replacement assignee set. 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. An empty array clears all assignees.",
"items": {
"$ref": "#/components/schemas/WorkItemAssignee"
},
"maxItems": 20,
"type": "array"
},
"version": {
"description": "Current item version for optimistic locking. Must match the stored version.",
"format": "int64",
Expand Down Expand Up @@ -28429,6 +28453,28 @@
],
"type": "object"
},
"WorkItemAssignee": {
"description": "One assignee on a work item.",
"properties": {
"id": {
"description": "Member ID. Required when `type` is `person`. Omitted when `type` is `ai_sre`.",
"format": "int64",
"type": "integer"
},
"type": {
"description": "Assignee kind: `person` (a member) or `ai_sre` (the account AI SRE).",
"enum": [
"person",
"ai_sre"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"WorkItemCreateResult": {
"description": "Result of creating a work item.",
"properties": {
Expand Down Expand Up @@ -28456,14 +28502,33 @@
"WorkItemItem": {
"description": "A structured incident work item (action or post-mortem follow-up) with its assignees.",
"properties": {
"agent_session_id": {
"description": "ID of the AI SRE session executing this item. Omitted when no session is recorded.",
"type": "string"
},
"agent_session_venue": {
"description": "Where that AI SRE session runs: `web` or `im`. Omitted when no session is recorded.",
"enum": [
"web",
"im"
],
"type": "string"
},
"assignee_ids": {
"description": "Member IDs of the current assignees. Never null; an empty array means unassigned.",
"description": "Member IDs of the current person assignees. AI SRE is not included. Never null; an empty array means no person assignee.",
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"assignees": {
"description": "Current assignees. Each entry is `{type, id?}`. `type` is `person` or `ai_sre`; an `ai_sre` entry omits `id`. Never null; an empty array means unassigned. `assignee_ids` is the person-only subset of this list.",
"items": {
"$ref": "#/components/schemas/WorkItemAssignee"
},
"type": "array"
},
"converted_at_seconds": {
"description": "Conversion time as a Unix timestamp in seconds. Present only after conversion.",
"format": "int64",
Expand Down Expand Up @@ -28563,6 +28628,7 @@
"source_kind",
"version",
"assignee_ids",
"assignees",
"created_by",
"updated_by",
"created_at_seconds",
Expand Down Expand Up @@ -40265,6 +40331,20 @@
4756301322131,
5068740052131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
},
{
"id": 4756301322131,
"type": "person"
},
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495329,
"created_by": 5329873302131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down Expand Up @@ -40321,7 +40401,7 @@
"On-call/Incidents"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set — an empty array clears all assignees.\n- Only newly added assignees are notified; removals never notify.\n- Audited — changes are recorded in the audit log.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- Full replacement of the assignee set — an empty array clears all assignees.\n- Set either `assignees` or the legacy `assignee_ids`, not both (sending both returns an error). An `ai_sre` entry omits `id`.\n- Only newly added assignees are notified; removals never notify.\n- Audited — changes are recorded in the audit log.",
"href": "/en/api-reference/on-call/incidents/incident-work-item-reset-assignees",
"metadata": {
"sidebarTitle": "Reset work item assignees"
Expand Down Expand Up @@ -40361,6 +40441,20 @@
4756301322131,
5068740052131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
},
{
"id": 4756301322131,
"type": "person"
},
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495329,
"created_by": 5329873302131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down Expand Up @@ -40454,6 +40548,20 @@
4756301322131,
5068740052131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
},
{
"id": 4756301322131,
"type": "person"
},
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495329,
"created_by": 5329873302131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down Expand Up @@ -40554,6 +40662,12 @@
"assignee_ids": [
3790925372131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
}
],
"created_at_seconds": 1785496400,
"created_by": 3790925372131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down Expand Up @@ -40606,7 +40720,7 @@
"On-call/Incidents"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- An `action` anchors to an active incident and must NOT set `post_mortem_id`; a `follow_up` REQUIRES the `post_mortem_id` of a post-mortem linked to `incident_id`.\n- Assignees must be active members who can already read the anchor incident or post-mortem — assignment never grants access.\n- Newly added assignees are notified.\n- Retrying with the same (`creator`, `idempotency_key`) replays the original item with `idempotent_replay: true` instead of creating a duplicate.\n- Audited — changes are recorded in the audit log.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Manage** (`on-call`) |\n\n## Usage\n\n- Requires the On-call Pro license.\n- An `action` anchors to an active incident and must NOT set `post_mortem_id`; a `follow_up` REQUIRES the `post_mortem_id` of a post-mortem linked to `incident_id`.\n- Set either `assignees` or the legacy `assignee_ids`, not both. `assignees` entries are `{type, id?}` with `type` `person` or `ai_sre`; an `ai_sre` entry omits `id`. `assignee_ids` is equivalent to an all-`person` list. Sending both returns an error.\n- Person assignees must be active members who can already read the anchor incident or post-mortem — assignment never grants access.\n- Newly added assignees are notified.\n- Retrying with the same (`creator`, `idempotency_key`) replays the original item with `idempotent_replay: true` instead of creating a duplicate.\n- Audited — changes are recorded in the audit log.",
"href": "/en/api-reference/on-call/incidents/incident-work-item-create",
"metadata": {
"sidebarTitle": "Create a work item"
Expand Down Expand Up @@ -40717,6 +40831,20 @@
4756301322131,
5068740052131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
},
{
"id": 4756301322131,
"type": "person"
},
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495329,
"created_by": 5329873302131,
"incident_id": "6a5f1e28807515413b384bce",
Expand All @@ -40734,6 +40862,12 @@
"assignee_ids": [
5068740052131
],
"assignees": [
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495164,
"created_by": 3790925372131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down Expand Up @@ -40789,7 +40923,7 @@
"On-call/Incidents"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, or `assignee_id` is required.\n- Cursor pagination sorted by `updated_at_seconds` descending — pass the previous response's `next_cursor` as `cursor` until `has_more` is false.\n- Listing by `incident_id` also includes follow-ups anchored on the incident's post-mortem.\n- Listing by `assignee_id` alone requires being that assignee or an account admin.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- At least one of `incident_id`, `post_mortem_id`, `assignee_id`, or `assignee_type` = `ai_sre` is required.\n- `assignee_type` = `ai_sre` lists items assigned to AI SRE and can be used on its own.\n- Cursor pagination sorted by `updated_at_seconds` descending — pass the previous response's `next_cursor` as `cursor` until `has_more` is false.\n- Listing by `incident_id` also includes follow-ups anchored on the incident's post-mortem.\n- Listing by `assignee_id` alone requires being that assignee or an account admin.",
"href": "/en/api-reference/on-call/incidents/incident-work-item-list",
"metadata": {
"sidebarTitle": "List work items"
Expand Down Expand Up @@ -40830,6 +40964,20 @@
4756301322131,
5068740052131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
},
{
"id": 4756301322131,
"type": "person"
},
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495329,
"created_by": 5329873302131,
"incident_id": "6a5f1e28807515413b384bce",
Expand All @@ -40847,6 +40995,12 @@
"assignee_ids": [
5068740052131
],
"assignees": [
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495164,
"created_by": 3790925372131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down Expand Up @@ -40941,6 +41095,20 @@
4756301322131,
5068740052131
],
"assignees": [
{
"id": 3790925372131,
"type": "person"
},
{
"id": 4756301322131,
"type": "person"
},
{
"id": 5068740052131,
"type": "person"
}
],
"created_at_seconds": 1785495329,
"created_by": 5329873302131,
"incident_id": "6a5f1e28807515413b384bce",
Expand Down
Loading
Loading