Skip to content
Workspace
Docs

Cortex API reference

Use the Cortex API to work with Modules, Flashes, Issues, 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 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.

Base URL

https://cortex.socra.cloud

Modules

A context module — a self-contained unit of specific knowledge, addressed by name within an account.

Create module

POST/v1/modules

Request body

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

dependenciesstring[]optional

Names of the direct module dependencies.

visibility"internal" | "private"optional

Visibility of the module within its account.

parentstring | nulloptional

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanoptional

Whether the module uses the permission policy of its parent.

Response

13 fields

idcustomrequired

Stable unique ID of the module.

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

versionintegerrequired

Current knowledge revision of the module.

greater than: 0 · max: 9007199254740991
archivedbooleanrequired

Whether the module is archived.

visibility"internal" | "private"required

Visibility of the module within its account.

dependenciesstring[]required

Names of the direct module dependencies.

ownerstringrequired

Account-user ID of the module owner.

default_assigneestring | nullrequired

Default account-user ID for unassigned work, or null if none is set.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanrequired

Whether the module uses the permission policy of its parent.

created_atcustomrequired

Date and time when the module was created.

updated_atcustomrequired

Date and time when the module was last updated.

List modules

GET/v1/modules

Query parameters

qstringoptional

Text to find in module names or content.

ownerstringoptional

Account-user ID by which to filter modules.

state"active" | "archived" | "all"optional

Archival state by which to filter modules.

limitintegeroptional

Maximum number of modules to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return modules.

Response

2 fields

dataobject[]required

Modules in this page.

idcustomrequired

Stable unique ID of the module.

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

versionintegerrequired

Current knowledge revision of the module.

greater than: 0 · max: 9007199254740991
archivedbooleanrequired

Whether the module is archived.

visibility"internal" | "private"required

Visibility of the module within its account.

dependenciesstring[]required

Names of the direct module dependencies.

ownerstringrequired

Account-user ID of the module owner.

default_assigneestring | nullrequired

Default account-user ID for unassigned work, or null if none is set.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanrequired

Whether the module uses the permission policy of its parent.

created_atcustomrequired

Date and time when the module was created.

updated_atcustomrequired

Date and time when the module was last updated.

has_morebooleanrequired

Whether more modules are available.

Get module

GET/v1/modules/{name}

Path parameters

namestringrequired

Account-unique name of the module.

Query parameters

No query parameters

Response

13 fields

idcustomrequired

Stable unique ID of the module.

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

versionintegerrequired

Current knowledge revision of the module.

greater than: 0 · max: 9007199254740991
archivedbooleanrequired

Whether the module is archived.

visibility"internal" | "private"required

Visibility of the module within its account.

dependenciesstring[]required

Names of the direct module dependencies.

ownerstringrequired

Account-user ID of the module owner.

default_assigneestring | nullrequired

Default account-user ID for unassigned work, or null if none is set.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanrequired

Whether the module uses the permission policy of its parent.

created_atcustomrequired

Date and time when the module was created.

updated_atcustomrequired

Date and time when the module was last updated.

Update module

PATCH/v1/modules/{name}

Path parameters

namestringrequired

Account-unique name of the module.

Request body

namestringoptional

New account-unique name of the module.

contentstringoptional

New authored knowledge content of the module.

dependenciesstring[]optional

Complete new set of direct module dependency names.

visibility"internal" | "private"optional

New visibility of the module within its account.

ownerstringoptional

Account-user ID of the new module owner.

default_assigneestring | nulloptional

New default account-user ID for unassigned work, or null to clear it.

parentstring | nulloptional

New organizational parent name, or null to make the module a root.

inherit_permissionsbooleanoptional

Whether the module uses the permission policy of its parent.

Response

13 fields

idcustomrequired

Stable unique ID of the module.

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

versionintegerrequired

Current knowledge revision of the module.

greater than: 0 · max: 9007199254740991
archivedbooleanrequired

Whether the module is archived.

visibility"internal" | "private"required

Visibility of the module within its account.

dependenciesstring[]required

Names of the direct module dependencies.

ownerstringrequired

Account-user ID of the module owner.

default_assigneestring | nullrequired

Default account-user ID for unassigned work, or null if none is set.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanrequired

Whether the module uses the permission policy of its parent.

created_atcustomrequired

Date and time when the module was created.

updated_atcustomrequired

Date and time when the module was last updated.

List module versions

GET/v1/modules/{name}/versions

Path parameters

namestringrequired

Account-unique name of the module.

Query parameters

limitintegeroptional

Maximum number of module versions to return.

min: 1 · max: 100
afterintegeroptional

Version number before which to return older versions.

greater than: 0 · max: 9007199254740991

Response

2 fields

dataobject[]required

Module versions in this page.

module_idcustomrequired

Stable ID of the versioned module.

versionintegerrequired

Revision number of this module version.

greater than: 0 · max: 9007199254740991
namestringrequired

Module name in this version.

contentstringrequired

Authored knowledge content in this version.

dependenciesstring[]required

Direct dependency names in this version.

ownerstringrequired

Account-user ID of the module owner in this version.

default_assigneestring | nullrequired

Default account-user ID in this version, or null if none was set.

visibility"internal" | "private"required

Module visibility in this version.

archivedboolean | nullrequired

Archive state in this version; null for older snapshots where it was not recorded.

authorstring | nullrequired

Account-user ID of the version author, or null if unknown.

source"create" | "update" | "backfill"required

Operation that created the module version.

changed_fields"name" | "content" | "dependencies" | "owner" | "default_assignee" | "visibility" | "archived"[]required

Module fields that changed in this version.

