> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarky.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipelines

> Read pipelines and stages, manage pipeline cards

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

<CardGroup cols={3}>
  <Card title="Pipelines" icon="diagram-project" href="#list-pipelines">
    The top-level container, owned by an agent
  </Card>

  <Card title="Stages" icon="bars-staggered" href="#list-pipeline-stages">
    Ordered columns within a pipeline
  </Card>

  <Card title="Cards" icon="rectangle-list" href="#list-pipeline-cards">
    Individual deals living in a stage
  </Card>
</CardGroup>

***

## The Pipeline object

<ResponseField name="id" type="string" />

<ResponseField name="workspace_id" type="string" />

<ResponseField name="bot_id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="is_default" type="boolean" />

<ResponseField name="is_private" type="boolean" />

<ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp.</ResponseField>

## List pipelines

<ParamField path="method" type="GET">
  `GET /api/v1/pipelines`
</ParamField>

### Query parameters

| Param       | Type    | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `bot_id`    | string  | Restrict to pipelines owned by a specific agent |
| `page`      | integer | See [Pagination](/api-reference/pagination)     |
| `page_size` | integer | See [Pagination](/api-reference/pagination)     |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/pipelines?bot_id=b_01HDEF" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "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

<ResponseField name="id" type="string" />

<ResponseField name="bot_id" type="string" />

<ResponseField name="pipeline_id" type="string" />

<ResponseField name="name" type="string" />

<ResponseField name="color" type="string">Hex color (e.g. `"#0586ff"`).</ResponseField>
<ResponseField name="order_index" type="integer">0-indexed position within the pipeline.</ResponseField>

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

## List pipeline stages

<ParamField path="method" type="GET">
  `GET /api/v1/pipelines/{id}/stages`
</ParamField>

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

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/pipelines/p_01HPLA/stages \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "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

<ResponseField name="id" type="string" />

<ResponseField name="pipeline_stage_id" type="string">The stage the card is currently in.</ResponseField>
<ResponseField name="contact_id" type="string | null">The contact associated with this card, if any.</ResponseField>

<ResponseField name="title" type="string" />

<ResponseField name="description" type="string | null" />

<ResponseField name="tags" type="string[]" />

<ResponseField name="order_index" type="integer">Position within the stage. Lower values sort first.</ResponseField>
<ResponseField name="archived_at" type="string | null">ISO 8601 timestamp the card was archived. `null` if active.</ResponseField>

<ResponseField name="created_at" type="string" />

<ResponseField name="updated_at" type="string" />

## List pipeline cards

<ParamField path="method" type="GET">
  `GET /api/v1/pipeline-cards`
</ParamField>

### 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](/api-reference/pagination)    |
| `page_size`         | integer | See [Pagination](/api-reference/pagination)    |

### Example

```bash theme={null}
curl "https://clarky.ai/api/v1/pipeline-cards?pipeline_stage_id=ps_01HSTA" \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "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

<ParamField path="method" type="GET">
  `GET /api/v1/pipeline-cards/{id}`
</ParamField>

### Example

```bash theme={null}
curl https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example"
```

```json theme={null}
{
  "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

<ParamField path="method" type="POST">
  `POST /api/v1/pipeline-cards`
</ParamField>

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

```bash theme={null}
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"]
  }'
```

```json theme={null}
{
  "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

<ParamField path="method" type="PATCH">
  `PATCH /api/v1/pipeline-cards/{id}`
</ParamField>

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

```bash theme={null}
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 }'
```

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

***

## Delete a pipeline card

<ParamField path="method" type="DELETE">
  `DELETE /api/v1/pipeline-cards/{id}`
</ParamField>

Returns `204 No Content`. To preserve a card while removing it from active views, set `archived_at` via [Update](#update-a-pipeline-card) instead of deleting.

```bash theme={null}
curl -X DELETE https://clarky.ai/api/v1/pipeline-cards/pc_01HCRD \
  -H "Authorization: Bearer ck_live_example"
```