Pipelines

Pipelines model your sales (or other) workflow. Each pipeline has an ordered list of stages, and each stage holds cards — usually one per deal or opportunity. Pipelines and stages are read-only via the API; cards support full CRUD.

Resources

The top-level container, owned by an agent

Stages

Ordered columns within a pipeline

Cards

Individual deals living in a stage

The Pipeline object

string

workspace_id

string

bot_id

string

name

string

is_default

boolean

is_private

boolean

created_at

string

ISO 8601 timestamp.

updated_at

string

ISO 8601 timestamp.

List pipelines

method

GET

GET /api/v1/pipelines

Query parameters

Param	Type	Description
`bot_id`	string	Restrict to pipelines owned by a specific agent
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/pipelines?bot_id=b_01HDEF" \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "p_01HPLA...",
      "workspace_id": "w_01HXXX...",
      "bot_id": "b_01HDEF...",
      "name": "Sales Pipeline",
      "is_default": true,
      "is_private": false,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-04-01T08:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}

The Stage object

string

bot_id

string

pipeline_id

string

name

string

color

string

Hex color (e.g. "#0586ff").

order_index

integer

0-indexed position within the pipeline.

created_at

string

updated_at

string

List pipeline stages

method

GET

GET /api/v1/pipelines/{id}/stages

Returns every stage in the pipeline, sorted by order_index. Not paginated — the response shape is { "data": [...] } with no pagination object.

Example

curl https://clarky.ai/api/v1/pipelines/p_01HPLA/stages \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "ps_01HSTA...",
      "bot_id": "b_01HDEF...",
      "pipeline_id": "p_01HPLA...",
      "name": "Lead",
      "color": "#94a3b8",
      "order_index": 0,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "ps_01HSTB...",
      "bot_id": "b_01HDEF...",
      "pipeline_id": "p_01HPLA...",
      "name": "Qualified",
      "color": "#3b82f6",
      "order_index": 1,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "id": "ps_01HSTC...",
      "bot_id": "b_01HDEF...",
      "pipeline_id": "p_01HPLA...",
      "name": "Closed Won",
      "color": "#22c55e",
      "order_index": 2,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

The Pipeline Card object

string

pipeline_stage_id

string

The stage the card is currently in.

contact_id

string | null

The contact associated with this card, if any.

title

string

description

string | null

List pipeline cards

method

GET

GET /api/v1/pipeline-cards

Query parameters

Param	Type	Description
`pipeline_id`	string	Restrict to cards in a specific pipeline
`pipeline_stage_id`	string	Restrict to cards in a specific stage
`bot_id`	string	Restrict to cards owned by a specific agent
`contact_id`	string	Restrict to cards linked to a specific contact
`include_archived`	boolean	Include archived cards (default `false`)
`page`	integer	See Pagination
`page_size`	integer	See Pagination

Example

curl "https://clarky.ai/api/v1/pipeline-cards?pipeline_stage_id=ps_01HSTA" \
  -H "Authorization: Bearer ck_live_example"

{
  "data": [
    {
      "id": "pc_01HCRD...",
      "pipeline_stage_id": "ps_01HSTA...",
      "contact_id": "c_01HXYZ...",
      "title": "Acme Corp – renewal",
      "description": "Renewal due in Q2",
      "tags": ["renewal"],
      "order_index": 0,
      "archived_at": null,
      "created_at": "2026-04-10T09:00:00.000Z",
      "updated_at": "2026-04-29T15:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 1, "total_pages": 1 }
}

Get a pipeline card

method

GET

GET /api/v1/pipeline-cards/{id}

Example

curl https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example"

{
  "data": {
    "id": "pc_01HCRD...",
    "pipeline_stage_id": "ps_01HSTA...",
    "contact_id": "c_01HXYZ...",
    "title": "Acme Corp – renewal",
    "description": "Renewal due in Q2",
    "tags": ["renewal"],
    "order_index": 0,
    "archived_at": null,
    "created_at": "2026-04-10T09:00:00.000Z",
    "updated_at": "2026-04-29T15:00:00.000Z"
  }
}

Create a pipeline card

method

POST

POST /api/v1/pipeline-cards

Requires a key with the write scope.

Body fields

Field	Type	Required	Description
`pipeline_stage_id`	string	Yes	The stage to drop the card into
`title`	string	Yes
`contact_id`	string	No	Link to a contact
`description`	string	No
`tags`	string[]	No
`order_index`	integer	No	Defaults to the end of the stage

Example

curl https://clarky.ai/api/v1/pipeline-cards \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_stage_id": "ps_01HSTA",
    "title": "Acme Corp – renewal",
    "contact_id": "c_01HXYZ",
    "tags": ["renewal"]
  }'

{
  "data": {
    "id": "pc_01HCRD...",
    "pipeline_stage_id": "ps_01HSTA...",
    "contact_id": "c_01HXYZ...",
    "title": "Acme Corp – renewal",
    "tags": ["renewal"],
    "order_index": 3,
    "archived_at": null,
    "created_at": "2026-04-29T19:10:00.000Z",
    "updated_at": "2026-04-29T19:10:00.000Z"
  }
}

Update a pipeline card

method

PATCH

PATCH /api/v1/pipeline-cards/{id}

Update any combination of fields. Setting pipeline_stage_id to a new stage moves the card. Setting archived_at to an ISO 8601 timestamp archives the card; setting it to null un-archives it.

Body fields

Field	Type	Description
`pipeline_stage_id`	string	Move the card to a different stage
`contact_id`	string \| null	Link or unlink a contact
`title`	string
`description`	string
`tags`	string[]
`order_index`	integer	Reorder within the stage
`archived_at`	string \| null	ISO 8601 timestamp, or `null` to un-archive

Example: move a card to a new stage

curl -X PATCH https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_stage_id": "ps_01HSTC", "order_index": 0 }'

{
  "data": {
    "id": "pc_01HCRD...",
    "pipeline_stage_id": "ps_01HSTC...",
    "order_index": 0,
    "updated_at": "2026-04-29T19:15:00.000Z"
  }
}

Delete a pipeline card

method

DELETE

DELETE /api/v1/pipeline-cards/{id}

Returns 204 No Content. To preserve a card while removing it from active views, set archived_at via Update instead of deleting.

curl -X DELETE https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example"

​Resources

Pipelines

Stages

Cards

​The Pipeline object

​List pipelines

​Query parameters

​Example

​The Stage object

​List pipeline stages

​Example

​The Pipeline Card object

​List pipeline cards

​Query parameters

​Example

​Get a pipeline card

​Example

​Create a pipeline card

​Body fields

​Example

​Update a pipeline card

​Body fields

​Example: move a card to a new stage

​Delete a pipeline card

Resources

The Pipeline object

List pipelines

Query parameters

Example

The Stage object

List pipeline stages

Example

The Pipeline Card object

List pipeline cards

Query parameters

Example

Get a pipeline card

Example

Create a pipeline card

Body fields

Example

Update a pipeline card

Body fields

Example: move a card to a new stage

Delete a pipeline card