created_atcustomrequired

Date and time when the module version was created.

has_morebooleanrequired

Whether more module versions are available.

Get module version

GET/v1/modules/{name}/versions/{version}

Path parameters

namestringrequired

Account-unique name of the module.

versionintegerrequired

Module version number.

greater than: 0 · max: 9007199254740991

Query parameters

No query parameters

Response

13 fields

module_idcustomrequired

Stable ID of the versioned module.

versionintegerrequired

Revision number of this module version.

greater than: 0 · max: 9007199254740991
namestringrequired

Module name in this version.

contentstringrequired

Authored knowledge content in this version.

dependenciesstring[]required

Direct dependency names in this version.

ownerstringrequired

Account-user ID of the module owner in this version.

default_assigneestring | nullrequired

Default account-user ID in this version, or null if none was set.

visibility"internal" | "private"required

Module visibility in this version.

archivedboolean | nullrequired

Archive state in this version; null for older snapshots where it was not recorded.

authorstring | nullrequired

Account-user ID of the version author, or null if unknown.

source"create" | "update" | "backfill"required

Operation that created the module version.

changed_fields"name" | "content" | "dependencies" | "owner" | "default_assignee" | "visibility" | "archived"[]required

Module fields that changed in this version.

created_atcustomrequired

Date and time when the module version was created.

Archive module

POST/v1/modules/{name}/archive

Path parameters

namestringrequired

Account-unique name of the module.

Request body

No request body

Response

13 fields

idcustomrequired

Stable unique ID of the module.

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

versionintegerrequired

Current knowledge revision of the module.

greater than: 0 · max: 9007199254740991
archivedbooleanrequired

Whether the module is archived.

visibility"internal" | "private"required

Visibility of the module within its account.

dependenciesstring[]required

Names of the direct module dependencies.

ownerstringrequired

Account-user ID of the module owner.

default_assigneestring | nullrequired

Default account-user ID for unassigned work, or null if none is set.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanrequired

Whether the module uses the permission policy of its parent.

created_atcustomrequired

Date and time when the module was created.

updated_atcustomrequired

Date and time when the module was last updated.

Restore module

POST/v1/modules/{name}/restore

Path parameters

namestringrequired

Account-unique name of the module.

Request body

contentstringoptional

Replacement body committed with restoration; omitted preserves the body.

dependenciesstring[]optional

Complete final dependency list; omitted preserves links, [] removes all links.

Response

13 fields

idcustomrequired

Stable unique ID of the module.

namestringrequired

Account-unique name of the module.

contentstringrequired

Authored knowledge content of the module.

versionintegerrequired

Current knowledge revision of the module.

greater than: 0 · max: 9007199254740991
archivedbooleanrequired

Whether the module is archived.

visibility"internal" | "private"required

Visibility of the module within its account.

dependenciesstring[]required

Names of the direct module dependencies.

ownerstringrequired

Account-user ID of the module owner.

default_assigneestring | nullrequired

Default account-user ID for unassigned work, or null if none is set.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

inherit_permissionsbooleanrequired

Whether the module uses the permission policy of its parent.

created_atcustomrequired

Date and time when the module was created.

updated_atcustomrequired

Date and time when the module was last updated.

Delete module

DELETE/v1/modules/{name}

Path parameters

namestringrequired

Account-unique name of the module.

Query parameters

No query parameters

Response

No response body

Module graph

POST/v1/modules/graph

Request body

No request body

Response

1 field

nodesobject[]required

Accessible modules and their direct dependency edges.

namestringrequired

Account-unique name of the module.

summarystringrequired

First meaningful line of the module content.

ownerstringrequired

Account-user ID of the module owner.

visibility"internal" | "private"required

Visibility of the module within its account.

parentstring | nullrequired

Name of the organizational parent, or null for a root module.

depends_onstring[]required

Names of the direct module dependencies.

Module permissions

The effective permission policy projected through a Cortex module.

Get module permissions

GET/v1/modules/{name}/permissions

Path parameters

namestringrequired

Account-unique name of the module.

Query parameters

No query parameters

Response

4 fields

inheritedbooleanrequired

Whether the module uses the permission policy of an ancestor.

inherited_fromstring | nullrequired

Name of the module that owns the effective policy, or null for this module.

etagstringrequired

Opaque revision tag of the effective permission policy.

bindingsobject[]required

Role bindings in the effective policy.

role"admin" | "editor" | "commenter" | "viewer"required

Access role granted by this binding.

membersobject[]required

Principals and groups that receive the access role.

min items: 1

Set module permissions

PATCH/v1/modules/{name}/permissions

Path parameters

namestringrequired

Account-unique name of the module.

Request body

etagstringrequired

Revision tag that the current policy must match.

min length: 1
bindingsobject[]required

Complete new set of role bindings.

role"admin" | "editor" | "commenter" | "viewer"required

Access role granted by this binding.

membersobject[]required

Principals and groups that receive the access role.

min items: 1

Response

4 fields

inheritedbooleanrequired

Whether the module uses the permission policy of an ancestor.

inherited_fromstring | nullrequired

Name of the module that owns the effective policy, or null for this module.

etagstringrequired

Opaque revision tag of the effective permission policy.

bindingsobject[]required

Role bindings in the effective policy.

role"admin" | "editor" | "commenter" | "viewer"required

Access role granted by this binding.

membersobject[]required

Principals and groups that receive the access role.

min items: 1

Flashes

A flash — one assembly of a target module's dependency closure into a single context bundle. The metered consume verb of Cortex.

Flash a module

POST/v1/flashes

Request body

targetstringrequired

Name of the module to flash.

Response

