Automation

Reusable AI you compose and ship: agents, workflows, their triggers and runs, and the skills the classifier can invoke as acts.

Common responses

These responses apply across endpoints in this section unless an endpoint documents an additional response.

Status	Meaning	Body
`200`	Request succeeded.	Endpoint response object.
`201`	Resource created.	Created resource object.
`400`	Invalid request.	Error envelope.
`401`	Missing or invalid bearer token.	Error envelope.
`404`	Resource not found or not visible to the current organization.	Error envelope.

Agents

List agents

List agents in the calling organization. Default response is active agents only; pass `isArchived=true` to see only archived ones.

GET/v1/agents

Query parameters

Name	Type	Required	Description
`isArchived`	`boolean`	Optional	Tri-state filter on archive status. `true` returns only archived rows; `false` returns only active; omit for the default (active only).

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/agents?is_archived=false" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "9f7c9d3a-1234-5678-9abc-def012345678",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "name": "Sales assistant",
      "description": "Handles inbound sales questions and routes to CRM.",
      "system_prompt": "You are a helpful sales assistant for Acme Corp.",
      "config": {},
      "visibility": "organization",
      "default_skill_slugs": [
        "web-search"
      ],
      "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "status": "active",
      "created_at": "2026-05-21T10:30:00.000Z",
      "updated_at": "2026-05-21T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create agent

Create a new agent. Returns 201 with the created agent object.

POST/v1/agents

Request body

Name	Type	Required	Description
`name`	`string`	Required	Display name. 1–255 characters.
`description`	`string`	Optional	Optional human description. Nullable.
`system_prompt`	`string`	Required	System prompt defining the agent's behavior. Non-empty.
`config`	`object`	Optional	Runtime overrides for this agent. Two keys are recognized: `model` (string) overrides the model family slug used for every run (e.g. `"claude-opus"`); `tools` (string[]) is an allowlist of tool names — omit the key to allow all tools. All other keys are stored and ignored.
`visibility`	`string`	Optional	`organization` (default — visible to every member) or `private` (visible only to the creator).
`default_skill_slugs`	`array`	Optional	Skills preloaded on every run. Each slug is resolved and merged into the run context before execution begins, the same way a user-selected skill would be.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant","system_prompt":"You are a helpful assistant."}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Sales assistant",
  "description": "Handles inbound sales questions and routes to CRM.",
  "system_prompt": "You are a helpful sales assistant for Acme Corp.",
  "config": {},
  "visibility": "organization",
  "default_skill_slugs": [
    "web-search"
  ],
  "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "status": "active",
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Get agent

Get an agent by ID. 404 if not found in the caller's organization.

GET/v1/agents/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

200 OKjson

{
  "id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Sales assistant",
  "description": "Handles inbound sales questions and routes to CRM.",
  "system_prompt": "You are a helpful sales assistant for Acme Corp.",
  "config": {},
  "visibility": "organization",
  "default_skill_slugs": [
    "web-search"
  ],
  "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "status": "active",
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Update agent

Update an agent. All fields optional — send only what you want to change.

PATCH/v1/agents/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`name`	`string`	Optional	Display name. 1–255 characters.
`description`	`string`	Optional	Optional human description. Nullable.
`system_prompt`	`string`	Optional	System prompt defining the agent's behavior. Non-empty.
`config`	`object`	Optional	Runtime overrides for this agent. Two keys are recognized: `model` (string) overrides the model family slug used for every run (e.g. `"claude-opus"`); `tools` (string[]) is an allowlist of tool names — omit the key to allow all tools. All other keys are stored and ignored.
`visibility`	`string`	Optional	`organization` (default — visible to every member) or `private` (visible only to the creator).
`default_skill_slugs`	`array`	Optional	Skills preloaded on every run. Each slug is resolved and merged into the run context before execution begins, the same way a user-selected skill would be.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant","system_prompt":"You are a helpful assistant."}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Sales assistant v2",
  "description": "Handles inbound sales questions and routes to CRM.",
  "system_prompt": "You are a helpful sales assistant for Acme Corp.",
  "config": {},
  "visibility": "organization",
  "default_skill_slugs": [
    "web-search"
  ],
  "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "status": "active",
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T11:00:00.000Z"
}

Archive agent

