Pipelines API Documentation

The Pipelines API provides Kanban-style workflow management for orders, leads, support tickets, and custom workflows.

Base URL

https://api.talkingshops.com/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-tenant-api-key: your_api_key_here

API keys are tenant-specific and automatically provide access to the correct data for your business account.

Rate Limiting

The API implements rate limiting to prevent abuse. Each tenant is limited to requests per minute based on their subscription tier.

Endpoints Overview

Method	Endpoint	Description
`POST`	`/pipelines`	Create a new pipeline
`GET`	`/pipelines`	List pipelines
`GET`	`/pipelines/:pipelineId`	Get pipeline by ID
`PUT`	`/pipelines/:pipelineId`	Update pipeline
`PATCH`	`/pipelines/:pipelineId`	Partial update pipeline
`DELETE`	`/pipelines/:pipelineId`	Delete pipeline
`GET`	`/pipelines/:pipelineId/check-delete`	Check if pipeline can be deleted
`POST`	`/pipelines/seed`	Seed default pipelines
`GET`	`/pipelines/:pipelineId/entities`	Get entities in pipeline (Kanban view)
`GET`	`/pipelines/:pipelineId/stats`	Get pipeline statistics
`POST`	`/pipelines/:pipelineId/assign`	Assign entity to pipeline
`PUT`	`/pipelines/:pipelineId/entities/:entityId/stage`	Move entity to stage
`PUT`	`/pipelines/:pipelineId/entities/bulk-stage`	Bulk move entities
`PUT`	`/pipelines/:pipelineId/entities/bulk-assign`	Bulk assign entities

Pipeline Entity Types

Type	Description
`order`	Order fulfillment workflow
`lead`	Lead qualification pipeline
`support`	Customer support workflow
`custom`	Custom workflow

Stage Types

Type	Description
`default`	Initial/default stage for new entities
`success`	Terminal success stage
`failure`	Terminal failure stage
`neutral`	Neutral terminal stage

Create Pipeline

Create a new pipeline with stages.

Request

http

POST /v1/pipelines
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "name": "Order Fulfillment",
  "description": "Manage order fulfillment workflow",
  "entityType": "order",
  "stages": [
    { "name": "New", "slug": "new", "order": 0, "type": "default" },
    { "name": "Processing", "slug": "processing", "order": 1 },
    { "name": "Shipped", "slug": "shipped", "order": 2 },
    { "name": "Delivered", "slug": "delivered", "order": 3, "type": "success" }
  ],
  "settings": {
    "enableStageHistory": true,
    "enableOwnerAssignment": true,
    "enableBulkOperations": true
  }
}

Request Body

Field	Type	Required	Description
`name`	string	Yes	Pipeline name (max 200 chars)
`description`	string	No	Pipeline description (max 5000 chars)
`entityType`	string	Yes	Entity type (order, lead, support, custom)
`stages`	array	No	Pipeline stages (max 50 stages)
`settings`	object	No	Pipeline settings

Stage Object

Field	Type	Description
`name`	string	Stage name (max 100 chars)
`slug`	string	URL-safe identifier (max 50 chars)
`description`	string	Stage description
`color`	string	Stage color hex code
`order`	number	Stage order
`type`	string	Stage type (default, success, failure, neutral)

Response

json

{
  "success": true,
  "message": "Pipeline created successfully",
  "pipeline": {
    "_id": "507f1f77bcf86cd799439012",
    "name": "Order Fulfillment",
    "description": "Manage order fulfillment workflow",
    "entityType": "order",
    "stages": [
      { "name": "New", "slug": "new", "order": 0, "type": "default" },
      { "name": "Processing", "slug": "processing", "order": 1 },
      { "name": "Shipped", "slug": "shipped", "order": 2 },
      { "name": "Delivered", "slug": "delivered", "order": 3, "type": "success" }
    ],
    "settings": {
      "enableStageHistory": true,
      "enableOwnerAssignment": true,
      "enableBulkOperations": true
    },
    "isSystem": false,
    "created_at": "2026-04-10T12:00:00Z",
    "updated_at": "2026-04-10T12:00:00Z"
  }
}