7 fields

idcustomrequired

Unique ID of the flash.

targetstringrequired

Name of the module that was explicitly flashed.

total_tokensnumberrequired

Total tokens in the assembled dependency closure.

module_countnumberrequired

Number of modules in the assembled dependency closure.

linesobject[]required

Immutable module manifest for the flash.

modulestringrequired

Name of the module in the flash closure.

versioninteger | nullrequired

Module revision used in the flash, or null for a legacy record.

tokensnumberrequired

Tokens attributed to the module in this flash.

is_targetbooleanrequired

Whether this module was the explicit flash target.

created_atcustomrequired

Date and time when the flash was created.

assemblyobjectrequired

Context bundle produced by the flash.

targetstringrequired

Name of the module that was explicitly flashed.

modulesobject[]required

Dependency closure in foundation-first order.

namestringrequired

Account-unique name of the assembled module.

contentstringrequired

Authored knowledge content of the assembled module.

depends_onstring[]required

Names of the direct module dependencies.

List flashes

GET/v1/flashes

Query parameters

targetstringoptional

Target module name by which to filter flashes.

limitintegeroptional

Maximum number of flashes to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return flashes.

Response

2 fields

dataobject[]required

Flashes in this page.

idcustomrequired

Unique ID of the flash.

targetstringrequired

Name of the module that was explicitly flashed.

total_tokensnumberrequired

Total tokens in the assembled dependency closure.

module_countnumberrequired

Number of modules in the assembled dependency closure.

linesobject[]required

Immutable module manifest for the flash.

modulestringrequired

Name of the module in the flash closure.

versioninteger | nullrequired

Module revision used in the flash, or null for a legacy record.

tokensnumberrequired

Tokens attributed to the module in this flash.

is_targetbooleanrequired

Whether this module was the explicit flash target.

created_atcustomrequired

Date and time when the flash was created.

has_morebooleanrequired

Whether more flashes are available.

Get a flash

GET/v1/flashes/{id}

Path parameters

idcustomrequired

Unique ID of the flash.

Query parameters

No query parameters

Response

6 fields

idcustomrequired

Unique ID of the flash.

targetstringrequired

Name of the module that was explicitly flashed.

total_tokensnumberrequired

Total tokens in the assembled dependency closure.

module_countnumberrequired

Number of modules in the assembled dependency closure.

linesobject[]required

Immutable module manifest for the flash.

modulestringrequired

Name of the module in the flash closure.

versioninteger | nullrequired

Module revision used in the flash, or null for a legacy record.

tokensnumberrequired

Tokens attributed to the module in this flash.

is_targetbooleanrequired

Whether this module was the explicit flash target.

created_atcustomrequired

Date and time when the flash was created.

Get a flash assembly

GET/v1/flashes/{id}/assembly

Path parameters

idcustomrequired

Unique ID of the flash.

Query parameters

No query parameters

Response

2 fields

targetstringrequired

Name of the module that was explicitly flashed.

modulesobject[]required

Dependency closure in foundation-first order.

namestringrequired

Account-unique name of the assembled module.

contentstringrequired

Authored knowledge content of the assembled module.

depends_onstring[]required

Names of the direct module dependencies.

Flash usage

POST/v1/flashes/usage

Request body

sincecustomoptional

Inclusive start of the usage window.

untilcustomoptional

Inclusive end of the usage window.

sort"flashed" | "pulled" | "tokens"optional

Field by which to order module usage.

group_by"day" | "module_day"optional

Optional time grouping for usage.

Response

5 fields

total_flashesnumberrequired

Number of flashes in the usage window.

total_tokensnumberrequired

Total tokens served in the usage window.

modulesobject[]required

Usage totals for each module in the window.

modulestringrequired

Account-unique name of the module.

explicit_flashesnumberrequired

Number of times the module was an explicit flash target.

transitive_pullsnumberrequired

Number of times the module was pulled into another closure.

total_tokensnumberrequired

Tokens attributed to the module in the usage window.

last_flashed_atcustom | nullrequired

Last time the module was an explicit target, or null if it was not targeted.

per_dayobject[]optional

Daily usage buckets when time grouping is requested.

datestringrequired

UTC date of the usage bucket in YYYY-MM-DD format.

flashesnumberrequired

Number of explicit flashes on this date.

tokensnumberrequired

Total tokens served on this date.

pullsnumberrequired

Number of transitive module pulls on this date.

module_dailyobject[]optional

Per-module daily usage series when module-day grouping is requested.

modulestringrequired

Account-unique name of the module.

pointsobject[]required

Daily explicit-flash usage points.

datestringrequired

UTC date of the usage point in YYYY-MM-DD format.

flashesnumberrequired

Number of times the module was flashed on this date.

Issues

A unit of work in flight, owned by a module — the work supply chain over an account’s knowledge.

Create issue

POST/v1/issues

Request body

modulestringrequired

Name of the module that will own the issue.

titlestringrequired

Short title of the issue.

descriptionstringrequired

Premise and required outcome of the issue.

assigneestring | nulloptional

Account-user ID to assign, or null to leave the issue unassigned.

priority"low" | "medium" | "high" | "urgent" | nulloptional

Issue priority, or null if it is not triaged.

dependenciesstring[]optional

IDs of issues that must finish before this issue.

labelsstring[]optional

IDs of labels to attach to the issue.

Response

14 fields

idcustomrequired

Unique ID of the issue.

modulestringrequired

Name of the module that owns the issue.

titlestringrequired

Short title of the issue.

descriptionstringrequired

Premise and required outcome of the issue.

status"open" | "in_progress" | "done" | "canceled"required

