--- title: "Cortex API reference" canonical: https://workspace.socra.com/docs/cortex/reference/api --- # Cortex API reference Use the Cortex API to work with [Modules](/docs/cortex/concepts/modules-and-map), [Flashes](/docs/cortex/concepts/flashing-context), [Issues](/docs/cortex/concepts/issues-and-coordination), and their related resources. This reference is generated from the contract used by the Cortex service. Send a Socra access token as a Bearer token in the `Authorization` header. Review [access and permissions](/docs/cortex/administration/access-and-permissions) before choosing the principal and Account for the request. All methods use JSON unless the method has no request or response body. ```bash curl https://cortex.socra.cloud/v1/modules \ --header "Authorization: Bearer $SOCRA_ACCESS_TOKEN" ``` The contract below is the source of truth for method paths, inputs, outputs, and required authorization scopes. ## API surface Base URL: `https://cortex.socra.cloud` ## Modules A context module — a self-contained unit of specific knowledge, addressed by name within an account. ### Resource schema - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Create module `POST /v1/modules` #### Request body - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `dependencies` string[] — Names of the direct module dependencies., optional - `visibility` "internal" | "private" — Visibility of the module within its account., optional - `parent` string | null — Name of the organizational parent, or null for a root module., optional - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" } }, "required": [ "name", "content" ] } ``` #### Response - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } ``` ### List modules `GET /v1/modules` #### Query parameters - `q` string — Text to find in module names or content., optional - `owner` string — Account-user ID by which to filter modules., optional - `state` "active" | "archived" | "all" — Archival state by which to filter modules., optional - `limit` integer (min: 1; max: 100) — Maximum number of modules to return., optional - `after` string — Cursor after which to return modules., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "description": "Text to find in module names or content.", "type": "string" }, "owner": { "description": "Account-user ID by which to filter modules.", "type": "string" }, "state": { "description": "Archival state by which to filter modules.", "type": "string", "enum": [ "active", "archived", "all" ] }, "limit": { "description": "Maximum number of modules to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return modules.", "type": "string" } } } ``` #### Response - `data` object[] — Modules in this page., required - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required - `has_more` boolean — Whether more modules are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Modules in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more modules are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get module `GET /v1/modules/{name}` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Response - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Update module `PATCH /v1/modules/{name}` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Request body - `name` string — New account-unique name of the module., optional - `content` string — New authored knowledge content of the module., optional - `dependencies` string[] — Complete new set of direct module dependency names., optional - `visibility` "internal" | "private" — New visibility of the module within its account., optional - `owner` string — Account-user ID of the new module owner., optional - `default_assignee` string | null — New default account-user ID for unassigned work, or null to clear it., optional - `parent` string | null — New organizational parent name, or null to make the module a root., optional - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "New account-unique name of the module.", "type": "string" }, "content": { "description": "New authored knowledge content of the module.", "type": "string" }, "dependencies": { "description": "Complete new set of direct module dependency names.", "type": "array", "items": { "type": "string" } }, "visibility": { "description": "New visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "owner": { "description": "Account-user ID of the new module owner.", "type": "string" }, "default_assignee": { "description": "New default account-user ID for unassigned work, or null to clear it.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "New organizational parent name, or null to make the module a root.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" } } } ``` #### Response - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } ``` ### List module versions `GET /v1/modules/{name}/versions` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Query parameters - `limit` integer (min: 1; max: 100) — Maximum number of module versions to return., optional - `after` integer (greater than: 0; max: 9007199254740991) — Version number before which to return older versions., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "description": "Maximum number of module versions to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Version number before which to return older versions.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } } ``` #### Response - `data` object[] — Module versions in this page., required - `module_id` custom — Stable ID of the versioned module., required - `version` integer (greater than: 0; max: 9007199254740991) — Revision number of this module version., required - `name` string — Module name in this version., required - `content` string — Authored knowledge content in this version., required - `dependencies` string[] — Direct dependency names in this version., required - `owner` string — Account-user ID of the module owner in this version., required - `default_assignee` string | null — Default account-user ID in this version, or null if none was set., required - `visibility` "internal" | "private" — Module visibility in this version., required - `archived` boolean | null — Archive state in this version; null for older snapshots where it was not recorded., required - `author` string | null — Account-user ID of the version author, or null if unknown., required - `source` "create" | "update" | "backfill" — Operation that created the module version., required - `changed_fields` "name" | "content" | "dependencies" | "owner" | "default_assignee" | "visibility" | "archived"[] — Module fields that changed in this version., required - `created_at` custom — Date and time when the module version was created., required - `has_more` boolean — Whether more module versions are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Module versions in this page.", "type": "array", "items": { "type": "object", "properties": { "module_id": { "description": "Stable ID of the versioned module." }, "version": { "description": "Revision number of this module version.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "description": "Module name in this version.", "type": "string" }, "content": { "description": "Authored knowledge content in this version.", "type": "string" }, "dependencies": { "description": "Direct dependency names in this version.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner in this version.", "type": "string" }, "default_assignee": { "description": "Default account-user ID in this version, or null if none was set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "visibility": { "description": "Module visibility in this version.", "type": "string", "enum": [ "internal", "private" ] }, "archived": { "description": "Archive state in this version; null for older snapshots where it was not recorded.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "author": { "description": "Account-user ID of the version author, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "description": "Operation that created the module version.", "type": "string", "enum": [ "create", "update", "backfill" ] }, "changed_fields": { "description": "Module fields that changed in this version.", "type": "array", "items": { "description": "A module field that changed in a version.", "type": "string", "enum": [ "name", "content", "dependencies", "owner", "default_assignee", "visibility", "archived" ] } }, "created_at": { "description": "Date and time when the module version was created." } }, "required": [ "module_id", "version", "name", "content", "dependencies", "owner", "default_assignee", "visibility", "archived", "author", "source", "changed_fields", "created_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more module versions are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get module version `GET /v1/modules/{name}/versions/{version}` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` - `version` integer (greater than: 0; max: 9007199254740991) — Module version number., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Module version number.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } ``` #### Response - `module_id` custom — Stable ID of the versioned module., required - `version` integer (greater than: 0; max: 9007199254740991) — Revision number of this module version., required - `name` string — Module name in this version., required - `content` string — Authored knowledge content in this version., required - `dependencies` string[] — Direct dependency names in this version., required - `owner` string — Account-user ID of the module owner in this version., required - `default_assignee` string | null — Default account-user ID in this version, or null if none was set., required - `visibility` "internal" | "private" — Module visibility in this version., required - `archived` boolean | null — Archive state in this version; null for older snapshots where it was not recorded., required - `author` string | null — Account-user ID of the version author, or null if unknown., required - `source` "create" | "update" | "backfill" — Operation that created the module version., required - `changed_fields` "name" | "content" | "dependencies" | "owner" | "default_assignee" | "visibility" | "archived"[] — Module fields that changed in this version., required - `created_at` custom — Date and time when the module version was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_id": { "description": "Stable ID of the versioned module." }, "version": { "description": "Revision number of this module version.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "description": "Module name in this version.", "type": "string" }, "content": { "description": "Authored knowledge content in this version.", "type": "string" }, "dependencies": { "description": "Direct dependency names in this version.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner in this version.", "type": "string" }, "default_assignee": { "description": "Default account-user ID in this version, or null if none was set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "visibility": { "description": "Module visibility in this version.", "type": "string", "enum": [ "internal", "private" ] }, "archived": { "description": "Archive state in this version; null for older snapshots where it was not recorded.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "author": { "description": "Account-user ID of the version author, or null if unknown.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "description": "Operation that created the module version.", "type": "string", "enum": [ "create", "update", "backfill" ] }, "changed_fields": { "description": "Module fields that changed in this version.", "type": "array", "items": { "description": "A module field that changed in a version.", "type": "string", "enum": [ "name", "content", "dependencies", "owner", "default_assignee", "visibility", "archived" ] } }, "created_at": { "description": "Date and time when the module version was created." } }, "required": [ "module_id", "version", "name", "content", "dependencies", "owner", "default_assignee", "visibility", "archived", "author", "source", "changed_fields", "created_at" ], "additionalProperties": false } ``` ### Archive module `POST /v1/modules/{name}/archive` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Response - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Restore module `POST /v1/modules/{name}/restore` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Request body - `content` string — Replacement body committed with restoration; omitted preserves the body., optional - `dependencies` string[] — Complete final dependency list; omitted preserves links, [] removes all links., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "description": "Replacement body committed with restoration; omitted preserves the body.", "type": "string" }, "dependencies": { "description": "Complete final dependency list; omitted preserves links, [] removes all links.", "type": "array", "items": { "type": "string" } } } } ``` #### Response - `id` custom — Stable unique ID of the module., required - `name` string — Account-unique name of the module., required - `content` string — Authored knowledge content of the module., required - `version` integer (greater than: 0; max: 9007199254740991) — Current knowledge revision of the module., required - `archived` boolean — Whether the module is archived., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `dependencies` string[] — Names of the direct module dependencies., required - `owner` string — Account-user ID of the module owner., required - `default_assignee` string | null — Default account-user ID for unassigned work, or null if none is set., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `inherit_permissions` boolean — Whether the module uses the permission policy of its parent., required - `created_at` custom — Date and time when the module was created., required - `updated_at` custom — Date and time when the module was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Stable unique ID of the module." }, "name": { "description": "Account-unique name of the module.", "type": "string" }, "content": { "description": "Authored knowledge content of the module.", "type": "string" }, "version": { "description": "Current knowledge revision of the module.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "archived": { "description": "Whether the module is archived.", "type": "boolean" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "dependencies": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "default_assignee": { "description": "Default account-user ID for unassigned work, or null if none is set.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inherit_permissions": { "description": "Whether the module uses the permission policy of its parent.", "type": "boolean" }, "created_at": { "description": "Date and time when the module was created." }, "updated_at": { "description": "Date and time when the module was last updated." } }, "required": [ "id", "name", "content", "version", "archived", "visibility", "dependencies", "owner", "default_assignee", "parent", "inherit_permissions", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Delete module `DELETE /v1/modules/{name}` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Response No response body. ### Module graph `POST /v1/modules/graph` #### Response - `nodes` object[] — Accessible modules and their direct dependency edges., required - `name` string — Account-unique name of the module., required - `summary` string — First meaningful line of the module content., required - `owner` string — Account-user ID of the module owner., required - `visibility` "internal" | "private" — Visibility of the module within its account., required - `parent` string | null — Name of the organizational parent, or null for a root module., required - `depends_on` string[] — Names of the direct module dependencies., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "nodes": { "description": "Accessible modules and their direct dependency edges.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Account-unique name of the module.", "type": "string" }, "summary": { "description": "First meaningful line of the module content.", "type": "string" }, "owner": { "description": "Account-user ID of the module owner.", "type": "string" }, "visibility": { "description": "Visibility of the module within its account.", "type": "string", "enum": [ "internal", "private" ] }, "parent": { "description": "Name of the organizational parent, or null for a root module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "depends_on": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } } }, "required": [ "name", "summary", "owner", "visibility", "parent", "depends_on" ], "additionalProperties": false } } }, "required": [ "nodes" ], "additionalProperties": false } ``` ## Module permissions The effective permission policy projected through a Cortex module. ### Resource schema - `inherited` boolean — Whether the module uses the permission policy of an ancestor., required - `inherited_from` string | null — Name of the module that owns the effective policy, or null for this module., required - `etag` string — Opaque revision tag of the effective permission policy., required - `bindings` object[] — Role bindings in the effective policy., required - `role` "admin" | "editor" | "commenter" | "viewer" — Access role granted by this binding., required - `members` object[] (min items: 1) — Principals and groups that receive the access role., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inherited": { "description": "Whether the module uses the permission policy of an ancestor.", "type": "boolean" }, "inherited_from": { "description": "Name of the module that owns the effective policy, or null for this module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "etag": { "description": "Opaque revision tag of the effective permission policy.", "type": "string" }, "bindings": { "description": "Role bindings in the effective policy.", "type": "array", "items": { "type": "object", "properties": { "role": { "description": "Access role granted by this binding.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ] }, "members": { "description": "Principals and groups that receive the access role.", "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "principal" }, "id": { "description": "Account-user ID of the principal." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "group" }, "id": { "description": "ID of the account group." } }, "required": [ "type", "id" ], "additionalProperties": false } ] } } }, "required": [ "role", "members" ], "additionalProperties": false } } }, "required": [ "inherited", "inherited_from", "etag", "bindings" ], "additionalProperties": false } ``` ### Get module permissions `GET /v1/modules/{name}/permissions` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Response - `inherited` boolean — Whether the module uses the permission policy of an ancestor., required - `inherited_from` string | null — Name of the module that owns the effective policy, or null for this module., required - `etag` string — Opaque revision tag of the effective permission policy., required - `bindings` object[] — Role bindings in the effective policy., required - `role` "admin" | "editor" | "commenter" | "viewer" — Access role granted by this binding., required - `members` object[] (min items: 1) — Principals and groups that receive the access role., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inherited": { "description": "Whether the module uses the permission policy of an ancestor.", "type": "boolean" }, "inherited_from": { "description": "Name of the module that owns the effective policy, or null for this module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "etag": { "description": "Opaque revision tag of the effective permission policy.", "type": "string" }, "bindings": { "description": "Role bindings in the effective policy.", "type": "array", "items": { "type": "object", "properties": { "role": { "description": "Access role granted by this binding.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ] }, "members": { "description": "Principals and groups that receive the access role.", "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "principal" }, "id": { "description": "Account-user ID of the principal." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "group" }, "id": { "description": "ID of the account group." } }, "required": [ "type", "id" ], "additionalProperties": false } ] } } }, "required": [ "role", "members" ], "additionalProperties": false } } }, "required": [ "inherited", "inherited_from", "etag", "bindings" ], "additionalProperties": false } ``` ### Set module permissions `PATCH /v1/modules/{name}/permissions` #### Path parameters - `name` string — Account-unique name of the module., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Account-unique name of the module.", "type": "string" } ``` #### Request body - `etag` string (min length: 1) — Revision tag that the current policy must match., required - `bindings` object[] — Complete new set of role bindings., required - `role` "admin" | "editor" | "commenter" | "viewer" — Access role granted by this binding., required - `members` object[] (min items: 1) — Principals and groups that receive the access role., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "etag": { "description": "Revision tag that the current policy must match.", "type": "string", "minLength": 1 }, "bindings": { "description": "Complete new set of role bindings.", "type": "array", "items": { "type": "object", "properties": { "role": { "description": "Access role granted by this binding.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ] }, "members": { "description": "Principals and groups that receive the access role.", "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "principal" }, "id": { "description": "Account-user ID of the principal." } }, "required": [ "type", "id" ] }, { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "group" }, "id": { "description": "ID of the account group." } }, "required": [ "type", "id" ] } ] } } }, "required": [ "role", "members" ] } } }, "required": [ "etag", "bindings" ] } ``` #### Response - `inherited` boolean — Whether the module uses the permission policy of an ancestor., required - `inherited_from` string | null — Name of the module that owns the effective policy, or null for this module., required - `etag` string — Opaque revision tag of the effective permission policy., required - `bindings` object[] — Role bindings in the effective policy., required - `role` "admin" | "editor" | "commenter" | "viewer" — Access role granted by this binding., required - `members` object[] (min items: 1) — Principals and groups that receive the access role., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inherited": { "description": "Whether the module uses the permission policy of an ancestor.", "type": "boolean" }, "inherited_from": { "description": "Name of the module that owns the effective policy, or null for this module.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "etag": { "description": "Opaque revision tag of the effective permission policy.", "type": "string" }, "bindings": { "description": "Role bindings in the effective policy.", "type": "array", "items": { "type": "object", "properties": { "role": { "description": "Access role granted by this binding.", "type": "string", "enum": [ "admin", "editor", "commenter", "viewer" ] }, "members": { "description": "Principals and groups that receive the access role.", "minItems": 1, "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "principal" }, "id": { "description": "Account-user ID of the principal." } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "description": "Type of module access member.", "type": "string", "const": "group" }, "id": { "description": "ID of the account group." } }, "required": [ "type", "id" ], "additionalProperties": false } ] } } }, "required": [ "role", "members" ], "additionalProperties": false } } }, "required": [ "inherited", "inherited_from", "etag", "bindings" ], "additionalProperties": false } ``` ## Flashes A flash — one assembly of a target module's dependency closure into a single context bundle. The metered consume verb of Cortex. ### Resource schema - `id` custom — Unique ID of the flash., required - `target` string — Name of the module that was explicitly flashed., required - `total_tokens` number — Total tokens in the assembled dependency closure., required - `module_count` number — Number of modules in the assembled dependency closure., required - `lines` object[] — Immutable module manifest for the flash., required - `module` string — Name of the module in the flash closure., required - `version` integer | null — Module revision used in the flash, or null for a legacy record., required - `tokens` number — Tokens attributed to the module in this flash., required - `is_target` boolean — Whether this module was the explicit flash target., required - `created_at` custom — Date and time when the flash was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the flash." }, "target": { "description": "Name of the module that was explicitly flashed.", "type": "string" }, "total_tokens": { "description": "Total tokens in the assembled dependency closure.", "type": "number" }, "module_count": { "description": "Number of modules in the assembled dependency closure.", "type": "number" }, "lines": { "description": "Immutable module manifest for the flash.", "type": "array", "items": { "type": "object", "properties": { "module": { "description": "Name of the module in the flash closure.", "type": "string" }, "version": { "description": "Module revision used in the flash, or null for a legacy record.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "tokens": { "description": "Tokens attributed to the module in this flash.", "type": "number" }, "is_target": { "description": "Whether this module was the explicit flash target.", "type": "boolean" } }, "required": [ "module", "version", "tokens", "is_target" ], "additionalProperties": false } }, "created_at": { "description": "Date and time when the flash was created." } }, "required": [ "id", "target", "total_tokens", "module_count", "lines", "created_at" ], "additionalProperties": false } ``` ### Flash a module `POST /v1/flashes` #### Request body - `target` string — Name of the module to flash., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "target": { "description": "Name of the module to flash.", "type": "string" } }, "required": [ "target" ] } ``` #### Response - `id` custom — Unique ID of the flash., required - `target` string — Name of the module that was explicitly flashed., required - `total_tokens` number — Total tokens in the assembled dependency closure., required - `module_count` number — Number of modules in the assembled dependency closure., required - `lines` object[] — Immutable module manifest for the flash., required - `module` string — Name of the module in the flash closure., required - `version` integer | null — Module revision used in the flash, or null for a legacy record., required - `tokens` number — Tokens attributed to the module in this flash., required - `is_target` boolean — Whether this module was the explicit flash target., required - `created_at` custom — Date and time when the flash was created., required - `assembly` object — Context bundle produced by the flash., required - `target` string — Name of the module that was explicitly flashed., required - `modules` object[] — Dependency closure in foundation-first order., required - `name` string — Account-unique name of the assembled module., required - `content` string — Authored knowledge content of the assembled module., required - `depends_on` string[] — Names of the direct module dependencies., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the flash." }, "target": { "description": "Name of the module that was explicitly flashed.", "type": "string" }, "total_tokens": { "description": "Total tokens in the assembled dependency closure.", "type": "number" }, "module_count": { "description": "Number of modules in the assembled dependency closure.", "type": "number" }, "lines": { "description": "Immutable module manifest for the flash.", "type": "array", "items": { "type": "object", "properties": { "module": { "description": "Name of the module in the flash closure.", "type": "string" }, "version": { "description": "Module revision used in the flash, or null for a legacy record.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "tokens": { "description": "Tokens attributed to the module in this flash.", "type": "number" }, "is_target": { "description": "Whether this module was the explicit flash target.", "type": "boolean" } }, "required": [ "module", "version", "tokens", "is_target" ], "additionalProperties": false } }, "created_at": { "description": "Date and time when the flash was created." }, "assembly": { "description": "Context bundle produced by the flash.", "type": "object", "properties": { "target": { "description": "Name of the module that was explicitly flashed.", "type": "string" }, "modules": { "description": "Dependency closure in foundation-first order.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Account-unique name of the assembled module.", "type": "string" }, "content": { "description": "Authored knowledge content of the assembled module.", "type": "string" }, "depends_on": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } } }, "required": [ "name", "content", "depends_on" ], "additionalProperties": false } } }, "required": [ "target", "modules" ], "additionalProperties": false } }, "required": [ "id", "target", "total_tokens", "module_count", "lines", "created_at", "assembly" ], "additionalProperties": false } ``` ### List flashes `GET /v1/flashes` #### Query parameters - `target` string — Target module name by which to filter flashes., optional - `limit` integer (min: 1; max: 100) — Maximum number of flashes to return., optional - `after` string — Cursor after which to return flashes., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "target": { "description": "Target module name by which to filter flashes.", "type": "string" }, "limit": { "description": "Maximum number of flashes to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return flashes.", "type": "string" } } } ``` #### Response - `data` object[] — Flashes in this page., required - `id` custom — Unique ID of the flash., required - `target` string — Name of the module that was explicitly flashed., required - `total_tokens` number — Total tokens in the assembled dependency closure., required - `module_count` number — Number of modules in the assembled dependency closure., required - `lines` object[] — Immutable module manifest for the flash., required - `module` string — Name of the module in the flash closure., required - `version` integer | null — Module revision used in the flash, or null for a legacy record., required - `tokens` number — Tokens attributed to the module in this flash., required - `is_target` boolean — Whether this module was the explicit flash target., required - `created_at` custom — Date and time when the flash was created., required - `has_more` boolean — Whether more flashes are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Flashes in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the flash." }, "target": { "description": "Name of the module that was explicitly flashed.", "type": "string" }, "total_tokens": { "description": "Total tokens in the assembled dependency closure.", "type": "number" }, "module_count": { "description": "Number of modules in the assembled dependency closure.", "type": "number" }, "lines": { "description": "Immutable module manifest for the flash.", "type": "array", "items": { "type": "object", "properties": { "module": { "description": "Name of the module in the flash closure.", "type": "string" }, "version": { "description": "Module revision used in the flash, or null for a legacy record.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "tokens": { "description": "Tokens attributed to the module in this flash.", "type": "number" }, "is_target": { "description": "Whether this module was the explicit flash target.", "type": "boolean" } }, "required": [ "module", "version", "tokens", "is_target" ], "additionalProperties": false } }, "created_at": { "description": "Date and time when the flash was created." } }, "required": [ "id", "target", "total_tokens", "module_count", "lines", "created_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more flashes are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get a flash `GET /v1/flashes/{id}` #### Path parameters - `id` custom — Unique ID of the flash., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the flash." } ``` #### Response - `id` custom — Unique ID of the flash., required - `target` string — Name of the module that was explicitly flashed., required - `total_tokens` number — Total tokens in the assembled dependency closure., required - `module_count` number — Number of modules in the assembled dependency closure., required - `lines` object[] — Immutable module manifest for the flash., required - `module` string — Name of the module in the flash closure., required - `version` integer | null — Module revision used in the flash, or null for a legacy record., required - `tokens` number — Tokens attributed to the module in this flash., required - `is_target` boolean — Whether this module was the explicit flash target., required - `created_at` custom — Date and time when the flash was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the flash." }, "target": { "description": "Name of the module that was explicitly flashed.", "type": "string" }, "total_tokens": { "description": "Total tokens in the assembled dependency closure.", "type": "number" }, "module_count": { "description": "Number of modules in the assembled dependency closure.", "type": "number" }, "lines": { "description": "Immutable module manifest for the flash.", "type": "array", "items": { "type": "object", "properties": { "module": { "description": "Name of the module in the flash closure.", "type": "string" }, "version": { "description": "Module revision used in the flash, or null for a legacy record.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "tokens": { "description": "Tokens attributed to the module in this flash.", "type": "number" }, "is_target": { "description": "Whether this module was the explicit flash target.", "type": "boolean" } }, "required": [ "module", "version", "tokens", "is_target" ], "additionalProperties": false } }, "created_at": { "description": "Date and time when the flash was created." } }, "required": [ "id", "target", "total_tokens", "module_count", "lines", "created_at" ], "additionalProperties": false } ``` ### Get a flash assembly `GET /v1/flashes/{id}/assembly` #### Path parameters - `id` custom — Unique ID of the flash., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the flash." } ``` #### Response - `target` string — Name of the module that was explicitly flashed., required - `modules` object[] — Dependency closure in foundation-first order., required - `name` string — Account-unique name of the assembled module., required - `content` string — Authored knowledge content of the assembled module., required - `depends_on` string[] — Names of the direct module dependencies., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "target": { "description": "Name of the module that was explicitly flashed.", "type": "string" }, "modules": { "description": "Dependency closure in foundation-first order.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Account-unique name of the assembled module.", "type": "string" }, "content": { "description": "Authored knowledge content of the assembled module.", "type": "string" }, "depends_on": { "description": "Names of the direct module dependencies.", "type": "array", "items": { "type": "string" } } }, "required": [ "name", "content", "depends_on" ], "additionalProperties": false } } }, "required": [ "target", "modules" ], "additionalProperties": false } ``` ### Flash usage `POST /v1/flashes/usage` #### Request body - `since` custom — Inclusive start of the usage window., optional - `until` custom — Inclusive end of the usage window., optional - `sort` "flashed" | "pulled" | "tokens" — Field by which to order module usage., optional - `group_by` "day" | "module_day" — Optional time grouping for usage., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "description": "Inclusive start of the usage window." }, "until": { "description": "Inclusive end of the usage window." }, "sort": { "description": "Field by which to order module usage.", "type": "string", "enum": [ "flashed", "pulled", "tokens" ] }, "group_by": { "description": "Optional time grouping for usage.", "type": "string", "enum": [ "day", "module_day" ] } } } ``` #### Response - `total_flashes` number — Number of flashes in the usage window., required - `total_tokens` number — Total tokens served in the usage window., required - `modules` object[] — Usage totals for each module in the window., required - `module` string — Account-unique name of the module., required - `explicit_flashes` number — Number of times the module was an explicit flash target., required - `transitive_pulls` number — Number of times the module was pulled into another closure., required - `total_tokens` number — Tokens attributed to the module in the usage window., required - `last_flashed_at` custom | null — Last time the module was an explicit target, or null if it was not targeted., required - `per_day` object[] — Daily usage buckets when time grouping is requested., optional - `date` string — UTC date of the usage bucket in YYYY-MM-DD format., required - `flashes` number — Number of explicit flashes on this date., required - `tokens` number — Total tokens served on this date., required - `pulls` number — Number of transitive module pulls on this date., required - `module_daily` object[] — Per-module daily usage series when module-day grouping is requested., optional - `module` string — Account-unique name of the module., required - `points` object[] — Daily explicit-flash usage points., required - `date` string — UTC date of the usage point in YYYY-MM-DD format., required - `flashes` number — Number of times the module was flashed on this date., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "total_flashes": { "description": "Number of flashes in the usage window.", "type": "number" }, "total_tokens": { "description": "Total tokens served in the usage window.", "type": "number" }, "modules": { "description": "Usage totals for each module in the window.", "type": "array", "items": { "type": "object", "properties": { "module": { "description": "Account-unique name of the module.", "type": "string" }, "explicit_flashes": { "description": "Number of times the module was an explicit flash target.", "type": "number" }, "transitive_pulls": { "description": "Number of times the module was pulled into another closure.", "type": "number" }, "total_tokens": { "description": "Tokens attributed to the module in the usage window.", "type": "number" }, "last_flashed_at": { "description": "Last time the module was an explicit target, or null if it was not targeted.", "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "module", "explicit_flashes", "transitive_pulls", "total_tokens", "last_flashed_at" ], "additionalProperties": false } }, "per_day": { "description": "Daily usage buckets when time grouping is requested.", "type": "array", "items": { "type": "object", "properties": { "date": { "description": "UTC date of the usage bucket in YYYY-MM-DD format.", "type": "string" }, "flashes": { "description": "Number of explicit flashes on this date.", "type": "number" }, "tokens": { "description": "Total tokens served on this date.", "type": "number" }, "pulls": { "description": "Number of transitive module pulls on this date.", "type": "number" } }, "required": [ "date", "flashes", "tokens", "pulls" ], "additionalProperties": false } }, "module_daily": { "description": "Per-module daily usage series when module-day grouping is requested.", "type": "array", "items": { "type": "object", "properties": { "module": { "description": "Account-unique name of the module.", "type": "string" }, "points": { "description": "Daily explicit-flash usage points.", "type": "array", "items": { "type": "object", "properties": { "date": { "description": "UTC date of the usage point in YYYY-MM-DD format.", "type": "string" }, "flashes": { "description": "Number of times the module was flashed on this date.", "type": "number" } }, "required": [ "date", "flashes" ], "additionalProperties": false } } }, "required": [ "module", "points" ], "additionalProperties": false } } }, "required": [ "total_flashes", "total_tokens", "modules" ], "additionalProperties": false } ``` ## Issues A unit of work in flight, owned by a module — the work supply chain over an account’s knowledge. ### Resource schema - `id` custom — Unique ID of the issue., required - `module` string — Name of the module that owns the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `status` "open" | "in_progress" | "done" | "canceled" — Current lifecycle status of the issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., required - `originator` string — Account-user ID of the user who created the issue., required - `assignee` string | null — Assigned account-user ID, or null if unassigned., required - `dependencies` string[] — IDs of issues that must finish before this issue., required - `labels` object[] — Labels attached to the issue., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `schedule` string | null — ID of the schedule that created the issue, or null if none did., required - `scheduled_for` custom | null — Scheduled occurrence that created the issue, or null if it was not scheduled., required - `created_at` custom — Date and time when the issue was created., required - `updated_at` custom — Date and time when the issue was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue." }, "module": { "description": "Name of the module that owns the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "status": { "description": "Current lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "originator": { "description": "Account-user ID of the user who created the issue.", "type": "string" }, "assignee": { "description": "Assigned account-user ID, or null if unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Labels attached to the issue.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "schedule": { "description": "ID of the schedule that created the issue, or null if none did.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "Scheduled occurrence that created the issue, or null if it was not scheduled.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the issue was created." }, "updated_at": { "description": "Date and time when the issue was last updated." } }, "required": [ "id", "module", "title", "description", "status", "priority", "originator", "assignee", "dependencies", "labels", "schedule", "scheduled_for", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Create issue `POST /v1/issues` #### Request body - `module` string — Name of the module that will own the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `assignee` string | null — Account-user ID to assign, or null to leave the issue unassigned., optional - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., optional - `dependencies` string[] — IDs of issues that must finish before this issue., optional - `labels` string[] — IDs of labels to attach to the issue., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module": { "description": "Name of the module that will own the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "assignee": { "description": "Account-user ID to assign, or null to leave the issue unassigned.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "IDs of labels to attach to the issue.", "type": "array", "items": { "type": "string" } } }, "required": [ "module", "title", "description" ] } ``` #### Response - `id` custom — Unique ID of the issue., required - `module` string — Name of the module that owns the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `status` "open" | "in_progress" | "done" | "canceled" — Current lifecycle status of the issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., required - `originator` string — Account-user ID of the user who created the issue., required - `assignee` string | null — Assigned account-user ID, or null if unassigned., required - `dependencies` string[] — IDs of issues that must finish before this issue., required - `labels` object[] — Labels attached to the issue., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `schedule` string | null — ID of the schedule that created the issue, or null if none did., required - `scheduled_for` custom | null — Scheduled occurrence that created the issue, or null if it was not scheduled., required - `created_at` custom — Date and time when the issue was created., required - `updated_at` custom — Date and time when the issue was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue." }, "module": { "description": "Name of the module that owns the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "status": { "description": "Current lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "originator": { "description": "Account-user ID of the user who created the issue.", "type": "string" }, "assignee": { "description": "Assigned account-user ID, or null if unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Labels attached to the issue.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "schedule": { "description": "ID of the schedule that created the issue, or null if none did.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "Scheduled occurrence that created the issue, or null if it was not scheduled.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the issue was created." }, "updated_at": { "description": "Date and time when the issue was last updated." } }, "required": [ "id", "module", "title", "description", "status", "priority", "originator", "assignee", "dependencies", "labels", "schedule", "scheduled_for", "created_at", "updated_at" ], "additionalProperties": false } ``` ### List issues `GET /v1/issues` #### Query parameters - `module` string — Module name by which to filter issues., optional - `status` "open" | "in_progress" | "done" | "canceled" — Lifecycle status by which to filter issues., optional - `assignee` string — Account-user ID by which to filter issues., optional - `label` string — Label ID by which to filter issues., optional - `q` string — Text to find in issue titles, descriptions, or comments., optional - `limit` integer (min: 1; max: 100) — Maximum number of issues to return., optional - `after` string — Cursor after which to return issues., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module": { "description": "Module name by which to filter issues.", "type": "string" }, "status": { "description": "Lifecycle status by which to filter issues.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "assignee": { "description": "Account-user ID by which to filter issues.", "type": "string" }, "label": { "description": "Label ID by which to filter issues.", "type": "string" }, "q": { "description": "Text to find in issue titles, descriptions, or comments.", "type": "string" }, "limit": { "description": "Maximum number of issues to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return issues.", "type": "string" } } } ``` #### Response - `data` object[] — Issues in this page., required - `id` custom — Unique ID of the issue., required - `module` string — Name of the module that owns the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `status` "open" | "in_progress" | "done" | "canceled" — Current lifecycle status of the issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., required - `originator` string — Account-user ID of the user who created the issue., required - `assignee` string | null — Assigned account-user ID, or null if unassigned., required - `dependencies` string[] — IDs of issues that must finish before this issue., required - `labels` object[] — Labels attached to the issue., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `schedule` string | null — ID of the schedule that created the issue, or null if none did., required - `scheduled_for` custom | null — Scheduled occurrence that created the issue, or null if it was not scheduled., required - `created_at` custom — Date and time when the issue was created., required - `updated_at` custom — Date and time when the issue was last updated., required - `has_more` boolean — Whether more issues are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Issues in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the issue." }, "module": { "description": "Name of the module that owns the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "status": { "description": "Current lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "originator": { "description": "Account-user ID of the user who created the issue.", "type": "string" }, "assignee": { "description": "Assigned account-user ID, or null if unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Labels attached to the issue.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "schedule": { "description": "ID of the schedule that created the issue, or null if none did.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "Scheduled occurrence that created the issue, or null if it was not scheduled.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the issue was created." }, "updated_at": { "description": "Date and time when the issue was last updated." } }, "required": [ "id", "module", "title", "description", "status", "priority", "originator", "assignee", "dependencies", "labels", "schedule", "scheduled_for", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more issues are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Issue inbox `POST /v1/issues/inbox` #### Request body - `limit` integer (min: 1; max: 100) — Maximum number of issues to return., optional - `after` string — Cursor after which to return issues., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "description": "Maximum number of issues to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return issues.", "type": "string" } } } ``` #### Response - `data` object[] — Issues in this page., required - `id` custom — Unique ID of the issue., required - `module` string — Name of the module that owns the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `status` "open" | "in_progress" | "done" | "canceled" — Current lifecycle status of the issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., required - `originator` string — Account-user ID of the user who created the issue., required - `assignee` string | null — Assigned account-user ID, or null if unassigned., required - `dependencies` string[] — IDs of issues that must finish before this issue., required - `labels` object[] — Labels attached to the issue., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `schedule` string | null — ID of the schedule that created the issue, or null if none did., required - `scheduled_for` custom | null — Scheduled occurrence that created the issue, or null if it was not scheduled., required - `created_at` custom — Date and time when the issue was created., required - `updated_at` custom — Date and time when the issue was last updated., required - `has_more` boolean — Whether more issues are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Issues in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the issue." }, "module": { "description": "Name of the module that owns the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "status": { "description": "Current lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "originator": { "description": "Account-user ID of the user who created the issue.", "type": "string" }, "assignee": { "description": "Assigned account-user ID, or null if unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Labels attached to the issue.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "schedule": { "description": "ID of the schedule that created the issue, or null if none did.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "Scheduled occurrence that created the issue, or null if it was not scheduled.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the issue was created." }, "updated_at": { "description": "Date and time when the issue was last updated." } }, "required": [ "id", "module", "title", "description", "status", "priority", "originator", "assignee", "dependencies", "labels", "schedule", "scheduled_for", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more issues are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get issue `GET /v1/issues/{id}` #### Path parameters - `id` custom — Unique ID of the issue., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue." } ``` #### Response - `id` custom — Unique ID of the issue., required - `module` string — Name of the module that owns the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `status` "open" | "in_progress" | "done" | "canceled" — Current lifecycle status of the issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., required - `originator` string — Account-user ID of the user who created the issue., required - `assignee` string | null — Assigned account-user ID, or null if unassigned., required - `dependencies` string[] — IDs of issues that must finish before this issue., required - `labels` object[] — Labels attached to the issue., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `schedule` string | null — ID of the schedule that created the issue, or null if none did., required - `scheduled_for` custom | null — Scheduled occurrence that created the issue, or null if it was not scheduled., required - `created_at` custom — Date and time when the issue was created., required - `updated_at` custom — Date and time when the issue was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue." }, "module": { "description": "Name of the module that owns the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "status": { "description": "Current lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "originator": { "description": "Account-user ID of the user who created the issue.", "type": "string" }, "assignee": { "description": "Assigned account-user ID, or null if unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Labels attached to the issue.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "schedule": { "description": "ID of the schedule that created the issue, or null if none did.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "Scheduled occurrence that created the issue, or null if it was not scheduled.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the issue was created." }, "updated_at": { "description": "Date and time when the issue was last updated." } }, "required": [ "id", "module", "title", "description", "status", "priority", "originator", "assignee", "dependencies", "labels", "schedule", "scheduled_for", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Update issue `PATCH /v1/issues/{id}` #### Path parameters - `id` custom — Unique ID of the issue., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue." } ``` #### Request body - `title` string — New short title of the issue., optional - `description` string — New premise and required outcome of the issue., optional - `status` "open" | "in_progress" | "done" | "canceled" — New lifecycle status of the issue., optional - `assignee` string | null — Account-user ID to assign, or null to unassign the issue., optional - `priority` "low" | "medium" | "high" | "urgent" | null — New issue priority, or null to clear the priority., optional - `dependencies` string[] — Complete new set of issue dependency IDs., optional - `labels` string[] — Complete new set of label IDs., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "description": "New short title of the issue.", "type": "string" }, "description": { "description": "New premise and required outcome of the issue.", "type": "string" }, "status": { "description": "New lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "assignee": { "description": "Account-user ID to assign, or null to unassign the issue.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "priority": { "description": "New issue priority, or null to clear the priority.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "dependencies": { "description": "Complete new set of issue dependency IDs.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Complete new set of label IDs.", "type": "array", "items": { "type": "string" } } } } ``` #### Response - `id` custom — Unique ID of the issue., required - `module` string — Name of the module that owns the issue., required - `title` string — Short title of the issue., required - `description` string — Premise and required outcome of the issue., required - `status` "open" | "in_progress" | "done" | "canceled" — Current lifecycle status of the issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Issue priority, or null if it is not triaged., required - `originator` string — Account-user ID of the user who created the issue., required - `assignee` string | null — Assigned account-user ID, or null if unassigned., required - `dependencies` string[] — IDs of issues that must finish before this issue., required - `labels` object[] — Labels attached to the issue., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `schedule` string | null — ID of the schedule that created the issue, or null if none did., required - `scheduled_for` custom | null — Scheduled occurrence that created the issue, or null if it was not scheduled., required - `created_at` custom — Date and time when the issue was created., required - `updated_at` custom — Date and time when the issue was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue." }, "module": { "description": "Name of the module that owns the issue.", "type": "string" }, "title": { "description": "Short title of the issue.", "type": "string" }, "description": { "description": "Premise and required outcome of the issue.", "type": "string" }, "status": { "description": "Current lifecycle status of the issue.", "type": "string", "enum": [ "open", "in_progress", "done", "canceled" ] }, "priority": { "description": "Issue priority, or null if it is not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "originator": { "description": "Account-user ID of the user who created the issue.", "type": "string" }, "assignee": { "description": "Assigned account-user ID, or null if unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dependencies": { "description": "IDs of issues that must finish before this issue.", "type": "array", "items": { "type": "string" } }, "labels": { "description": "Labels attached to the issue.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "schedule": { "description": "ID of the schedule that created the issue, or null if none did.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_for": { "description": "Scheduled occurrence that created the issue, or null if it was not scheduled.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the issue was created." }, "updated_at": { "description": "Date and time when the issue was last updated." } }, "required": [ "id", "module", "title", "description", "status", "priority", "originator", "assignee", "dependencies", "labels", "schedule", "scheduled_for", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Delete issue `DELETE /v1/issues/{id}` #### Path parameters - `id` custom — Unique ID of the issue., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue." } ``` #### Response No response body. ## Labels An account-scoped classification that can be attached to Cortex issues. ### Resource schema - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `created_at` custom — Date and time when the label was created., required - `updated_at` custom — Date and time when the label was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] }, "created_at": { "description": "Date and time when the label was created." }, "updated_at": { "description": "Date and time when the label was last updated." } }, "required": [ "id", "name", "color", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Create label `POST /v1/labels` #### Request body - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null to create it without a color., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null to create it without a color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } }, "required": [ "name" ] } ``` #### Response - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `created_at` custom — Date and time when the label was created., required - `updated_at` custom — Date and time when the label was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] }, "created_at": { "description": "Date and time when the label was created." }, "updated_at": { "description": "Date and time when the label was last updated." } }, "required": [ "id", "name", "color", "created_at", "updated_at" ], "additionalProperties": false } ``` ### List labels `GET /v1/labels` #### Query parameters - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Exact label name by which to filter labels., optional - `q` string — Text to find in label names., optional - `limit` integer (min: 1; max: 100) — Maximum number of labels to return., optional - `after` string — Cursor after which to return labels., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "Exact label name by which to filter labels.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "q": { "description": "Text to find in label names.", "type": "string" }, "limit": { "description": "Maximum number of labels to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return labels.", "type": "string" } } } ``` #### Response - `data` object[] — Labels in this page., required - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `created_at` custom — Date and time when the label was created., required - `updated_at` custom — Date and time when the label was last updated., required - `has_more` boolean — Whether more labels are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Labels in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] }, "created_at": { "description": "Date and time when the label was created." }, "updated_at": { "description": "Date and time when the label was last updated." } }, "required": [ "id", "name", "color", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more labels are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get label `GET /v1/labels/{id}` #### Path parameters - `id` custom — Unique ID of the label., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the label." } ``` #### Response - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `created_at` custom — Date and time when the label was created., required - `updated_at` custom — Date and time when the label was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] }, "created_at": { "description": "Date and time when the label was created." }, "updated_at": { "description": "Date and time when the label was last updated." } }, "required": [ "id", "name", "color", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Update label `PATCH /v1/labels/{id}` #### Path parameters - `id` custom — Unique ID of the label., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the label." } ``` #### Request body - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — New account-unique name of the label., optional - `color` string | null — New hex color of the label, or null to clear the color., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "New account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "New hex color of the label, or null to clear the color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] } } } ``` #### Response - `id` custom — Unique ID of the label., required - `name` string (min length: 1; max length: 40; pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$) — Account-unique name of the label., required - `color` string | null — Hex color of the label, or null if it has no color., required - `created_at` custom — Date and time when the label was created., required - `updated_at` custom — Date and time when the label was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the label." }, "name": { "description": "Account-unique name of the label.", "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "color": { "description": "Hex color of the label, or null if it has no color.", "anyOf": [ { "description": "Lowercase six-digit hex color of the label.", "type": "string", "pattern": "^#[0-9a-f]{6}$" }, { "type": "null" } ] }, "created_at": { "description": "Date and time when the label was created." }, "updated_at": { "description": "Date and time when the label was last updated." } }, "required": [ "id", "name", "color", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Delete label `DELETE /v1/labels/{id}` #### Path parameters - `id` custom — Unique ID of the label., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the label." } ``` #### Response No response body. ## Issue schedules A durable recurrence rule that materializes ordinary Cortex issues. ### Resource schema - `id` custom — Unique ID of the issue schedule., required - `module` string — Name of the module that owns generated issues., required - `title` string — Title assigned to each generated issue., required - `description` string — Premise assigned to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority assigned to generated issues, or null if they are not triaged., required - `assignee` string | null — Account-user ID assigned to generated issues, or null if they are unassigned., required - `cron` string — Five-field cron expression that defines the recurrence., required - `timezone` string — IANA time zone in which to evaluate the cron expression., required - `overlap_policy` "coalesce" | "allow" — Behavior when a previous issue from the schedule is still open., required - `missed_run_policy` "next_only" | "catch_up" — Behavior for occurrences missed while the schedule was inactive., required - `enabled` boolean — Whether the schedule can generate issues., required - `next_run_at` custom — Date and time of the next scheduled occurrence., required - `created_by` string — Account-user ID of the user who created the schedule., required - `created_at` custom — Date and time when the schedule was created., required - `updated_at` custom — Date and time when the schedule was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue schedule." }, "module": { "description": "Name of the module that owns generated issues.", "type": "string" }, "title": { "description": "Title assigned to each generated issue.", "type": "string" }, "description": { "description": "Premise assigned to each generated issue.", "type": "string" }, "priority": { "description": "Priority assigned to generated issues, or null if they are not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID assigned to generated issues, or null if they are unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string" }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "type": "string" }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" }, "next_run_at": { "description": "Date and time of the next scheduled occurrence." }, "created_by": { "description": "Account-user ID of the user who created the schedule.", "type": "string" }, "created_at": { "description": "Date and time when the schedule was created." }, "updated_at": { "description": "Date and time when the schedule was last updated." } }, "required": [ "id", "module", "title", "description", "priority", "assignee", "cron", "timezone", "overlap_policy", "missed_run_policy", "enabled", "next_run_at", "created_by", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Create issue schedule `POST /v1/issue-schedules` #### Request body - `module` string — Name of the module that will own generated issues., required - `title` string (min length: 1) — Title to assign to each generated issue., required - `description` string — Premise to assign to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority to assign to generated issues, or null to leave them untriaged., optional - `assignee` string | null — Account-user ID to assign to generated issues, or null to leave them unassigned., optional - `cron` string (min length: 1) — Five-field cron expression that defines the recurrence., required - `timezone` string (default: "UTC"; min length: 1) — IANA time zone in which to evaluate the cron expression., optional - `overlap_policy` "coalesce" | "allow" (default: "coalesce") — Behavior when a previous issue from the schedule is still open., optional - `missed_run_policy` "next_only" | "catch_up" (default: "next_only") — Behavior for occurrences missed while the schedule was inactive., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module": { "description": "Name of the module that will own generated issues.", "type": "string" }, "title": { "description": "Title to assign to each generated issue.", "type": "string", "minLength": 1 }, "description": { "description": "Premise to assign to each generated issue.", "type": "string" }, "priority": { "description": "Priority to assign to generated issues, or null to leave them untriaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID to assign to generated issues, or null to leave them unassigned.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string", "minLength": 1 }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "default": "UTC", "type": "string", "minLength": 1 }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "default": "coalesce", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "default": "next_only", "type": "string", "enum": [ "next_only", "catch_up" ] } }, "required": [ "module", "title", "description", "cron" ] } ``` #### Response - `id` custom — Unique ID of the issue schedule., required - `module` string — Name of the module that owns generated issues., required - `title` string — Title assigned to each generated issue., required - `description` string — Premise assigned to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority assigned to generated issues, or null if they are not triaged., required - `assignee` string | null — Account-user ID assigned to generated issues, or null if they are unassigned., required - `cron` string — Five-field cron expression that defines the recurrence., required - `timezone` string — IANA time zone in which to evaluate the cron expression., required - `overlap_policy` "coalesce" | "allow" — Behavior when a previous issue from the schedule is still open., required - `missed_run_policy` "next_only" | "catch_up" — Behavior for occurrences missed while the schedule was inactive., required - `enabled` boolean — Whether the schedule can generate issues., required - `next_run_at` custom — Date and time of the next scheduled occurrence., required - `created_by` string — Account-user ID of the user who created the schedule., required - `created_at` custom — Date and time when the schedule was created., required - `updated_at` custom — Date and time when the schedule was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue schedule." }, "module": { "description": "Name of the module that owns generated issues.", "type": "string" }, "title": { "description": "Title assigned to each generated issue.", "type": "string" }, "description": { "description": "Premise assigned to each generated issue.", "type": "string" }, "priority": { "description": "Priority assigned to generated issues, or null if they are not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID assigned to generated issues, or null if they are unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string" }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "type": "string" }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" }, "next_run_at": { "description": "Date and time of the next scheduled occurrence." }, "created_by": { "description": "Account-user ID of the user who created the schedule.", "type": "string" }, "created_at": { "description": "Date and time when the schedule was created." }, "updated_at": { "description": "Date and time when the schedule was last updated." } }, "required": [ "id", "module", "title", "description", "priority", "assignee", "cron", "timezone", "overlap_policy", "missed_run_policy", "enabled", "next_run_at", "created_by", "created_at", "updated_at" ], "additionalProperties": false } ``` ### List issue schedules `GET /v1/issue-schedules` #### Query parameters - `module` string — Module name by which to filter issue schedules., optional - `enabled` boolean | "true" | "false" — Whether to return enabled or disabled issue schedules., optional - `limit` integer (min: 1; max: 100) — Maximum number of issue schedules to return., optional - `after` string — Cursor after which to return issue schedules., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module": { "description": "Module name by which to filter issue schedules.", "type": "string" }, "enabled": { "description": "Whether to return enabled or disabled issue schedules.", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "limit": { "description": "Maximum number of issue schedules to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return issue schedules.", "type": "string" } } } ``` #### Response - `data` object[] — Issue schedules in this page., required - `id` custom — Unique ID of the issue schedule., required - `module` string — Name of the module that owns generated issues., required - `title` string — Title assigned to each generated issue., required - `description` string — Premise assigned to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority assigned to generated issues, or null if they are not triaged., required - `assignee` string | null — Account-user ID assigned to generated issues, or null if they are unassigned., required - `cron` string — Five-field cron expression that defines the recurrence., required - `timezone` string — IANA time zone in which to evaluate the cron expression., required - `overlap_policy` "coalesce" | "allow" — Behavior when a previous issue from the schedule is still open., required - `missed_run_policy` "next_only" | "catch_up" — Behavior for occurrences missed while the schedule was inactive., required - `enabled` boolean — Whether the schedule can generate issues., required - `next_run_at` custom — Date and time of the next scheduled occurrence., required - `created_by` string — Account-user ID of the user who created the schedule., required - `created_at` custom — Date and time when the schedule was created., required - `updated_at` custom — Date and time when the schedule was last updated., required - `has_more` boolean — Whether more issue schedules are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Issue schedules in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the issue schedule." }, "module": { "description": "Name of the module that owns generated issues.", "type": "string" }, "title": { "description": "Title assigned to each generated issue.", "type": "string" }, "description": { "description": "Premise assigned to each generated issue.", "type": "string" }, "priority": { "description": "Priority assigned to generated issues, or null if they are not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID assigned to generated issues, or null if they are unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string" }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "type": "string" }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" }, "next_run_at": { "description": "Date and time of the next scheduled occurrence." }, "created_by": { "description": "Account-user ID of the user who created the schedule.", "type": "string" }, "created_at": { "description": "Date and time when the schedule was created." }, "updated_at": { "description": "Date and time when the schedule was last updated." } }, "required": [ "id", "module", "title", "description", "priority", "assignee", "cron", "timezone", "overlap_policy", "missed_run_policy", "enabled", "next_run_at", "created_by", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more issue schedules are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get issue schedule `GET /v1/issue-schedules/{id}` #### Path parameters - `id` custom — Unique ID of the issue schedule., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue schedule." } ``` #### Response - `id` custom — Unique ID of the issue schedule., required - `module` string — Name of the module that owns generated issues., required - `title` string — Title assigned to each generated issue., required - `description` string — Premise assigned to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority assigned to generated issues, or null if they are not triaged., required - `assignee` string | null — Account-user ID assigned to generated issues, or null if they are unassigned., required - `cron` string — Five-field cron expression that defines the recurrence., required - `timezone` string — IANA time zone in which to evaluate the cron expression., required - `overlap_policy` "coalesce" | "allow" — Behavior when a previous issue from the schedule is still open., required - `missed_run_policy` "next_only" | "catch_up" — Behavior for occurrences missed while the schedule was inactive., required - `enabled` boolean — Whether the schedule can generate issues., required - `next_run_at` custom — Date and time of the next scheduled occurrence., required - `created_by` string — Account-user ID of the user who created the schedule., required - `created_at` custom — Date and time when the schedule was created., required - `updated_at` custom — Date and time when the schedule was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue schedule." }, "module": { "description": "Name of the module that owns generated issues.", "type": "string" }, "title": { "description": "Title assigned to each generated issue.", "type": "string" }, "description": { "description": "Premise assigned to each generated issue.", "type": "string" }, "priority": { "description": "Priority assigned to generated issues, or null if they are not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID assigned to generated issues, or null if they are unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string" }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "type": "string" }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" }, "next_run_at": { "description": "Date and time of the next scheduled occurrence." }, "created_by": { "description": "Account-user ID of the user who created the schedule.", "type": "string" }, "created_at": { "description": "Date and time when the schedule was created." }, "updated_at": { "description": "Date and time when the schedule was last updated." } }, "required": [ "id", "module", "title", "description", "priority", "assignee", "cron", "timezone", "overlap_policy", "missed_run_policy", "enabled", "next_run_at", "created_by", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Update issue schedule `PATCH /v1/issue-schedules/{id}` #### Path parameters - `id` custom — Unique ID of the issue schedule., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue schedule." } ``` #### Request body - `title` string (min length: 1) — New title for generated issues., optional - `description` string — New premise for generated issues., optional - `priority` "low" | "medium" | "high" | "urgent" | null — New priority for generated issues, or null to leave them untriaged., optional - `assignee` string | null — New account-user ID for generated issues, or null to leave them unassigned., optional - `cron` string (min length: 1) — New five-field cron expression., optional - `timezone` string (min length: 1) — New IANA time zone., optional - `overlap_policy` "coalesce" | "allow" — New behavior when a previous issue from the schedule is still open., optional - `missed_run_policy` "next_only" | "catch_up" — New behavior for occurrences missed while the schedule was inactive., optional - `enabled` boolean — Whether the schedule can generate issues., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "description": "New title for generated issues.", "type": "string", "minLength": 1 }, "description": { "description": "New premise for generated issues.", "type": "string" }, "priority": { "description": "New priority for generated issues, or null to leave them untriaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "New account-user ID for generated issues, or null to leave them unassigned.", "anyOf": [ { "description": "An account-user ID.", "type": "string" }, { "type": "null" } ] }, "cron": { "description": "New five-field cron expression.", "type": "string", "minLength": 1 }, "timezone": { "description": "New IANA time zone.", "type": "string", "minLength": 1 }, "overlap_policy": { "description": "New behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "New behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" } } } ``` #### Response - `id` custom — Unique ID of the issue schedule., required - `module` string — Name of the module that owns generated issues., required - `title` string — Title assigned to each generated issue., required - `description` string — Premise assigned to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority assigned to generated issues, or null if they are not triaged., required - `assignee` string | null — Account-user ID assigned to generated issues, or null if they are unassigned., required - `cron` string — Five-field cron expression that defines the recurrence., required - `timezone` string — IANA time zone in which to evaluate the cron expression., required - `overlap_policy` "coalesce" | "allow" — Behavior when a previous issue from the schedule is still open., required - `missed_run_policy` "next_only" | "catch_up" — Behavior for occurrences missed while the schedule was inactive., required - `enabled` boolean — Whether the schedule can generate issues., required - `next_run_at` custom — Date and time of the next scheduled occurrence., required - `created_by` string — Account-user ID of the user who created the schedule., required - `created_at` custom — Date and time when the schedule was created., required - `updated_at` custom — Date and time when the schedule was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue schedule." }, "module": { "description": "Name of the module that owns generated issues.", "type": "string" }, "title": { "description": "Title assigned to each generated issue.", "type": "string" }, "description": { "description": "Premise assigned to each generated issue.", "type": "string" }, "priority": { "description": "Priority assigned to generated issues, or null if they are not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID assigned to generated issues, or null if they are unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string" }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "type": "string" }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" }, "next_run_at": { "description": "Date and time of the next scheduled occurrence." }, "created_by": { "description": "Account-user ID of the user who created the schedule.", "type": "string" }, "created_at": { "description": "Date and time when the schedule was created." }, "updated_at": { "description": "Date and time when the schedule was last updated." } }, "required": [ "id", "module", "title", "description", "priority", "assignee", "cron", "timezone", "overlap_policy", "missed_run_policy", "enabled", "next_run_at", "created_by", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Delete issue schedule `DELETE /v1/issue-schedules/{id}` #### Path parameters - `id` custom — Unique ID of the issue schedule., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue schedule." } ``` #### Response No response body. ### Queue an immediate issue schedule run `POST /v1/issue-schedules/{id}/run` #### Path parameters - `id` custom — Unique ID of the issue schedule., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue schedule." } ``` #### Response - `id` custom — Unique ID of the issue schedule., required - `module` string — Name of the module that owns generated issues., required - `title` string — Title assigned to each generated issue., required - `description` string — Premise assigned to each generated issue., required - `priority` "low" | "medium" | "high" | "urgent" | null — Priority assigned to generated issues, or null if they are not triaged., required - `assignee` string | null — Account-user ID assigned to generated issues, or null if they are unassigned., required - `cron` string — Five-field cron expression that defines the recurrence., required - `timezone` string — IANA time zone in which to evaluate the cron expression., required - `overlap_policy` "coalesce" | "allow" — Behavior when a previous issue from the schedule is still open., required - `missed_run_policy` "next_only" | "catch_up" — Behavior for occurrences missed while the schedule was inactive., required - `enabled` boolean — Whether the schedule can generate issues., required - `next_run_at` custom — Date and time of the next scheduled occurrence., required - `created_by` string — Account-user ID of the user who created the schedule., required - `created_at` custom — Date and time when the schedule was created., required - `updated_at` custom — Date and time when the schedule was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue schedule." }, "module": { "description": "Name of the module that owns generated issues.", "type": "string" }, "title": { "description": "Title assigned to each generated issue.", "type": "string" }, "description": { "description": "Premise assigned to each generated issue.", "type": "string" }, "priority": { "description": "Priority assigned to generated issues, or null if they are not triaged.", "anyOf": [ { "description": "Urgency of an issue relative to other work.", "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, { "type": "null" } ] }, "assignee": { "description": "Account-user ID assigned to generated issues, or null if they are unassigned.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cron": { "description": "Five-field cron expression that defines the recurrence.", "type": "string" }, "timezone": { "description": "IANA time zone in which to evaluate the cron expression.", "type": "string" }, "overlap_policy": { "description": "Behavior when a previous issue from the schedule is still open.", "type": "string", "enum": [ "coalesce", "allow" ] }, "missed_run_policy": { "description": "Behavior for occurrences missed while the schedule was inactive.", "type": "string", "enum": [ "next_only", "catch_up" ] }, "enabled": { "description": "Whether the schedule can generate issues.", "type": "boolean" }, "next_run_at": { "description": "Date and time of the next scheduled occurrence." }, "created_by": { "description": "Account-user ID of the user who created the schedule.", "type": "string" }, "created_at": { "description": "Date and time when the schedule was created." }, "updated_at": { "description": "Date and time when the schedule was last updated." } }, "required": [ "id", "module", "title", "description", "priority", "assignee", "cron", "timezone", "overlap_policy", "missed_run_policy", "enabled", "next_run_at", "created_by", "created_at", "updated_at" ], "additionalProperties": false } ``` ## Comments An authored note on an issue — the issue's own progress narrative. ### Resource schema - `id` custom — Unique ID of the comment., required - `issue` custom — ID of the issue that contains the comment., required - `author` string — Account-user ID of the comment author., required - `body` string — Authored content of the comment., required - `created_at` custom — Date and time when the comment was created., required - `updated_at` custom — Date and time when the comment was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the comment." }, "issue": { "description": "ID of the issue that contains the comment." }, "author": { "description": "Account-user ID of the comment author.", "type": "string" }, "body": { "description": "Authored content of the comment.", "type": "string" }, "created_at": { "description": "Date and time when the comment was created." }, "updated_at": { "description": "Date and time when the comment was last updated." } }, "required": [ "id", "issue", "author", "body", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Create comment `POST /v1/comments` #### Request body - `issue` string — ID of the issue on which to comment., required - `body` string — Authored content of the comment., required - `attachments` string[] (max items: 20) — IDs of completed issue attachments to place in the comment., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "issue": { "description": "ID of the issue on which to comment.", "type": "string" }, "body": { "description": "Authored content of the comment.", "type": "string" }, "attachments": { "description": "IDs of completed issue attachments to place in the comment.", "maxItems": 20, "type": "array", "items": { "type": "string" } } }, "required": [ "issue", "body" ] } ``` #### Response - `id` custom — Unique ID of the comment., required - `issue` custom — ID of the issue that contains the comment., required - `author` string — Account-user ID of the comment author., required - `body` string — Authored content of the comment., required - `created_at` custom — Date and time when the comment was created., required - `updated_at` custom — Date and time when the comment was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the comment." }, "issue": { "description": "ID of the issue that contains the comment." }, "author": { "description": "Account-user ID of the comment author.", "type": "string" }, "body": { "description": "Authored content of the comment.", "type": "string" }, "created_at": { "description": "Date and time when the comment was created." }, "updated_at": { "description": "Date and time when the comment was last updated." } }, "required": [ "id", "issue", "author", "body", "created_at", "updated_at" ], "additionalProperties": false } ``` ### List comments `GET /v1/comments` #### Query parameters - `issue` string — ID of the issue whose comments to return., required - `limit` integer (min: 1; max: 100) — Maximum number of comments to return., optional - `after` string — Cursor after which to return comments., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "issue": { "description": "ID of the issue whose comments to return.", "type": "string" }, "limit": { "description": "Maximum number of comments to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return comments.", "type": "string" } }, "required": [ "issue" ] } ``` #### Response - `data` object[] — Comments in this page., required - `id` custom — Unique ID of the comment., required - `issue` custom — ID of the issue that contains the comment., required - `author` string — Account-user ID of the comment author., required - `body` string — Authored content of the comment., required - `created_at` custom — Date and time when the comment was created., required - `updated_at` custom — Date and time when the comment was last updated., required - `has_more` boolean — Whether more comments are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Comments in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the comment." }, "issue": { "description": "ID of the issue that contains the comment." }, "author": { "description": "Account-user ID of the comment author.", "type": "string" }, "body": { "description": "Authored content of the comment.", "type": "string" }, "created_at": { "description": "Date and time when the comment was created." }, "updated_at": { "description": "Date and time when the comment was last updated." } }, "required": [ "id", "issue", "author", "body", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more comments are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get comment `GET /v1/comments/{id}` #### Path parameters - `id` custom — Unique ID of the comment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the comment." } ``` #### Response - `id` custom — Unique ID of the comment., required - `issue` custom — ID of the issue that contains the comment., required - `author` string — Account-user ID of the comment author., required - `body` string — Authored content of the comment., required - `created_at` custom — Date and time when the comment was created., required - `updated_at` custom — Date and time when the comment was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the comment." }, "issue": { "description": "ID of the issue that contains the comment." }, "author": { "description": "Account-user ID of the comment author.", "type": "string" }, "body": { "description": "Authored content of the comment.", "type": "string" }, "created_at": { "description": "Date and time when the comment was created." }, "updated_at": { "description": "Date and time when the comment was last updated." } }, "required": [ "id", "issue", "author", "body", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Update comment `PATCH /v1/comments/{id}` #### Path parameters - `id` custom — Unique ID of the comment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the comment." } ``` #### Request body - `body` string — New authored content of the comment., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "body": { "description": "New authored content of the comment.", "type": "string" } }, "required": [ "body" ] } ``` #### Response - `id` custom — Unique ID of the comment., required - `issue` custom — ID of the issue that contains the comment., required - `author` string — Account-user ID of the comment author., required - `body` string — Authored content of the comment., required - `created_at` custom — Date and time when the comment was created., required - `updated_at` custom — Date and time when the comment was last updated., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the comment." }, "issue": { "description": "ID of the issue that contains the comment." }, "author": { "description": "Account-user ID of the comment author.", "type": "string" }, "body": { "description": "Authored content of the comment.", "type": "string" }, "created_at": { "description": "Date and time when the comment was created." }, "updated_at": { "description": "Date and time when the comment was last updated." } }, "required": [ "id", "issue", "author", "body", "created_at", "updated_at" ], "additionalProperties": false } ``` ### Delete comment `DELETE /v1/comments/{id}` #### Path parameters - `id` custom — Unique ID of the comment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the comment." } ``` #### Response No response body. ## Issue attachments A private file owned by an issue and authorized through its module. ### Resource schema - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false } ``` ### Prepare issue attachment upload `POST /v1/issue-attachments` #### Request body - `issue` string — ID of the issue that will own the attachment., required - `filename` string (min length: 1; max length: 255) — Original name of the file., required - `media_type` string (min length: 1; max length: 255; pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$) — MIME type of the file., required - `byte_size` integer (greater than: 0; max: 26214400) — Size of the file in bytes. The maximum size is 25 MiB., required - `checksum_sha256` string (pattern: ^[A-Za-z0-9+/]{43}=$) — Base64-encoded SHA-256 checksum of the file., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "issue": { "description": "ID of the issue that will own the attachment.", "type": "string" }, "filename": { "description": "Original name of the file.", "type": "string", "minLength": 1, "maxLength": 255 }, "media_type": { "description": "MIME type of the file.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+\\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$" }, "byte_size": { "description": "Size of the file in bytes. The maximum size is 25 MiB.", "type": "integer", "exclusiveMinimum": 0, "maximum": 26214400 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" } }, "required": [ "issue", "filename", "media_type", "byte_size", "checksum_sha256" ] } ``` #### Response - `attachment` object — Attachment that is ready for upload., required - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required - `upload` object — Signed upload request., required - `url` string (format: uri) — Signed URL that accepts the file upload., required - `method` "PUT" — HTTP method to use for the upload., required - `headers` object — HTTP headers to include in the upload request., required - `expires_at` custom — Date and time when the upload URL expires., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attachment": { "description": "Attachment that is ready for upload.", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false }, "upload": { "description": "Signed upload request.", "type": "object", "properties": { "url": { "description": "Signed URL that accepts the file upload.", "type": "string", "format": "uri" }, "method": { "description": "HTTP method to use for the upload.", "type": "string", "const": "PUT" }, "headers": { "description": "HTTP headers to include in the upload request.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expires_at": { "description": "Date and time when the upload URL expires." } }, "required": [ "url", "method", "headers", "expires_at" ], "additionalProperties": false } }, "required": [ "attachment", "upload" ], "additionalProperties": false } ``` ### List issue attachments `GET /v1/issue-attachments` #### Query parameters - `issue` string — ID of the issue that owns the attachments., required - `limit` integer (min: 1; max: 100) — Maximum number of attachments to return., optional - `after` string — Cursor after which to return attachments., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "issue": { "description": "ID of the issue that owns the attachments.", "type": "string" }, "limit": { "description": "Maximum number of attachments to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return attachments.", "type": "string" } }, "required": [ "issue" ] } ``` #### Response - `data` object[] — Attachments in this page., required - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required - `has_more` boolean — Whether more attachments are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Attachments in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more attachments are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get issue attachment `GET /v1/issue-attachments/{id}` #### Path parameters - `id` custom — Unique ID of the attachment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the attachment." } ``` #### Response - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false } ``` ### Complete issue attachment upload `POST /v1/issue-attachments/{id}/complete` #### Path parameters - `id` custom — Unique ID of the attachment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the attachment." } ``` #### Response - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false } ``` ### Get issue attachment download `POST /v1/issue-attachments/{id}/download` #### Path parameters - `id` custom — Unique ID of the attachment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the attachment." } ``` #### Response - `url` string (format: uri) — Signed URL from which to download the file., required - `expires_at` custom — Date and time when the download URL expires., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "description": "Signed URL from which to download the file.", "type": "string", "format": "uri" }, "expires_at": { "description": "Date and time when the download URL expires." } }, "required": [ "url", "expires_at" ], "additionalProperties": false } ``` ### Remove issue attachment `DELETE /v1/issue-attachments/{id}` #### Path parameters - `id` custom — Unique ID of the attachment., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the attachment." } ``` #### Response No response body. ## Comment attachments A placement of an issue-owned attachment in an authored issue comment. ### Resource schema - `id` custom — Unique ID of the placement., required - `issue` custom — ID of the issue that owns the attachment., required - `comment` custom — ID of the comment that contains the attachment., required - `attachment` object — Attachment placed in the comment., required - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required - `position` integer (min: 0; max: 9007199254740991) — Zero-based display position of the attachment in the comment., required - `created_at` custom — Date and time when the placement was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the placement." }, "issue": { "description": "ID of the issue that owns the attachment." }, "comment": { "description": "ID of the comment that contains the attachment." }, "attachment": { "description": "Attachment placed in the comment.", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false }, "position": { "description": "Zero-based display position of the attachment in the comment.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "description": "Date and time when the placement was created." } }, "required": [ "id", "issue", "comment", "attachment", "position", "created_at" ], "additionalProperties": false } ``` ### Place attachment in comment `POST /v1/comment-attachments` #### Request body - `comment` string — ID of the comment in which to place the attachment., required - `attachment` string — ID of the attachment to place in the comment., required - `position` integer (min: 0; max: 9007199254740991) — Zero-based display position of the attachment in the comment., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "comment": { "description": "ID of the comment in which to place the attachment.", "type": "string" }, "attachment": { "description": "ID of the attachment to place in the comment.", "type": "string" }, "position": { "description": "Zero-based display position of the attachment in the comment.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "comment", "attachment" ] } ``` #### Response - `id` custom — Unique ID of the placement., required - `issue` custom — ID of the issue that owns the attachment., required - `comment` custom — ID of the comment that contains the attachment., required - `attachment` object — Attachment placed in the comment., required - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required - `position` integer (min: 0; max: 9007199254740991) — Zero-based display position of the attachment in the comment., required - `created_at` custom — Date and time when the placement was created., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the placement." }, "issue": { "description": "ID of the issue that owns the attachment." }, "comment": { "description": "ID of the comment that contains the attachment." }, "attachment": { "description": "Attachment placed in the comment.", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false }, "position": { "description": "Zero-based display position of the attachment in the comment.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "description": "Date and time when the placement was created." } }, "required": [ "id", "issue", "comment", "attachment", "position", "created_at" ], "additionalProperties": false } ``` ### List comment attachments `GET /v1/comment-attachments` #### Query parameters - `comment` string — ID of the comment by which to filter placements., optional - `issue` string — ID of the issue by which to filter placements., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "comment": { "description": "ID of the comment by which to filter placements.", "type": "string" }, "issue": { "description": "ID of the issue by which to filter placements.", "type": "string" } } } ``` #### Response - `data` object[] — Attachment placements in this page., required - `id` custom — Unique ID of the placement., required - `issue` custom — ID of the issue that owns the attachment., required - `comment` custom — ID of the comment that contains the attachment., required - `attachment` object — Attachment placed in the comment., required - `id` custom — Unique ID of the attachment., required - `issue` custom — ID of the issue that owns the attachment., required - `filename` string — Original name of the uploaded file., required - `media_type` string — MIME type of the uploaded file., required - `byte_size` integer (min: 0; max: 9007199254740991) — Size of the file in bytes., required - `checksum_sha256` string — Base64-encoded SHA-256 checksum of the file., required - `state` "pending" | "ready" — Upload state of the attachment., required - `uploaded_by` string — Account-user ID of the user who uploaded the file., required - `comments` custom[] — IDs of the comments that contain the attachment., required - `uploaded_at` custom | null — Date and time when the upload completed, or null if it is incomplete., required - `deleted_at` custom | null — Date and time when the file was removed, or null if it is available., required - `created_at` custom — Date and time when the attachment was created., required - `position` integer (min: 0; max: 9007199254740991) — Zero-based display position of the attachment in the comment., required - `created_at` custom — Date and time when the placement was created., required - `has_more` false — Whether more attachment placements are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Attachment placements in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the placement." }, "issue": { "description": "ID of the issue that owns the attachment." }, "comment": { "description": "ID of the comment that contains the attachment." }, "attachment": { "description": "Attachment placed in the comment.", "type": "object", "properties": { "id": { "description": "Unique ID of the attachment." }, "issue": { "description": "ID of the issue that owns the attachment." }, "filename": { "description": "Original name of the uploaded file.", "type": "string" }, "media_type": { "description": "MIME type of the uploaded file.", "type": "string" }, "byte_size": { "description": "Size of the file in bytes.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "checksum_sha256": { "description": "Base64-encoded SHA-256 checksum of the file.", "type": "string" }, "state": { "description": "Upload state of the attachment.", "type": "string", "enum": [ "pending", "ready" ] }, "uploaded_by": { "description": "Account-user ID of the user who uploaded the file.", "type": "string" }, "comments": { "description": "IDs of the comments that contain the attachment.", "type": "array", "items": {} }, "uploaded_at": { "description": "Date and time when the upload completed, or null if it is incomplete.", "anyOf": [ {}, { "type": "null" } ] }, "deleted_at": { "description": "Date and time when the file was removed, or null if it is available.", "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "description": "Date and time when the attachment was created." } }, "required": [ "id", "issue", "filename", "media_type", "byte_size", "checksum_sha256", "state", "uploaded_by", "comments", "uploaded_at", "deleted_at", "created_at" ], "additionalProperties": false }, "position": { "description": "Zero-based display position of the attachment in the comment.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "description": "Date and time when the placement was created." } }, "required": [ "id", "issue", "comment", "attachment", "position", "created_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more attachment placements are available.", "type": "boolean", "const": false } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Remove attachment from comment `DELETE /v1/comment-attachments/{id}` #### Path parameters - `id` custom — Unique ID of the placement., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the placement." } ``` #### Response No response body. ## Issue events An immutable record of a state change to an issue — its timeline. ### Resource schema - `id` custom — Unique ID of the issue event., required - `issue` custom — ID of the issue that contains the event., required - `actor` string — Account-user ID that caused the state change., required - `type` "created" | "status_changed" | "assigned" | "prioritized" | "retitled" | "redescribed" | "dependencies_changed" | "labels_changed" — Type of state change recorded by the event., required - `data` object — State-change details for the event., required - `created_at` custom — Date and time when the state change occurred., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue event." }, "issue": { "description": "ID of the issue that contains the event." }, "actor": { "description": "Account-user ID that caused the state change.", "type": "string" }, "type": { "description": "Type of state change recorded by the event.", "type": "string", "enum": [ "created", "status_changed", "assigned", "prioritized", "retitled", "redescribed", "dependencies_changed", "labels_changed" ] }, "data": { "description": "State-change details for the event.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "created_at": { "description": "Date and time when the state change occurred." } }, "required": [ "id", "issue", "actor", "type", "data", "created_at" ], "additionalProperties": false } ``` ### List issue events `GET /v1/issue-events` #### Query parameters - `issue` string — ID of the issue whose events to return., required - `limit` integer (min: 1; max: 100) — Maximum number of issue events to return., optional - `after` string — Cursor after which to return issue events., optional JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "issue": { "description": "ID of the issue whose events to return.", "type": "string" }, "limit": { "description": "Maximum number of issue events to return.", "type": "integer", "minimum": 1, "maximum": 100 }, "after": { "description": "Cursor after which to return issue events.", "type": "string" } }, "required": [ "issue" ] } ``` #### Response - `data` object[] — Issue events in this page., required - `id` custom — Unique ID of the issue event., required - `issue` custom — ID of the issue that contains the event., required - `actor` string — Account-user ID that caused the state change., required - `type` "created" | "status_changed" | "assigned" | "prioritized" | "retitled" | "redescribed" | "dependencies_changed" | "labels_changed" — Type of state change recorded by the event., required - `data` object — State-change details for the event., required - `created_at` custom — Date and time when the state change occurred., required - `has_more` boolean — Whether more issue events are available., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "description": "Issue events in this page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique ID of the issue event." }, "issue": { "description": "ID of the issue that contains the event." }, "actor": { "description": "Account-user ID that caused the state change.", "type": "string" }, "type": { "description": "Type of state change recorded by the event.", "type": "string", "enum": [ "created", "status_changed", "assigned", "prioritized", "retitled", "redescribed", "dependencies_changed", "labels_changed" ] }, "data": { "description": "State-change details for the event.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "created_at": { "description": "Date and time when the state change occurred." } }, "required": [ "id", "issue", "actor", "type", "data", "created_at" ], "additionalProperties": false } }, "has_more": { "description": "Whether more issue events are available.", "type": "boolean" } }, "required": [ "data", "has_more" ], "additionalProperties": false } ``` ### Get issue event `GET /v1/issue-events/{id}` #### Path parameters - `id` custom — Unique ID of the issue event., required ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Unique ID of the issue event." } ``` #### Response - `id` custom — Unique ID of the issue event., required - `issue` custom — ID of the issue that contains the event., required - `actor` string — Account-user ID that caused the state change., required - `type` "created" | "status_changed" | "assigned" | "prioritized" | "retitled" | "redescribed" | "dependencies_changed" | "labels_changed" — Type of state change recorded by the event., required - `data` object — State-change details for the event., required - `created_at` custom — Date and time when the state change occurred., required JSON Schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "description": "Unique ID of the issue event." }, "issue": { "description": "ID of the issue that contains the event." }, "actor": { "description": "Account-user ID that caused the state change.", "type": "string" }, "type": { "description": "Type of state change recorded by the event.", "type": "string", "enum": [ "created", "status_changed", "assigned", "prioritized", "retitled", "redescribed", "dependencies_changed", "labels_changed" ] }, "data": { "description": "State-change details for the event.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "created_at": { "description": "Date and time when the state change occurred." } }, "required": [ "id", "issue", "actor", "type", "data", "created_at" ], "additionalProperties": false } ```