Archive an agent (soft delete — sets status to `archived`). The agent stops accepting new runs but historical runs remain queryable. Returns 204.

DELETE/v1/agents/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

204 No Contenttext

Agent triggers

List agent triggers

List every trigger configured on this agent.

GET/v1/agents/:id/triggers

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678/triggers \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "a3d8f1b2-5678-4321-bcde-012345678901",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "parent_type": "agent",
      "parent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
      "type": "cron",
      "schedule": "0 9 * * 1-5",
      "payload": {},
      "enabled": true,
      "next_fire_at": "2026-05-22T09:00:00.000Z",
      "target": {
        "type": "user",
        "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
      },
      "last_fired_at": null,
      "created_at": "2026-05-21T10:30:00.000Z",
      "updated_at": "2026-05-21T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create agent trigger

Create a trigger on an agent. Returns 201 with the trigger including the computed `nextFireAt`.

POST/v1/agents/:id/triggers

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`type`	`string`	Required	`cron`, `event`, or `webhook`.
`schedule`	`string`	Required	Schedule expression. For `cron`, a 5-field cron string (e.g. `0 * * * *`). Non-empty.
`payload`	`object`	Optional	Payload passed to the run when the trigger fires.
`enabled`	`boolean`	Optional	Whether the trigger is active. Defaults to true.
`target`	`object`	Optional	Where the trigger's output thread should be visible. Three shapes: `{ type: "user", user_id: "..." }` (personal thread for a single user), `{ type: "users", user_ids: ["..."] }` (one shared thread visible to all listed users), or `{ type: "project", project_id: "..." }` (shared thread in a project). When omitted on create, defaults to `{ type: "user", user_id: <caller> }`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678/triggers \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"type":"cron","schedule":"0 9 * * 1-5"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "id": "a3d8f1b2-5678-4321-bcde-012345678901",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "parent_type": "agent",
  "parent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "type": "cron",
  "schedule": "0 9 * * 1-5",
  "payload": {},
  "enabled": true,
  "next_fire_at": "2026-05-22T09:00:00.000Z",
  "target": {
    "type": "user",
    "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
  },
  "last_fired_at": null,
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Update agent trigger

Update a trigger. All fields optional.

PATCH/v1/agents/:id/triggers/:triggerId

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.
`triggerId`	`string`	Required	The triggerId value from the endpoint path.

Request body

Name	Type	Required	Description
`type`	`string`	Optional	`cron`, `event`, or `webhook`.
`schedule`	`string`	Optional	Schedule expression. For `cron`, a 5-field cron string (e.g. `0 * * * *`). Non-empty.
`payload`	`object`	Optional	Payload passed to the run when the trigger fires.
`enabled`	`boolean`	Optional	Whether the trigger is active. Defaults to true.
`target`	`object`	Optional	Where the trigger's output thread should be visible. Three shapes: `{ type: "user", user_id: "..." }` (personal thread for a single user), `{ type: "users", user_ids: ["..."] }` (one shared thread visible to all listed users), or `{ type: "project", project_id: "..." }` (shared thread in a project). When omitted on create, defaults to `{ type: "user", user_id: <caller> }`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678/triggers/a7b8c9d0-1234-5678-9abc-def012345678 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"type":"cron","schedule":"0 9 * * 1-5"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "a3d8f1b2-5678-4321-bcde-012345678901",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "parent_type": "agent",
  "parent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "type": "cron",
  "schedule": "0 9 * * 1-5",
  "payload": {},
  "enabled": false,
  "next_fire_at": "2026-05-22T09:00:00.000Z",
  "target": {
    "type": "user",
    "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
  },
  "last_fired_at": null,
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T11:00:00.000Z"
}

Delete agent trigger

Delete a trigger. Returns 204.

DELETE/v1/agents/:id/triggers/:triggerId

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.
`triggerId`	`string`	Required	The triggerId value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678/triggers/a7b8c9d0-1234-5678-9abc-def012345678 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

204 No Contenttext

Fire agent trigger now

Fire a trigger immediately, regardless of its schedule. Creates a new agent run as if the schedule had elapsed. Optionally pass `{ threadId }` to direct the run's output into an existing thread; when omitted, a new thread is created per the trigger's `target` configuration.

POST/v1/agents/:id/triggers/:triggerId/fire-now

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.
`triggerId`	`string`	Required	The triggerId value from the endpoint path.