Current lifecycle status of the issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Issue priority, or null if it is not triaged.

originatorstringrequired

Account-user ID of the user who created the issue.

assigneestring | nullrequired

Assigned account-user ID, or null if unassigned.

dependenciesstring[]required

IDs of issues that must finish before this issue.

labelsobject[]required

Labels attached to the issue.

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

schedulestring | nullrequired

ID of the schedule that created the issue, or null if none did.

scheduled_forcustom | nullrequired

Scheduled occurrence that created the issue, or null if it was not scheduled.

created_atcustomrequired

Date and time when the issue was created.

updated_atcustomrequired

Date and time when the issue was last updated.

List issues

GET/v1/issues

Query parameters

modulestringoptional

Module name by which to filter issues.

status"open" | "in_progress" | "done" | "canceled"optional

Lifecycle status by which to filter issues.

assigneestringoptional

Account-user ID by which to filter issues.

labelstringoptional

Label ID by which to filter issues.

qstringoptional

Text to find in issue titles, descriptions, or comments.

limitintegeroptional

Maximum number of issues to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return issues.

Response

2 fields

dataobject[]required

Issues in this page.

idcustomrequired

Unique ID of the issue.

modulestringrequired

Name of the module that owns the issue.

titlestringrequired

Short title of the issue.

descriptionstringrequired

Premise and required outcome of the issue.

status"open" | "in_progress" | "done" | "canceled"required

Current lifecycle status of the issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Issue priority, or null if it is not triaged.

originatorstringrequired

Account-user ID of the user who created the issue.

assigneestring | nullrequired

Assigned account-user ID, or null if unassigned.

dependenciesstring[]required

IDs of issues that must finish before this issue.

labelsobject[]required

Labels attached to the issue.

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

schedulestring | nullrequired

ID of the schedule that created the issue, or null if none did.

scheduled_forcustom | nullrequired

Scheduled occurrence that created the issue, or null if it was not scheduled.

created_atcustomrequired

Date and time when the issue was created.

updated_atcustomrequired

Date and time when the issue was last updated.

has_morebooleanrequired

Whether more issues are available.

Issue inbox

POST/v1/issues/inbox

Request body

limitintegeroptional

Maximum number of issues to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return issues.

Response

2 fields

dataobject[]required

Issues in this page.

idcustomrequired

Unique ID of the issue.

modulestringrequired

Name of the module that owns the issue.

titlestringrequired

Short title of the issue.

descriptionstringrequired

Premise and required outcome of the issue.

status"open" | "in_progress" | "done" | "canceled"required

Current lifecycle status of the issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Issue priority, or null if it is not triaged.

originatorstringrequired

Account-user ID of the user who created the issue.

assigneestring | nullrequired

Assigned account-user ID, or null if unassigned.

dependenciesstring[]required

IDs of issues that must finish before this issue.

labelsobject[]required

Labels attached to the issue.

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

schedulestring | nullrequired

ID of the schedule that created the issue, or null if none did.

scheduled_forcustom | nullrequired

Scheduled occurrence that created the issue, or null if it was not scheduled.

created_atcustomrequired

Date and time when the issue was created.

updated_atcustomrequired

Date and time when the issue was last updated.

has_morebooleanrequired

Whether more issues are available.

Get issue

GET/v1/issues/{id}

Path parameters

idcustomrequired

Unique ID of the issue.

Query parameters

No query parameters

Response

14 fields

idcustomrequired

Unique ID of the issue.

modulestringrequired

Name of the module that owns the issue.

titlestringrequired

Short title of the issue.

descriptionstringrequired

Premise and required outcome of the issue.

status"open" | "in_progress" | "done" | "canceled"required

Current lifecycle status of the issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Issue priority, or null if it is not triaged.

originatorstringrequired

Account-user ID of the user who created the issue.

assigneestring | nullrequired

Assigned account-user ID, or null if unassigned.

dependenciesstring[]required

IDs of issues that must finish before this issue.

labelsobject[]required

Labels attached to the issue.

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

schedulestring | nullrequired

ID of the schedule that created the issue, or null if none did.

scheduled_forcustom | nullrequired

Scheduled occurrence that created the issue, or null if it was not scheduled.

created_atcustomrequired

Date and time when the issue was created.

updated_atcustomrequired

Date and time when the issue was last updated.

Update issue

PATCH/v1/issues/{id}

Path parameters

idcustomrequired

Unique ID of the issue.

Request body

titlestringoptional

New short title of the issue.

descriptionstringoptional

New premise and required outcome of the issue.

status"open" | "in_progress" | "done" | "canceled"optional

New lifecycle status of the issue.

assigneestring | nulloptional

Account-user ID to assign, or null to unassign the issue.

priority"low" | "medium" | "high" | "urgent" | nulloptional

New issue priority, or null to clear the priority.

dependenciesstring[]optional

Complete new set of issue dependency IDs.

labelsstring[]optional

Complete new set of label IDs.

Response

14 fields

idcustomrequired

Unique ID of the issue.

modulestringrequired

Name of the module that owns the issue.

titlestringrequired

Short title of the issue.

descriptionstringrequired

Premise and required outcome of the issue.

status"open" | "in_progress" | "done" | "canceled"required

Current lifecycle status of the issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Issue priority, or null if it is not triaged.

originatorstringrequired

Account-user ID of the user who created the issue.

assigneestring | nullrequired

Assigned account-user ID, or null if unassigned.

dependenciesstring[]required

IDs of issues that must finish before this issue.

labelsobject[]required

Labels attached to the issue.

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

schedulestring | nullrequired

ID of the schedule that created the issue, or null if none did.

