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

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

{
  "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

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

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

---

Get Pipeline by ID

Retrieve a single pipeline by its ID.

Request

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

---

Update Pipeline

Update an existing pipeline.

Request

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

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

---

Delete Pipeline

Delete a pipeline. System pipelines cannot be deleted.

Request

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

{
  "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

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

Response

{
  "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

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

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

---

Get Pipeline Entities (Kanban View)

Retrieve all entities in a pipeline grouped by stage.

Request

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

{
  "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

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

---

Move Entity to Stage

Move an entity to a different stage in the pipeline.

Request

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

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

---

Bulk Move Entities

Move multiple entities to a stage in a single operation.

Request

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

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

---

Bulk Assign Entities

Assign multiple entities to an owner.

Request

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

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

---

Get Pipeline Statistics

Get aggregated statistics for a pipeline.

Request

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

Response

{
  "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