Request body

Name	Type	Required	Description
`threadId`	`string`	Optional	UUID of an existing thread to direct the trigger output into. When omitted a new thread is created.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678/triggers/a7b8c9d0-1234-5678-9abc-def012345678/fire-now \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"thread_id":"16000e2f-6aab-45fc-937b-3684b8cd9722"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "a3d8f1b2-5678-4321-bcde-012345678901",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "parent_type": "agent",
  "parent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "type": "cron",
  "schedule": "0 9 * * 1-5",
  "payload": {},
  "enabled": true,
  "next_fire_at": "2026-05-21T10:30:00.000Z",
  "target": {
    "type": "user",
    "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
  },
  "last_fired_at": null,
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Agent runs

Start agent run (alias)

> **Alias endpoint.** Equivalent to `POST /threads/:id/runs` with the agent context set to this agent. Returns `{ message?, run, thread? }`. Use the canonical `POST /threads/:id/runs` for new code; this alias exists for backward compatibility. Start a new run for the specified agent. If `threadId` is omitted the server creates a fresh thread automatically and returns its ID alongside the run identifiers. Returns immediately with `status: queued`; poll `GET /threads/:id/runs/:runId` or stream `GET /threads/:id/runs/:runId/events` for progress.

POST/v1/agents/:id/run

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The agent ID to run.

Request body

Name	Type	Required	Description
`input`	`object`	Required	Free-form input object. Must include at least a `prompt` key with a non-empty string value.
`threadId`	`string`	Optional	UUID of an existing thread to attach this run to. When omitted a new thread is created and its ID is returned in the response.
`metadata`	`object`	Optional	Optional metadata to persist on the inserted user message. For example, the chat UI uses `planner_enabled: true` to request manual planning for this turn.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/agents/9f7c9d3a-1234-5678-9abc-def012345678/run \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"input":{"content":"Plan this dashboard"},"metadata":{"planner_enabled":true}}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "run_id": "b5f1aa84-e3c1-4c19-bb7d-9420aafada11",
  "thread_id": "16000e2f-6aab-45fc-937b-3684b8cd9722",
  "status": "queued",
  "conversation_run_id": "43f6a165-46a6-4e68-9de8-68201c7f4421"
}

Workflows

List workflows

List workflows in the calling organization. Default response is active workflows only; pass `isArchived=true` to see only archived ones.

GET/v1/workflows

Query parameters

Name	Type	Required	Description
`isArchived`	`boolean`	Optional	Tri-state filter on archive status. `true` returns only archived rows; `false` returns only active; omit for the default (active only).

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/workflows?is_archived=false" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "name": "Lead qualification",
      "description": "Qualify inbound leads and schedule demos.",
      "definition": {
        "steps": [
          {
            "id": "step-1",
            "name": "Score lead",
            "depends_on": [],
            "type": "model",
            "config": {
              "prompt": "Score this lead from 0-100 based on fit criteria."
            },
            "requires_confirmation": false,
            "confirmation_message": null
          },
          {
            "id": "step-2",
            "name": "Schedule demo",
            "depends_on": [
              "step-1"
            ],
            "type": "tool",
            "config": {
              "prompt": "Book a 30-minute discovery call."
            },
            "requires_confirmation": true,
            "confirmation_message": "Confirm scheduling a demo for this lead?"
          }
        ]
      },
      "config": {},
      "visibility": "organization",
      "discussion_agent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
      "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "status": "active",
      "created_at": "2026-05-21T10:30:00.000Z",
      "updated_at": "2026-05-21T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create workflow

Create a new workflow. The `definition.steps` array must form a valid DAG (no cycles) and every `depends_on` ID must reference an earlier step. Returns 201.

POST/v1/workflows

Request body