scheduled_forcustom | nullrequired

Scheduled occurrence that created the issue, or null if it was not scheduled.

created_atcustomrequired

Date and time when the issue was created.

updated_atcustomrequired

Date and time when the issue was last updated.

Delete issue

DELETE/v1/issues/{id}

Path parameters

idcustomrequired

Unique ID of the issue.

Query parameters

No query parameters

Response

No response body

Labels

An account-scoped classification that can be attached to Cortex issues.

Create label

POST/v1/labels

Request body

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nulloptional

Hex color of the label, or null to create it without a color.

Response

5 fields

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

created_atcustomrequired

Date and time when the label was created.

updated_atcustomrequired

Date and time when the label was last updated.

List labels

GET/v1/labels

Query parameters

namestringoptional

Exact label name by which to filter labels.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
qstringoptional

Text to find in label names.

limitintegeroptional

Maximum number of labels to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return labels.

Response

2 fields

dataobject[]required

Labels in this page.

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

created_atcustomrequired

Date and time when the label was created.

updated_atcustomrequired

Date and time when the label was last updated.

has_morebooleanrequired

Whether more labels are available.

Get label

GET/v1/labels/{id}

Path parameters

idcustomrequired

Unique ID of the label.

Query parameters

No query parameters

Response

5 fields

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

created_atcustomrequired

Date and time when the label was created.

updated_atcustomrequired

Date and time when the label was last updated.

Update label

PATCH/v1/labels/{id}

Path parameters

idcustomrequired

Unique ID of the label.

Request body

namestringoptional

New account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nulloptional

New hex color of the label, or null to clear the color.

Response

5 fields

idcustomrequired

Unique ID of the label.

namestringrequired

Account-unique name of the label.

min length: 1 · max length: 40 · pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
colorstring | nullrequired

Hex color of the label, or null if it has no color.

created_atcustomrequired

Date and time when the label was created.

updated_atcustomrequired

Date and time when the label was last updated.

Delete label

DELETE/v1/labels/{id}

Path parameters

idcustomrequired

Unique ID of the label.

Query parameters

No query parameters

Response

No response body

Issue schedules

A durable recurrence rule that materializes ordinary Cortex issues.

Create issue schedule

POST/v1/issue-schedules

Request body

modulestringrequired

Name of the module that will own generated issues.

titlestringrequired

Title to assign to each generated issue.

min length: 1
descriptionstringrequired

Premise to assign to each generated issue.

priority"low" | "medium" | "high" | "urgent" | nulloptional

Priority to assign to generated issues, or null to leave them untriaged.

assigneestring | nulloptional

Account-user ID to assign to generated issues, or null to leave them unassigned.

cronstringrequired

Five-field cron expression that defines the recurrence.

min length: 1
timezonestringoptional

IANA time zone in which to evaluate the cron expression.

default: "UTC" · min length: 1
overlap_policy"coalesce" | "allow"optional

Behavior when a previous issue from the schedule is still open.

default: "coalesce"
missed_run_policy"next_only" | "catch_up"optional

Behavior for occurrences missed while the schedule was inactive.

default: "next_only"

Response

15 fields

idcustomrequired

Unique ID of the issue schedule.

modulestringrequired

Name of the module that owns generated issues.

titlestringrequired

Title assigned to each generated issue.

descriptionstringrequired

Premise assigned to each generated issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Priority assigned to generated issues, or null if they are not triaged.

assigneestring | nullrequired

Account-user ID assigned to generated issues, or null if they are unassigned.

cronstringrequired

Five-field cron expression that defines the recurrence.

timezonestringrequired

IANA time zone in which to evaluate the cron expression.

overlap_policy"coalesce" | "allow"required

Behavior when a previous issue from the schedule is still open.

missed_run_policy"next_only" | "catch_up"required

Behavior for occurrences missed while the schedule was inactive.

enabledbooleanrequired

Whether the schedule can generate issues.

next_run_atcustomrequired

Date and time of the next scheduled occurrence.

created_bystringrequired

Account-user ID of the user who created the schedule.

created_atcustomrequired

Date and time when the schedule was created.

updated_atcustomrequired

Date and time when the schedule was last updated.

List issue schedules

GET/v1/issue-schedules

Query parameters

modulestringoptional

Module name by which to filter issue schedules.

enabledboolean | "true" | "false"optional

Whether to return enabled or disabled issue schedules.

limitintegeroptional

Maximum number of issue schedules to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return issue schedules.

Response

2 fields

dataobject[]required

Issue schedules in this page.

idcustomrequired

Unique ID of the issue schedule.

modulestringrequired

Name of the module that owns generated issues.

titlestringrequired

Title assigned to each generated issue.

descriptionstringrequired

Premise assigned to each generated issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Priority assigned to generated issues, or null if they are not triaged.

assigneestring | nullrequired

Account-user ID assigned to generated issues, or null if they are unassigned.

cronstringrequired

Five-field cron expression that defines the recurrence.

timezonestringrequired

IANA time zone in which to evaluate the cron expression.

overlap_policy"coalesce" | "allow"required

Behavior when a previous issue from the schedule is still open.

missed_run_policy"next_only" | "catch_up"required

Behavior for occurrences missed while the schedule was inactive.

enabledbooleanrequired

Whether the schedule can generate issues.

next_run_atcustomrequired

Date and time of the next scheduled occurrence.

created_bystringrequired

Account-user ID of the user who created the schedule.

created_atcustomrequired

Date and time when the schedule was created.

updated_atcustomrequired

Date and time when the schedule was last updated.

has_morebooleanrequired

Whether more issue schedules are available.

