---
title: "Delete pipeline stage"
method: DELETE
path: "/api/pipeline-stages/{sid}"
tags: ["pipeline_stages"]
---

# Delete pipeline stage

`DELETE /api/pipeline-stages/{sid}`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/pipeline-stages/{sid}`
- Auth: HTTP bearer and API key in header `Team-SID`

Soft-delete a CUSTOM stage and hand its members to another one. replace_pipeline_stage_sid is required and must be a live stage of the same object: people and companies are repointed to it in the background (retained), so nothing is orphaned, and counts move within seconds rather than instantly. A system stage (key != null) is refused with 422: the auto-transition engine and the company derivation resolve those by key. Never blocked, idempotent (repeat returns already_deleted:true), no restore.

Contract:
- MCP tool `delete_pipeline_stage`, registry package `mcp.playtables/pipeline_stages`, mount `playtables.pipeline`.
- Operation `delete`, response envelope `delete_simple`.
- Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.

## Path parameters

- `sid` string, required: The custom stage to remove. A system stage (key != null) is refused with 422 validation_failed.

## Query parameters

- `replace_pipeline_stage_sid` string, required: Required. Every member object is repointed here, so nothing is orphaned: a live stage of the SAME object (422 otherwise), and not the stage being deleted (the backend does not reject the sid itself, and members would land on the row that just went away).

## Response `200`

`delete_simple` success envelope.

- DeletePipelineStageResponse
  - `success` true, required
  - `operation` 'delete', required
  - `item` object, required
  - `already_deleted` boolean, required
  - `soft_deleted` boolean, required
  - `retained` string[], required
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/revisions/aa394506515d?raw)