Name	Type	Required	Description
`name`	`string`	Required	Display name. 1–255 characters.
`description`	`string`	Optional	Optional description. Nullable.
`definition`	`object`	Optional	DAG of steps. Shape: `{ steps: Step[] }`. Each `Step` is `{ id, name, depends_on: string[], type: "model"\|"tool"\|"skill"\|"agent"\|"workflow", config: object, requires_confirmation?: boolean, confirmation_message?: string\|null }`. Steps may reference earlier `id`s via `depends_on` to form the execution order.
`config`	`object`	Optional	Free-form configuration object stored alongside the workflow.
`visibility`	`string`	Optional	`organization` (default) or `private`.
`discussion_agent_id`	`string`	Optional	UUID of an agent to act as the discussion host for threads started by this workflow's triggers. When set, replies to trigger-created threads are routed to this agent.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Lead qualification",
  "description": "Qualify inbound leads and schedule demos.",
  "definition": {
    "steps": [
      {
        "id": "step-1",
        "name": "Score lead",
        "depends_on": [],
        "type": "model",
        "config": {
          "prompt": "Score this lead from 0-100 based on fit criteria."
        },
        "requires_confirmation": false,
        "confirmation_message": null
      },
      {
        "id": "step-2",
        "name": "Schedule demo",
        "depends_on": [
          "step-1"
        ],
        "type": "tool",
        "config": {
          "prompt": "Book a 30-minute discovery call."
        },
        "requires_confirmation": true,
        "confirmation_message": "Confirm scheduling a demo for this lead?"
      }
    ]
  },
  "config": {},
  "visibility": "organization",
  "discussion_agent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "status": "active",
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Get workflow

Get a workflow by ID.

GET/v1/workflows/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

200 OKjson

{
  "id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Lead qualification",
  "description": "Qualify inbound leads and schedule demos.",
  "definition": {
    "steps": [
      {
        "id": "step-1",
        "name": "Score lead",
        "depends_on": [],
        "type": "model",
        "config": {
          "prompt": "Score this lead from 0-100 based on fit criteria."
        },
        "requires_confirmation": false,
        "confirmation_message": null
      },
      {
        "id": "step-2",
        "name": "Schedule demo",
        "depends_on": [
          "step-1"
        ],
        "type": "tool",
        "config": {
          "prompt": "Book a 30-minute discovery call."
        },
        "requires_confirmation": true,
        "confirmation_message": "Confirm scheduling a demo for this lead?"
      }
    ]
  },
  "config": {},
  "visibility": "organization",
  "discussion_agent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "status": "active",
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Update workflow

Update a workflow. All fields optional.

PATCH/v1/workflows/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`name`	`string`	Optional	Display name. 1–255 characters.
`description`	`string`	Optional	Optional description. Nullable.
`definition`	`object`	Optional	DAG of steps. Shape: `{ steps: Step[] }`. Each `Step` is `{ id, name, depends_on: string[], type: "model"\|"tool"\|"skill"\|"agent"\|"workflow", config: object, requires_confirmation?: boolean, confirmation_message?: string\|null }`. Steps may reference earlier `id`s via `depends_on` to form the execution order.
`config`	`object`	Optional	Free-form configuration object stored alongside the workflow.
`visibility`	`string`	Optional	`organization` (default) or `private`.
`discussion_agent_id`	`string`	Optional	UUID of an agent to act as the discussion host for threads started by this workflow's triggers. When set, replies to trigger-created threads are routed to this agent.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Lead qualification v2",
  "description": "Qualify inbound leads and schedule demos.",
  "definition": {
    "steps": [
      {
        "id": "step-1",
        "name": "Score lead",
        "depends_on": [],
        "type": "model",
        "config": {
          "prompt": "Score this lead from 0-100 based on fit criteria."
        },
        "requires_confirmation": false,
        "confirmation_message": null
      },
      {
        "id": "step-2",
        "name": "Schedule demo",
        "depends_on": [
          "step-1"
        ],
        "type": "tool",
        "config": {
          "prompt": "Book a 30-minute discovery call."
        },
        "requires_confirmation": true,
        "confirmation_message": "Confirm scheduling a demo for this lead?"
      }
    ]
  },
  "config": {},
  "visibility": "organization",
  "discussion_agent_id": "9f7c9d3a-1234-5678-9abc-def012345678",
  "created_by": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "status": "active",
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T11:00:00.000Z"
}

Refine workflow

Produce an LLM-assisted refinement of a workflow's definition based on a conversation history. The server replies with `{ text, proposedDefinition }`; the caller decides whether to apply `proposedDefinition` via `PATCH /workflows/:id`.