Get issue schedule

GET/v1/issue-schedules/{id}

Path parameters

idcustomrequired

Unique ID of the issue schedule.

Query parameters

No query parameters

Response

15 fields

idcustomrequired

Unique ID of the issue schedule.

modulestringrequired

Name of the module that owns generated issues.

titlestringrequired

Title assigned to each generated issue.

descriptionstringrequired

Premise assigned to each generated issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Priority assigned to generated issues, or null if they are not triaged.

assigneestring | nullrequired

Account-user ID assigned to generated issues, or null if they are unassigned.

cronstringrequired

Five-field cron expression that defines the recurrence.

timezonestringrequired

IANA time zone in which to evaluate the cron expression.

overlap_policy"coalesce" | "allow"required

Behavior when a previous issue from the schedule is still open.

missed_run_policy"next_only" | "catch_up"required

Behavior for occurrences missed while the schedule was inactive.

enabledbooleanrequired

Whether the schedule can generate issues.

next_run_atcustomrequired

Date and time of the next scheduled occurrence.

created_bystringrequired

Account-user ID of the user who created the schedule.

created_atcustomrequired

Date and time when the schedule was created.

updated_atcustomrequired

Date and time when the schedule was last updated.

Update issue schedule

PATCH/v1/issue-schedules/{id}

Path parameters

idcustomrequired

Unique ID of the issue schedule.

Request body

titlestringoptional

New title for generated issues.

min length: 1
descriptionstringoptional

New premise for generated issues.

priority"low" | "medium" | "high" | "urgent" | nulloptional

New priority for generated issues, or null to leave them untriaged.

assigneestring | nulloptional

New account-user ID for generated issues, or null to leave them unassigned.

cronstringoptional

New five-field cron expression.

min length: 1
timezonestringoptional

New IANA time zone.

min length: 1
overlap_policy"coalesce" | "allow"optional

New behavior when a previous issue from the schedule is still open.

missed_run_policy"next_only" | "catch_up"optional

New behavior for occurrences missed while the schedule was inactive.

enabledbooleanoptional

Whether the schedule can generate issues.

Response

15 fields

idcustomrequired

Unique ID of the issue schedule.

modulestringrequired

Name of the module that owns generated issues.

titlestringrequired

Title assigned to each generated issue.

descriptionstringrequired

Premise assigned to each generated issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Priority assigned to generated issues, or null if they are not triaged.

assigneestring | nullrequired

Account-user ID assigned to generated issues, or null if they are unassigned.

cronstringrequired

Five-field cron expression that defines the recurrence.

timezonestringrequired

IANA time zone in which to evaluate the cron expression.

overlap_policy"coalesce" | "allow"required

Behavior when a previous issue from the schedule is still open.

missed_run_policy"next_only" | "catch_up"required

Behavior for occurrences missed while the schedule was inactive.

enabledbooleanrequired

Whether the schedule can generate issues.

next_run_atcustomrequired

Date and time of the next scheduled occurrence.

created_bystringrequired

Account-user ID of the user who created the schedule.

created_atcustomrequired

Date and time when the schedule was created.

updated_atcustomrequired

Date and time when the schedule was last updated.

Delete issue schedule

DELETE/v1/issue-schedules/{id}

Path parameters

idcustomrequired

Unique ID of the issue schedule.

Query parameters

No query parameters

Response

No response body

Queue an immediate issue schedule run

POST/v1/issue-schedules/{id}/run

Path parameters

idcustomrequired

Unique ID of the issue schedule.

Request body

No request body

Response

15 fields

idcustomrequired

Unique ID of the issue schedule.

modulestringrequired

Name of the module that owns generated issues.

titlestringrequired

Title assigned to each generated issue.

descriptionstringrequired

Premise assigned to each generated issue.

priority"low" | "medium" | "high" | "urgent" | nullrequired

Priority assigned to generated issues, or null if they are not triaged.

assigneestring | nullrequired

Account-user ID assigned to generated issues, or null if they are unassigned.

cronstringrequired

Five-field cron expression that defines the recurrence.

timezonestringrequired

IANA time zone in which to evaluate the cron expression.

overlap_policy"coalesce" | "allow"required

Behavior when a previous issue from the schedule is still open.

missed_run_policy"next_only" | "catch_up"required

Behavior for occurrences missed while the schedule was inactive.

enabledbooleanrequired

Whether the schedule can generate issues.

next_run_atcustomrequired

Date and time of the next scheduled occurrence.

created_bystringrequired

Account-user ID of the user who created the schedule.

created_atcustomrequired

Date and time when the schedule was created.

updated_atcustomrequired

Date and time when the schedule was last updated.

Comments

An authored note on an issue — the issue's own progress narrative.

Create comment

POST/v1/comments

Request body

issuestringrequired

ID of the issue on which to comment.

bodystringrequired

Authored content of the comment.

attachmentsstring[]optional

IDs of completed issue attachments to place in the comment.

max items: 20

Response

6 fields

idcustomrequired

Unique ID of the comment.

issuecustomrequired

ID of the issue that contains the comment.

authorstringrequired

Account-user ID of the comment author.

bodystringrequired

Authored content of the comment.

created_atcustomrequired

Date and time when the comment was created.

updated_atcustomrequired

Date and time when the comment was last updated.

List comments

GET/v1/comments

Query parameters

issuestringrequired

ID of the issue whose comments to return.

limitintegeroptional

Maximum number of comments to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return comments.

Response

2 fields

dataobject[]required

Comments in this page.

idcustomrequired

Unique ID of the comment.

issuecustomrequired

ID of the issue that contains the comment.

authorstringrequired