Pipeline Object Fields

Field	Type	Description
`_id`	string	Unique pipeline identifier
`name`	string	Pipeline name
`description`	string	Pipeline description
`entityType`	string	Entity type (order, lead, support, custom)
`stages`	array	Array of stage objects
`settings`	object	Pipeline settings (autoAssign, history, assignments, bulk)
`isSystem`	boolean	Whether this is a system pipeline
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

List Pipelines

Retrieve all pipelines for the tenant.

Request

http

GET /v1/pipelines?entityType=order&includeSystem=false
x-tenant-api-key: your_api_key_here

Query Parameters

Parameter	Type	Description
`entityType`	string	Filter by entity type
`includeSystem`	boolean	Include system pipelines (default: true)

Response

json

{
  "pipelines": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "name": "Order Fulfillment",
      "entityType": "order",
      "stages": [...],
      "isSystem": true
    }
  ]
}

Get Pipeline by ID

Retrieve a single pipeline by its ID.

Request

http

GET /v1/pipelines/:pipelineId
x-tenant-api-key: your_api_key_here

Update Pipeline

Update an existing pipeline.

Request

http

PUT /v1/pipelines/:pipelineId
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "name": "Updated Pipeline Name",
  "description": "Updated description",
  "stages": [
    { "name": "New", "slug": "new", "order": 0, "type": "default" },
    { "name": "In Progress", "slug": "in_progress", "order": 1 }
  ]
}

Response

json

{
  "success": true,
  "message": "Pipeline updated successfully"
}

Delete Pipeline

Delete a pipeline. System pipelines cannot be deleted.

Request

http

DELETE /v1/pipelines/:pipelineId
x-tenant-api-key: your_api_key_here

Query Parameters

Parameter	Type	Description
`force`	boolean	Force delete even if entities exist

Response

json

{
  "success": true,
  "message": "Pipeline deleted successfully"
}

Error Responses

404 Not Found - Pipeline does not exist
400 Bad Request - System pipeline cannot be deleted
409 Conflict - Pipeline has entities (use force=true)

Check Delete Pipeline

Check if a pipeline can be safely deleted without affecting entities.

Request

http

GET /v1/pipelines/:pipelineId/check-delete
x-tenant-api-key: your_api_key_here

Response

json

{
  "canDelete": false,
  "isSystem": false,
  "entityCount": 5,
  "entityType": "order",
  "message": "5 entities are using this pipeline"
}

Seed Default Pipelines

Create default pipelines for a tenant.

Request

http

POST /v1/pipelines/seed
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "force": false
}

Request Body

Field	Type	Description
`force`	boolean	Update existing pipelines (default: false)

Response

json

{
  "success": true,
  "message": "Seeded 3 default pipelines",
  "created": 3
}

Get Pipeline Entities (Kanban View)

Retrieve all entities in a pipeline grouped by stage.

Request

http

GET /v1/pipelines/:pipelineId/entities?stage=new&ownerId=agent_001&limit=50
x-tenant-api-key: your_api_key_here

Query Parameters

Parameter	Type	Default	Description
`ownerId`	string	-	Filter by owner
`stage`	string	-	Filter by stage slug
`search`	string	-	Search in title/name
`page`	number	1	Page number
`limit`	number	50	Items per page (max 100)

Response

json

{
  "stages": {
    "new": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "title": "Order #123",
        "entityType": "order",
        "status": "confirmed",
        "ownerId": "agent_001",
        "ownerName": "John Doe",
        "stageHistory": [
          {
            "stage": "new",
            "enteredAt": "2026-04-10T10:00:00Z",
            "movedBy": "user",
            "movedByUserId": "agent_001",
            "movedByUserName": "John Doe"
          }
        ],
        "created_at": "2026-04-10T10:00:00Z",
        "updated_at": "2026-04-10T10:00:00Z"
      }
    ],
    "processing": [...],
    "shipped": [...],
    "delivered": [...]
  },
  "total": 150,
  "stageStats": {
    "new": 45,
    "processing": 30,
    "shipped": 50,
    "delivered": 25
  }
}