POST/v1/workflows/:id/refine

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`messages`	`array`	Required	Conversation history driving the refinement. Each entry: `{ role: "user"\|"assistant", content: string }`. The server uses these messages plus the current workflow definition to produce a refined definition via the LLM.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/refine \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"messages":[]}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "text": "I've added a step to send a follow-up email after the demo is scheduled.",
  "proposed_definition": {
    "steps": [
      {
        "id": "step-1",
        "name": "Score lead",
        "depends_on": [],
        "type": "model",
        "config": {
          "prompt": "Score this lead from 0-100."
        },
        "requires_confirmation": false,
        "confirmation_message": null
      },
      {
        "id": "step-2",
        "name": "Schedule demo",
        "depends_on": [
          "step-1"
        ],
        "type": "tool",
        "config": {
          "prompt": "Book a 30-minute discovery call."
        },
        "requires_confirmation": true,
        "confirmation_message": "Confirm scheduling a demo?"
      },
      {
        "id": "step-3",
        "name": "Send follow-up email",
        "depends_on": [
          "step-2"
        ],
        "type": "tool",
        "config": {
          "prompt": "Send a confirmation email to the lead."
        },
        "requires_confirmation": false,
        "confirmation_message": null
      }
    ]
  }
}

Archive workflow

Archive a workflow (soft delete — sets status to `archived`). Returns 204.

DELETE/v1/workflows/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

204 No Contenttext

Workflow triggers

List workflow triggers

List every trigger configured on this workflow.

GET/v1/workflows/:id/triggers

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/triggers \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "c9f3a7d1-1234-5678-abcd-ef0123456789",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "parent_type": "workflow",
      "parent_id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
      "type": "cron",
      "schedule": "0 9 * * 1-5",
      "payload": {},
      "enabled": true,
      "next_fire_at": "2026-05-22T09:00:00.000Z",
      "target": {
        "type": "user",
        "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
      },
      "last_fired_at": null,
      "created_at": "2026-05-21T10:30:00.000Z",
      "updated_at": "2026-05-21T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create workflow trigger

Create a trigger on a workflow. Returns 201 with the trigger including the computed `nextFireAt`.

POST/v1/workflows/:id/triggers

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`type`	`string`	Required	`cron`, `event`, or `webhook`.
`schedule`	`string`	Required	Schedule expression. For `cron`, a 5-field cron string (e.g. `0 * * * *`). Non-empty.
`payload`	`object`	Optional	Payload passed to the run when the trigger fires.
`enabled`	`boolean`	Optional	Whether the trigger is active. Defaults to true.
`target`	`object`	Optional	Where the trigger's output thread should be visible. Three shapes: `{ type: "user", user_id: "..." }` (personal thread for a single user), `{ type: "users", user_ids: ["..."] }` (one shared thread visible to all listed users), or `{ type: "project", project_id: "..." }` (shared thread in a project). When omitted on create, defaults to `{ type: "user", user_id: <caller> }`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/triggers \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"type":"cron","schedule":"0 9 * * 1-5"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "id": "c9f3a7d1-1234-5678-abcd-ef0123456789",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "parent_type": "workflow",
  "parent_id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
  "type": "cron",
  "schedule": "0 9 * * 1-5",
  "payload": {},
  "enabled": true,
  "next_fire_at": "2026-05-22T09:00:00.000Z",
  "target": {
    "type": "user",
    "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
  },
  "last_fired_at": null,
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Update workflow trigger

Update a workflow trigger. All fields optional.

PATCH/v1/workflows/:id/triggers/:triggerId

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.
`triggerId`	`string`	Required	The triggerId value from the endpoint path.

Request body

Name	Type	Required	Description
`type`	`string`	Optional	`cron`, `event`, or `webhook`.
`schedule`	`string`	Optional	Schedule expression. For `cron`, a 5-field cron string (e.g. `0 * * * *`). Non-empty.
`payload`	`object`	Optional	Payload passed to the run when the trigger fires.
`enabled`	`boolean`	Optional	Whether the trigger is active. Defaults to true.
`target`	`object`	Optional	Where the trigger's output thread should be visible. Three shapes: `{ type: "user", user_id: "..." }` (personal thread for a single user), `{ type: "users", user_ids: ["..."] }` (one shared thread visible to all listed users), or `{ type: "project", project_id: "..." }` (shared thread in a project). When omitted on create, defaults to `{ type: "user", user_id: <caller> }`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/triggers/a7b8c9d0-1234-5678-9abc-def012345678 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"type":"cron","schedule":"0 9 * * 1-5"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "c9f3a7d1-1234-5678-abcd-ef0123456789",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "parent_type": "workflow",
  "parent_id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
  "type": "cron",
  "schedule": "0 9 * * 1-5",
  "payload": {},
  "enabled": false,
  "next_fire_at": "2026-05-22T09:00:00.000Z",
  "target": {
    "type": "user",
    "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
  },
  "last_fired_at": null,
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T11:00:00.000Z"
}