Account-user ID of the comment author.

bodystringrequired

Authored content of the comment.

created_atcustomrequired

Date and time when the comment was created.

updated_atcustomrequired

Date and time when the comment was last updated.

has_morebooleanrequired

Whether more comments are available.

Get comment

GET/v1/comments/{id}

Path parameters

idcustomrequired

Unique ID of the comment.

Query parameters

No query parameters

Response

6 fields

idcustomrequired

Unique ID of the comment.

issuecustomrequired

ID of the issue that contains the comment.

authorstringrequired

Account-user ID of the comment author.

bodystringrequired

Authored content of the comment.

created_atcustomrequired

Date and time when the comment was created.

updated_atcustomrequired

Date and time when the comment was last updated.

Update comment

PATCH/v1/comments/{id}

Path parameters

idcustomrequired

Unique ID of the comment.

Request body

bodystringrequired

New authored content of the comment.

Response

6 fields

idcustomrequired

Unique ID of the comment.

issuecustomrequired

ID of the issue that contains the comment.

authorstringrequired

Account-user ID of the comment author.

bodystringrequired

Authored content of the comment.

created_atcustomrequired

Date and time when the comment was created.

updated_atcustomrequired

Date and time when the comment was last updated.

Delete comment

DELETE/v1/comments/{id}

Path parameters

idcustomrequired

Unique ID of the comment.

Query parameters

No query parameters

Response

No response body

Issue attachments

A private file owned by an issue and authorized through its module.

Prepare issue attachment upload

POST/v1/issue-attachments

Request body

issuestringrequired

ID of the issue that will own the attachment.

filenamestringrequired

Original name of the file.

min length: 1 · max length: 255
media_typestringrequired

MIME type of the file.

min length: 1 · max length: 255 · pattern: ^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$
byte_sizeintegerrequired

Size of the file in bytes. The maximum size is 25 MiB.

greater than: 0 · max: 26214400
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

pattern: ^[A-Za-z0-9+/]{43}=$

Response

2 fields

attachmentobjectrequired

Attachment that is ready for upload.

idcustomrequired

Unique ID of the attachment.

issuecustomrequired

ID of the issue that owns the attachment.

filenamestringrequired

Original name of the uploaded file.

media_typestringrequired

MIME type of the uploaded file.

byte_sizeintegerrequired

Size of the file in bytes.

min: 0 · max: 9007199254740991
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

state"pending" | "ready"required

Upload state of the attachment.

uploaded_bystringrequired

Account-user ID of the user who uploaded the file.

commentscustom[]required

IDs of the comments that contain the attachment.

uploaded_atcustom | nullrequired

Date and time when the upload completed, or null if it is incomplete.

deleted_atcustom | nullrequired

Date and time when the file was removed, or null if it is available.

created_atcustomrequired

Date and time when the attachment was created.

uploadobjectrequired

Signed upload request.

urlstringrequired

Signed URL that accepts the file upload.

format: uri
method"PUT"required

HTTP method to use for the upload.

headersobjectrequired

HTTP headers to include in the upload request.

expires_atcustomrequired

Date and time when the upload URL expires.

List issue attachments

GET/v1/issue-attachments

Query parameters

issuestringrequired

ID of the issue that owns the attachments.

limitintegeroptional

Maximum number of attachments to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return attachments.

Response

2 fields

dataobject[]required

Attachments in this page.

idcustomrequired

Unique ID of the attachment.

issuecustomrequired

ID of the issue that owns the attachment.

filenamestringrequired

Original name of the uploaded file.

media_typestringrequired

MIME type of the uploaded file.

byte_sizeintegerrequired

Size of the file in bytes.

min: 0 · max: 9007199254740991
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

state"pending" | "ready"required

Upload state of the attachment.

uploaded_bystringrequired

Account-user ID of the user who uploaded the file.

commentscustom[]required

IDs of the comments that contain the attachment.

uploaded_atcustom | nullrequired

Date and time when the upload completed, or null if it is incomplete.

deleted_atcustom | nullrequired

Date and time when the file was removed, or null if it is available.

created_atcustomrequired

Date and time when the attachment was created.

has_morebooleanrequired

Whether more attachments are available.

Get issue attachment

GET/v1/issue-attachments/{id}

Path parameters

idcustomrequired

Unique ID of the attachment.

Query parameters

No query parameters

Response

12 fields

idcustomrequired

Unique ID of the attachment.

issuecustomrequired

ID of the issue that owns the attachment.

filenamestringrequired

Original name of the uploaded file.

media_typestringrequired

MIME type of the uploaded file.

byte_sizeintegerrequired

Size of the file in bytes.

min: 0 · max: 9007199254740991
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

state"pending" | "ready"required

Upload state of the attachment.

uploaded_bystringrequired

Account-user ID of the user who uploaded the file.

commentscustom[]required

IDs of the comments that contain the attachment.

uploaded_atcustom | nullrequired

Date and time when the upload completed, or null if it is incomplete.

deleted_atcustom | nullrequired

Date and time when the file was removed, or null if it is available.

created_atcustomrequired

Date and time when the attachment was created.

Complete issue attachment upload

POST/v1/issue-attachments/{id}/complete

Path parameters

idcustomrequired

Unique ID of the attachment.

Request body

No request body

Response

12 fields

idcustomrequired

Unique ID of the attachment.

issuecustomrequired

ID of the issue that owns the attachment.

filenamestringrequired

Original name of the uploaded file.

media_typestringrequired

MIME type of the uploaded file.

byte_sizeintegerrequired

Size of the file in bytes.

min: 0 · max: 9007199254740991
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

state"pending" | "ready"required