Pipeline Entity Object Fields

Field	Type	Description
`_id`	string	Unique entity identifier
`title`	string	Entity title
`entityType`	string	Entity type (order, lead, support, custom)
`status`	string	Current status
`ownerId`	string	Assigned owner ID
`ownerName`	string	Assigned owner name
`stageHistory`	array	Array of stage change history entries
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Stage History Entry Fields

Field	Type	Description
`stage`	string	Stage slug
`enteredAt`	string	When entity entered this stage
`movedBy`	string	Who moved (user, system, manual)
`movedByUserId`	string	User ID who moved
`movedByUserName`	string	User name who moved
`note`	string	Optional note
`duration`	number	Time spent in previous stage (ms)


---

## Assign Entity to Pipeline

Assign an entity to a pipeline.

### Request

```http
POST /v1/pipelines/:pipelineId/assign
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "entityId": "507f1f77bcf86cd799439011",
  "ownerId": "agent_001",
  "ownerName": "John Doe",
  "initialStage": "new"
}

Request Body

Field	Type	Required	Description
`entityId`	string	Yes	Entity ID to assign
`ownerId`	string	No	Owner ID
`ownerName`	string	No	Owner name
`initialStage`	string	No	Initial stage slug

Response

json

{
  "success": true,
  "message": "Entity assigned to pipeline successfully"
}

Move Entity to Stage

Move an entity to a different stage in the pipeline.

Request

http

PUT /v1/pipelines/:pipelineId/entities/:entityId/stage
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "stage": "processing",
  "note": "Order confirmed with customer",
  "movedByUserId": "agent_001",
  "movedByUserName": "John Doe"
}

Request Body

Field	Type	Required	Description
`stage`	string	Yes	Target stage slug
`note`	string	No	Note for the stage change (max 1000 chars)
`movedByUserId`	string	No	User ID who is moving the entity
`movedByUserName`	string	No	User name who is moving the entity

Response

json

{
  "success": true,
  "message": "Entity moved to \"processing\" successfully"
}

Bulk Move Entities

Move multiple entities to a stage in a single operation.

Request

http

PUT /v1/pipelines/:pipelineId/entities/bulk-stage
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "entityIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012",
    "507f1f77bcf86cd799439013"
  ],
  "stage": "processing",
  "note": "Batch processing",
  "movedByUserId": "agent_001"
}

Request Body

Field	Type	Required	Description
`entityIds`	array	Yes	Array of entity IDs (max 50)
`stage`	string	Yes	Target stage slug
`note`	string	No	Note for the stage change
`movedByUserId`	string	No	User ID who is moving the entities
`movedByUserName`	string	No	User name who is moving the entities

Response

json

{
  "success": true,
  "moved": 3,
  "failed": 0,
  "errors": []
}

Bulk Assign Entities

Assign multiple entities to an owner.

Request

http

PUT /v1/pipelines/:pipelineId/entities/bulk-assign
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "entityIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ],
  "ownerId": "agent_002",
  "ownerName": "Jane Smith"
}

Request Body

Field	Type	Required	Description
`entityIds`	array	Yes	Array of entity IDs (max 50)
`ownerId`	string	Yes	Owner ID
`ownerName`	string	No	Owner name

Response

json

{
  "success": true,
  "assigned": 2,
  "failed": 0,
  "errors": []
}

Get Pipeline Statistics

Get aggregated statistics for a pipeline.

Request

http

GET /v1/pipelines/:pipelineId/stats
x-tenant-api-key: your_api_key_here

Response

json

{
  "pipelineId": "507f1f77bcf86cd799439012",
  "total": 150,
  "stageStats": {
    "new": { "count": 45, "averageDuration": 3600000 },
    "processing": { "count": 30, "averageDuration": 7200000 }
  },
  "stageDistribution": {
    "new": 45,
    "processing": 30,
    "shipped": 50,
    "delivered": 25
  }
}

Error Codes

Code	HTTP Status	Description
`AuthenticationError`	401	Invalid or missing API key
`ValidationError`	400	Request validation failed
`NotFoundError`	404	Resource not found
`ConflictError`	409	Resource conflict (e.g., pipeline in use)
`InternalServerError`	500	Internal server error

Input Constraints

Field	Max Length
`name`	200 characters
`description`	5000 characters
`note`	1000 characters
`stages`	50 stages per pipeline
`stage name`	100 characters
`stage slug`	50 characters

Pagination & Bulk Limits

Operation	Max Limit
Get Pipeline Entities	100 per request
Bulk Move	50 entities
Bulk Assign	50 entities

Stage History

Every stage change is recorded in the entity's stage history. The history is capped at 100 entries per entity to prevent unbounded growth.

Each stage history entry includes:

stage - Stage slug
enteredAt - ISO 8601 timestamp
movedBy - "user" or "manual"
movedByUserId - User who moved (if applicable)
movedByUserName - User name (if applicable)
note - Optional note for the move
duration - Time spent in previous stage (ms)

Audit Events

All operations are logged with structured audit events:

Event	Description
`PIPELINE_CREATED`	Pipeline created
`PIPELINE_UPDATED`	Pipeline updated
`PIPELINE_DELETED`	Pipeline deleted
`ENTITY_ASSIGNED`	Entity assigned to pipeline
`ENTITY_MOVED`	Entity moved between stages
`BULK_MOVE`	Bulk stage move operation
`BULK_ASSIGN`	Bulk assignment operation

Pipelines API Documentation ​

Base URL ​

Authentication ​

Rate Limiting ​

Endpoints Overview ​

Pipeline Entity Types ​

Stage Types ​

Create Pipeline ​

Request ​

Request Body ​

Stage Object ​

Response ​

Pipeline Object Fields ​

List Pipelines ​

Request ​

Query Parameters ​

Response ​

Get Pipeline by ID ​

Request ​

Update Pipeline ​

Request ​

Response ​

Delete Pipeline ​

Request ​

Query Parameters ​

Response ​

Error Responses ​

Check Delete Pipeline ​

Request ​

Response ​

Seed Default Pipelines ​

Request ​

Request Body ​

Response ​

Get Pipeline Entities (Kanban View) ​

Request ​

Query Parameters ​

Response ​

Pipeline Entity Object Fields ​

Stage History Entry Fields ​

Request Body ​

Response ​

Move Entity to Stage ​

Request ​

Request Body ​

Response ​

Bulk Move Entities ​

Request ​

Request Body ​

Response ​

Bulk Assign Entities ​

Request ​

Request Body ​

Response ​

Get Pipeline Statistics ​

Request ​

Response ​

Error Codes ​

Input Constraints ​

Pagination & Bulk Limits ​

Stage History ​

Audit Events ​

Pipelines API Documentation

Base URL

Authentication

Rate Limiting

Endpoints Overview

Pipeline Entity Types

Stage Types

Create Pipeline

Request

Request Body

Stage Object

Response

Pipeline Object Fields

List Pipelines

Request

Query Parameters

Response

Get Pipeline by ID

Request

Update Pipeline

Request

Response

Delete Pipeline

Request

Query Parameters

Response

Error Responses

Check Delete Pipeline

Request

Response

Seed Default Pipelines

Request

Request Body

Response

Get Pipeline Entities (Kanban View)

Request

Query Parameters

Response

Pipeline Entity Object Fields

Stage History Entry Fields

Request Body

Response

Move Entity to Stage

Request

Request Body

Response

Bulk Move Entities

Request

Request Body

Response

Bulk Assign Entities

Request

Request Body

Response

Get Pipeline Statistics

Request

Response

Error Codes

Input Constraints

Pagination & Bulk Limits

Stage History

Audit Events