Delete workflow trigger

Delete a workflow trigger. Returns 204.

DELETE/v1/workflows/:id/triggers/:triggerId

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.
`triggerId`	`string`	Required	The triggerId value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/triggers/a7b8c9d0-1234-5678-9abc-def012345678 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

204 No Contenttext

Fire workflow trigger now

Fire a workflow trigger immediately. Creates a new workflow run as if the schedule had elapsed. Optionally pass `{ threadId }` to direct the run's output into an existing thread; when omitted, a new thread is created per the trigger's `target` configuration.

POST/v1/workflows/:id/triggers/:triggerId/fire-now

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.
`triggerId`	`string`	Required	The triggerId value from the endpoint path.

Request body

Name	Type	Required	Description
`threadId`	`string`	Optional	UUID of an existing thread to direct the trigger output into. When omitted a new thread is created.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/triggers/a7b8c9d0-1234-5678-9abc-def012345678/fire-now \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"thread_id":"16000e2f-6aab-45fc-937b-3684b8cd9722"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "c9f3a7d1-1234-5678-abcd-ef0123456789",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "parent_type": "workflow",
  "parent_id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
  "type": "cron",
  "schedule": "0 9 * * 1-5",
  "payload": {},
  "enabled": true,
  "next_fire_at": "2026-05-21T10:30:00.000Z",
  "target": {
    "type": "user",
    "user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b"
  },
  "last_fired_at": null,
  "created_at": "2026-05-21T10:30:00.000Z",
  "updated_at": "2026-05-21T10:30:00.000Z"
}

Workflow runs

Start workflow run (alias)

> **Alias endpoint.** Equivalent to `POST /threads/:id/runs` with the workflow context set to this workflow. Returns `{ message, run, thread }`. Use the canonical `POST /threads/:id/runs` for new code; this alias exists for backward compatibility. Start a new run of the workflow. If `threadId` is omitted, the server creates a fresh thread and returns it alongside the run. Returns 201 immediately with `status: queued`.

POST/v1/workflows/:id/run

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`input`	`object`	Required	Payload passed to the orchestrator as the request input.
`threadId`	`string`	Optional	UUID of an existing thread to attach the run to. When omitted, a fresh thread is created and its ID is returned in the response.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/workflows/9f7c9d3a-1234-5678-9abc-def012345678/run \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"input":{}}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "message": {
    "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
    "thread_id": "16000e2f-6aab-45fc-937b-3684b8cd9722",
    "role": "user",
    "created_by_type": "user",
    "created_by_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "content": "Please qualify this lead.",
    "content_blocks": [
      {
        "type": "text",
        "text": "Please qualify this lead."
      }
    ],
    "sequence": 1,
    "created_at": "2026-05-21T10:30:00.000Z"
  },
  "run": {
    "id": "43f6a165-46a6-4e68-9de8-68201c7f4421",
    "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
    "thread_id": "16000e2f-6aab-45fc-937b-3684b8cd9722",
    "input_message_id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
    "output_message_id": null,
    "parent_run_id": null,
    "created_by_type": "user",
    "created_by_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
    "executed_by_type": "workflow",
    "executed_by_id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
    "status": "queued",
    "result": null,
    "error": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2026-05-21T10:30:00.000Z",
    "updated_at": "2026-05-21T10:30:00.000Z"
  },
  "thread": {
    "id": "16000e2f-6aab-45fc-937b-3684b8cd9722",
    "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
    "created_by_type": "workflow",
    "created_by_id": "b7e2c4f9-abcd-4567-8901-23456789abcd",
    "title": "Qualify Acme Corp lead",
    "project_id": null,
    "is_pinned": false,
    "created_at": "2026-05-21T10:30:00.000Z",
    "updated_at": "2026-05-21T10:30:00.000Z"
  }
}