Upload state of the attachment.

uploaded_bystringrequired

Account-user ID of the user who uploaded the file.

commentscustom[]required

IDs of the comments that contain the attachment.

uploaded_atcustom | nullrequired

Date and time when the upload completed, or null if it is incomplete.

deleted_atcustom | nullrequired

Date and time when the file was removed, or null if it is available.

created_atcustomrequired

Date and time when the attachment was created.

Get issue attachment download

POST/v1/issue-attachments/{id}/download

Path parameters

idcustomrequired

Unique ID of the attachment.

Request body

No request body

Response

2 fields

urlstringrequired

Signed URL from which to download the file.

format: uri
expires_atcustomrequired

Date and time when the download URL expires.

Remove issue attachment

DELETE/v1/issue-attachments/{id}

Path parameters

idcustomrequired

Unique ID of the attachment.

Query parameters

No query parameters

Response

No response body

Comment attachments

A placement of an issue-owned attachment in an authored issue comment.

Place attachment in comment

POST/v1/comment-attachments

Request body

commentstringrequired

ID of the comment in which to place the attachment.

attachmentstringrequired

ID of the attachment to place in the comment.

positionintegeroptional

Zero-based display position of the attachment in the comment.

min: 0 · max: 9007199254740991

Response

6 fields

idcustomrequired

Unique ID of the placement.

issuecustomrequired

ID of the issue that owns the attachment.

commentcustomrequired

ID of the comment that contains the attachment.

attachmentobjectrequired

Attachment placed in the comment.

idcustomrequired

Unique ID of the attachment.

issuecustomrequired

ID of the issue that owns the attachment.

filenamestringrequired

Original name of the uploaded file.

media_typestringrequired

MIME type of the uploaded file.

byte_sizeintegerrequired

Size of the file in bytes.

min: 0 · max: 9007199254740991
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

state"pending" | "ready"required

Upload state of the attachment.

uploaded_bystringrequired

Account-user ID of the user who uploaded the file.

commentscustom[]required

IDs of the comments that contain the attachment.

uploaded_atcustom | nullrequired

Date and time when the upload completed, or null if it is incomplete.

deleted_atcustom | nullrequired

Date and time when the file was removed, or null if it is available.

created_atcustomrequired

Date and time when the attachment was created.

positionintegerrequired

Zero-based display position of the attachment in the comment.

min: 0 · max: 9007199254740991
created_atcustomrequired

Date and time when the placement was created.

List comment attachments

GET/v1/comment-attachments

Query parameters

commentstringoptional

ID of the comment by which to filter placements.

issuestringoptional

ID of the issue by which to filter placements.

Response

2 fields

dataobject[]required

Attachment placements in this page.

idcustomrequired

Unique ID of the placement.

issuecustomrequired

ID of the issue that owns the attachment.

commentcustomrequired

ID of the comment that contains the attachment.

attachmentobjectrequired

Attachment placed in the comment.

idcustomrequired

Unique ID of the attachment.

issuecustomrequired

ID of the issue that owns the attachment.

filenamestringrequired

Original name of the uploaded file.

media_typestringrequired

MIME type of the uploaded file.

byte_sizeintegerrequired

Size of the file in bytes.

min: 0 · max: 9007199254740991
checksum_sha256stringrequired

Base64-encoded SHA-256 checksum of the file.

state"pending" | "ready"required

Upload state of the attachment.

uploaded_bystringrequired

Account-user ID of the user who uploaded the file.

commentscustom[]required

IDs of the comments that contain the attachment.

uploaded_atcustom | nullrequired

Date and time when the upload completed, or null if it is incomplete.

deleted_atcustom | nullrequired

Date and time when the file was removed, or null if it is available.

created_atcustomrequired

Date and time when the attachment was created.

positionintegerrequired

Zero-based display position of the attachment in the comment.

min: 0 · max: 9007199254740991
created_atcustomrequired

Date and time when the placement was created.

has_morefalserequired

Whether more attachment placements are available.

Remove attachment from comment

DELETE/v1/comment-attachments/{id}

Path parameters

idcustomrequired

Unique ID of the placement.

Query parameters

No query parameters

Response

No response body

Issue events

An immutable record of a state change to an issue — its timeline.

List issue events

GET/v1/issue-events

Query parameters

issuestringrequired

ID of the issue whose events to return.

limitintegeroptional

Maximum number of issue events to return.

min: 1 · max: 100
afterstringoptional

Cursor after which to return issue events.

Response

2 fields

dataobject[]required

Issue events in this page.

idcustomrequired

Unique ID of the issue event.

issuecustomrequired

ID of the issue that contains the event.

actorstringrequired

Account-user ID that caused the state change.

type"created" | "status_changed" | "assigned" | "prioritized" | "retitled" | "redescribed" | "dependencies_changed" | "labels_changed"required

Type of state change recorded by the event.

dataobjectrequired

State-change details for the event.

created_atcustomrequired

Date and time when the state change occurred.

has_morebooleanrequired

Whether more issue events are available.

Get issue event

GET/v1/issue-events/{id}

Path parameters

idcustomrequired

Unique ID of the issue event.

Query parameters

No query parameters

Response

6 fields

idcustomrequired

Unique ID of the issue event.

issuecustomrequired

ID of the issue that contains the event.

actorstringrequired

Account-user ID that caused the state change.

type"created" | "status_changed" | "assigned" | "prioritized" | "retitled" | "redescribed" | "dependencies_changed" | "labels_changed"required

Type of state change recorded by the event.

dataobjectrequired

State-change details for the event.

created_atcustomrequired

Date and time when the state change occurred.