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
Pipelines The top-level container, owned by an agent
Stages Ordered columns within a pipeline
Cards Individual deals living in a stage
The Pipeline object List pipelines Query parameters Param Type Description bot_idstring Restrict to pipelines owned by a specific agent pageinteger See Pagination page_sizeinteger 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 Hex color (e.g. "#0586ff").
0-indexed position within the pipeline.
List pipeline stages 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 The stage the card is currently in.
The contact associated with this card, if any.
Position within the stage. Lower values sort first.
ISO 8601 timestamp the card was archived. null if active.
List pipeline cards GET /api/v1/pipeline-cards
Query parameters Param Type Description pipeline_idstring Restrict to cards in a specific pipeline pipeline_stage_idstring Restrict to cards in a specific stage bot_idstring Restrict to cards owned by a specific agent contact_idstring Restrict to cards linked to a specific contact include_archivedboolean Include archived cards (default false) pageinteger See Pagination page_sizeinteger 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 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 POST /api/v1/pipeline-cards
Requires a key with the write scope.
Body fields Field Type Required Description pipeline_stage_idstring Yes The stage to drop the card into titlestring Yes contact_idstring No Link to a contact descriptionstring No tagsstring[] No order_indexinteger 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 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_idstring Move the card to a different stage contact_idstring | null Link or unlink a contact titlestring descriptionstring tagsstring[] order_indexinteger Reorder within the stage archived_atstring | 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 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"