Approvals

List pending approvals

List every pending graph approval across agents and workflows. Each item carries `{ threadId, runId, interruptId }` — use these with `POST /threads/:id/runs/:runId/approve` or `/reject`.

GET/v1/pending-actions

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/pending-actions \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "43f6a165-46a6-4e68-9de8-68201c7f4421:workflow:approve",
      "thread_id": "16000e2f-6aab-45fc-937b-3684b8cd9722",
      "run_id": "43f6a165-46a6-4e68-9de8-68201c7f4421",
      "interrupt_id": "workflow:approve",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "kind": "workflow",
      "type": "run_confirmation",
      "status": "pending",
      "title": "Sales assistant approval",
      "summary": "Confirm scheduling a demo for this lead?",
      "source_name": "Sales assistant",
      "created_at": "2026-05-21T10:30:00.000Z",
      "updated_at": "2026-05-21T10:30:00.000Z",
      "payload": {
        "interrupt_id": "workflow:approve",
        "step_id": "approve",
        "title": "Confirm scheduling a demo for this lead?"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Skills

List skills

List skills available to the calling organization — both built-in skills (provided by the platform) and org-defined skills created by the organization. Built-in skills are read-only and always present; org-defined skills can be created, updated, and archived. Filter by source with `?source=builtin` or `?source=org`. Tri-state `isArchived` filter (omit or `false` = active only; `true` = archived only) applies to org-defined skills only — built-ins are never archived.

GET/v1/skills

Query parameters

Name	Type	Required	Description
`source`	`string`	Optional	`builtin` to list only platform-provided skills; `org` to list only organization-defined skills. Omit to return both.
`isArchived`	`boolean`	Optional	Tri-state filter on archive status for org-defined skills. `true` returns only archived org skills; `false` or omit returns only active org skills.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/skills?source=org&is_archived=false" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "a92f3e6c-1d45-4b78-9c01-5e8a2b4d7f3c",
      "organization_id": null,
      "slug": "summarize_thread",
      "name": "Summarize thread",
      "description": "Built-in skill that produces an executive summary of the active thread.",
      "when_to_use": "When the user asks for a recap, summary, or TL;DR of the current conversation.",
      "instructions": "Read the thread transcript and produce a 5-sentence summary plus a bullet list of open follow-ups.",
      "manifest": {},
      "scripts": [],
      "version": 1,
      "is_archived": false,
      "created_by_user_id": null,
      "created_at": "2025-09-01T00:00:00.000Z",
      "updated_at": "2025-09-01T00:00:00.000Z"
    },
    {
      "id": "c5b1f9e2-3d8a-4f76-9b12-7c34e8a1d9f0",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "slug": "research_web",
      "name": "Research web",
      "description": "Search the public web and summarize sources for a given query.",
      "when_to_use": "Use when the user asks a question whose answer is likely on the public web and not in the org's private knowledge.",
      "instructions": "Search the web for the user's query. Cite each source. Summarize the top results in 3–5 bullet points.",
      "manifest": {
        "inputs": [
          "query"
        ],
        "outputs": [
          "summary",
          "citations"
        ]
      },
      "scripts": [],
      "version": 1,
      "is_archived": false,
      "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
      "created_at": "2026-05-20T10:30:00.000Z",
      "updated_at": "2026-05-20T10:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create skill

Create a new org-defined skill. Skills package reusable instructions that the classifier can select when decomposing a user message into acts. A skill's `slug` must be unique within the organization (case-insensitive). Built-in skill slugs are reserved and cannot be reused.

POST/v1/skills

Request body

Name	Type	Required	Description
`slug`	`string`	Required	URL-safe unique identifier within the organization. Used to reference the skill in agent `default_skill_slugs` and act DAGs. Example: `research_web`.
`name`	`string`	Required	Display name. 1–255 characters.
`description`	`string`	Optional	Optional description of what the skill does. Shown in the console and included in classification context.
`when_to_use`	`string`	Required	Natural-language guidance for the classifier on when to invoke this skill. Included verbatim in the classification prompt.
`instructions`	`string`	Required	System-prompt instructions injected when the skill executes. Describes how to perform the skill's work.
`manifest`	`object`	Optional	Optional structured metadata about the skill's inputs, outputs, and tool requirements. Free-form JSON.
`scripts`	`object`	Optional	Optional scripts the skill can invoke during execution. Free-form JSON keyed by script name.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/skills \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"slug":"research_web","name":"Sales assistant","when_to_use":"When the user asks a research question.","instructions":"Search and summarize."}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

