Delete a workflow

DELETEhttps://<your-url>/api/v2/workflows/{workflow}

MCP id workflows.destroyAlso on this path: GET Read a workflow, PATCH Update a workflow

Permanently deletes a workflow.

Token scope: api:destroy:workflows
Without it: 403 insufficient-token-scope.
Permission: workflows::delete
Without it: 403 insufficient-permission.
Feature: Needs the sprints feature on your organisation.
Without it: 404 endpoint-not-found.
Rate cost: 1 unit, write bucket.
Also: Accepts If-Match. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Delete a workflow and everything on it

curl -X DELETE \
  'https://<your-url>/api/v2/workflows/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/workflows/1', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->delete('https://<your-url>/api/v2/workflows/1');

import requests
response = requests.request(
    'DELETE',
    'https://<your-url>/api/v2/workflows/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

No body.

{
  "type": "https://developers.plnnrly.com/api/v2/problems/precondition-failed",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The record changed since the version named in If-Match. Re-read it and retry.",
  "instance": "/api/v2/work-items/812",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "current_version": 12
}

This resource is hard-delete: there is no restore action, no force parameter and no trashed parameter. This deletes more and is not refused. Every status and every transition in the workflow is deleted with it, and every work item that sat in one of those statuses is deleted as well, taking its subtasks, its links to other work items, its label assignments and its document attachments with it, and detaching the time logged against it. Every project using this workflow is silently detached from it. There is no in-use check and no refusal: a workflow that is driving live projects deletes just as readily as an unused one, which matches plnnrly's equally unguarded delete action. Repoint the affected projects at another workflow first.

Path parameters

workflowintegerRequired

The Workflow's numeric id.

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-Matchstring

The ETag a write is conditional on. A stale validator is 412 precondition-failed.

Response 204

Returns no content.

Headers

RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning