> ## Documentation Index > Fetch the complete documentation index at: https://docs.tetherai.ca/llms.txt > Use this file to discover all available pages before exploring further. # Update or create organization pipeline > Upsert the org's default pipeline for the given `type`. When the legacy `stages` mapping is provided, the controller also migrates existing records from `oldStage` to `newStage` and returns the per-stage migration counts on the response. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/pipelines openapi: 3.0.3 info: title: Tether Relay and Tether API version: 1.0.0 description: >- Route-derived OpenAPI contract generated from tether-relay backend sources. Regenerate with scripts/sync-openapi-from-backend.mjs. servers: - url: https://your-instance.example.com description: Production - url: http://localhost:2212 description: Local API service security: [] tags: - name: AI - name: Applications - name: Approval - name: Auth - name: Automations - name: Calls - name: Campaigns - name: Contact Analytics - name: Contact Metrics - name: Contact Notes - name: Contacts - name: Conversation Monitor - name: Conversations - name: Departments - name: Email - name: Escalation Dashboard - name: Event Logs - name: Google Sheets - name: Marketplace - name: Messages - name: Notification Sounds - name: Notifications - name: Org Snapshots - name: Organizations - name: Outreach - name: Outreach Metrics - name: Outreach Sources - name: Pipelines - name: Processes - name: Prompts - name: Reminders - name: Sms - name: Templates - name: Traces - name: Training - name: Upload - name: User Snapshots - name: Users - name: Vertical - name: Webchats - name: Webhook paths: /api/pipelines: post: tags: - Pipelines summary: Update or create organization pipeline description: >- Upsert the org's default pipeline for the given `type`. When the legacy `stages` mapping is provided, the controller also migrates existing records from `oldStage` to `newStage` and returns the per-stage migration counts on the response. operationId: post_pipelines parameters: - in: query name: type required: false schema: type: string enum: - Contact - Application default: Contact requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatePipelineRequest' responses: '200': description: Pipeline updated content: application/json: schema: $ref: '#/components/schemas/PipelineMutationResponse' '201': description: Pipeline created content: application/json: schema: $ref: '#/components/schemas/PipelineMutationResponse' '207': description: Pipeline updated with partial migration failure content: application/json: schema: $ref: '#/components/schemas/PipelineMigrationErrorResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/PipelineErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/PipelineErrorResponse' '404': description: Pipeline not found content: application/json: schema: $ref: '#/components/schemas/PipelineErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/PipelineErrorResponse' security: - bearerAuth: [] components: schemas: UpdatePipelineRequest: type: object properties: name: type: string description: Pipeline display name; trimmed and unique within the organization. description: type: string description: Optional human-readable summary of the pipeline's purpose. pipelineId: type: string description: >- Pipeline to update; if omitted, the org's default pipeline for the given `type` is updated. stages: type: array description: >- Legacy stage-rename mapping — pairs of `oldStage` -> `newStage` used to migrate existing records. Prefer `pipelineStages`. items: $ref: '#/components/schemas/LegacyStageItem' pipelineStages: type: array description: >- Stage definitions with `_id` (for updates), `name`, `color`, and `position`; omitted stages are deactivated. items: $ref: '#/components/schemas/PipelineStageItem' additionalProperties: true example: name: Sales pipeline description: NA sales pipeline pipelineId: 66f0a0b0c0d0e0f0a0b0c0d0 pipelineStages: - name: New color: '#3B82F6' position: 0 - name: Qualified color: '#10B981' position: 1 - name: Won color: '#F59E0B' position: 2 PipelineMutationResponse: type: object properties: message: type: string pipeline: $ref: '#/components/schemas/PipelineDto' contactsMigrated: type: object additionalProperties: type: number additionalProperties: true example: message: Pipeline updated pipeline: _id: 66f0a0b0c0d0e0f0a0b0c0d0 name: Sales pipeline type: Contact isDefault: true contactsMigrated: New Lead -> New: 14 Qualified Lead -> Qualified: 8 PipelineMigrationErrorResponse: type: object properties: message: type: string pipeline: $ref: '#/components/schemas/PipelineDto' migrationError: type: string contactsMigrated: type: object additionalProperties: type: number additionalProperties: true example: message: Pipeline updated with partial migration failure pipeline: _id: 66f0a0b0c0d0e0f0a0b0c0d0 name: Sales pipeline migrationError: Some records failed to migrate from "Stalled" -> "Lost" contactsMigrated: New Lead -> New: 14 PipelineErrorResponse: type: object properties: error: type: string additionalProperties: true example: error: Pipeline not found LegacyStageItem: type: object properties: oldStage: type: string description: >- Previous stage name; existing records with this `status` are migrated to `newStage`. newStage: type: string description: >- New stage name to apply; becomes the stored stage and the migrated `status` value. color: type: string description: Hex color used to render the stage chip in the pipeline UI. additionalProperties: true example: oldStage: New Lead newStage: New color: '#3B82F6' PipelineStageItem: type: object properties: _id: type: string description: >- Existing stage id; include to update/rename a stage, omit to create a new one. name: type: string description: Stage display name; must be unique within the pipeline. color: type: string description: Hex color used to render the stage chip in the pipeline UI. position: type: number description: >- Zero-based sort order within the pipeline; defaults to array index when omitted. additionalProperties: true example: _id: 67f0a0b0c0d0e0f0a0b0c0d0 name: Qualified color: '#10B981' position: 1 PipelineDto: type: object properties: _id: type: string name: type: string description: type: string organizationId: type: string type: type: string enum: - Contact - Application isDefault: type: boolean isActive: type: boolean stages: type: array items: type: object properties: name: type: string color: type: string additionalProperties: true pipelineStageIds: type: array items: type: string pipelineStages: type: array items: $ref: '#/components/schemas/PipelineStageItem' createdBy: type: string description: User ID or populated user object updatedBy: type: string description: User ID or populated user object additionalProperties: true example: _id: 66f0a0b0c0d0e0f0a0b0c0d0 name: Sales pipeline description: NA sales pipeline organizationId: 65a0e0e0e0e0e0e0e0e0e0e0 type: Contact isDefault: true isActive: true stages: - name: New color: '#3B82F6' - name: Qualified color: '#10B981' pipelineStageIds: - 67f0a0b0c0d0e0f0a0b0c0d0 - 67f0a0b0c0d0e0f0a0b0c0d1 pipelineStages: - _id: 67f0a0b0c0d0e0f0a0b0c0d0 name: New color: '#3B82F6' position: 0 - _id: 67f0a0b0c0d0e0f0a0b0c0d1 name: Qualified color: '#10B981' position: 1 createdBy: 65b1f0a2c3d4e5f6a7b8c9d0 updatedBy: 65b1f0a2c3d4e5f6a7b8c9d0 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````