201 Createdjson

{
  "id": "c5b1f9e2-3d8a-4f76-9b12-7c34e8a1d9f0",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "slug": "research_web",
  "name": "Research web",
  "description": "Search the public web and summarize sources for a given query.",
  "when_to_use": "Use when the user asks a question whose answer is likely on the public web and not in the org's private knowledge.",
  "instructions": "Search the web for the user's query. Cite each source. Summarize the top results in 3–5 bullet points.",
  "manifest": {
    "inputs": [
      "query"
    ],
    "outputs": [
      "summary",
      "citations"
    ]
  },
  "scripts": [],
  "version": 1,
  "is_archived": false,
  "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "created_at": "2026-05-20T10:30:00.000Z",
  "updated_at": "2026-05-20T10:30:00.000Z"
}

Get skill

Fetch the full definition of a skill by ID. Returns both built-in and org-defined skills visible to the calling organization.

GET/v1/skills/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/skills/9f7c9d3a-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

200 OKjson

{
  "id": "c5b1f9e2-3d8a-4f76-9b12-7c34e8a1d9f0",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "slug": "research_web",
  "name": "Research web",
  "description": "Search the public web and summarize sources for a given query.",
  "when_to_use": "Use when the user asks a question whose answer is likely on the public web and not in the org's private knowledge.",
  "instructions": "Search the web for the user's query. Cite each source. Summarize the top results in 3–5 bullet points.",
  "manifest": {
    "inputs": [
      "query"
    ],
    "outputs": [
      "summary",
      "citations"
    ]
  },
  "scripts": [],
  "version": 1,
  "is_archived": false,
  "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "created_at": "2026-05-20T10:30:00.000Z",
  "updated_at": "2026-05-20T10:30:00.000Z"
}

Update skill

Update an org-defined skill. All fields are optional — send only what you want to change. Returns 403 `builtin_skill_immutable` if the skill is a platform built-in; built-ins cannot be modified.

PATCH/v1/skills/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Request body

Name	Type	Required	Description
`name`	`string`	Optional	Display name. 1–255 characters.
`description`	`string`	Optional	Optional description. Pass null to clear.
`when_to_use`	`string`	Optional	Classification guidance.
`instructions`	`string`	Optional	Execution system-prompt instructions.
`manifest`	`object`	Optional	Structured metadata. Pass null to clear.
`scripts`	`object`	Optional	Executable scripts. Pass null to clear.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/skills/9f7c9d3a-1234-5678-9abc-def012345678 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Sales assistant","description":"Created via the docs example.","when_to_use":"When the user asks a research question.","instructions":"Search and summarize.","manifest":{},"scripts":{}}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`

200 OKjson

{
  "id": "c5b1f9e2-3d8a-4f76-9b12-7c34e8a1d9f0",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "slug": "research_web",
  "name": "Research web v2",
  "description": "Search the public web and summarize sources for a given query.",
  "when_to_use": "Use when the user asks a question whose answer is likely on the public web and not in the org's private knowledge.",
  "instructions": "Search the web for the user's query. Cite each source. Summarize the top results in 3–5 bullet points.",
  "manifest": {
    "inputs": [
      "query"
    ],
    "outputs": [
      "summary",
      "citations"
    ]
  },
  "scripts": [],
  "version": 1,
  "is_archived": false,
  "created_by_user_id": "0ce6409a-3bfa-4e2f-883a-5a696b451d8b",
  "created_at": "2026-05-20T10:30:00.000Z",
  "updated_at": "2026-05-21T11:00:00.000Z"
}

Archive skill

Soft-delete an org-defined skill by setting `isArchived = true`. Archived skills are excluded from classification and cannot be invoked in new runs, but existing run records that reference the skill are preserved. Returns 204. Returns 403 `builtin_skill_immutable` if the skill is a platform built-in.

DELETE/v1/skills/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/skills/9f7c9d3a-1234-5678-9abc-def012345678 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`

204 No Contenttext

(empty response body)