Delete a work type

DELETEhttps://<your-url>/api/v2/work-types/{work_type}

MCP id work-types.destroyAlso on this path: GET Read a work type, PATCH Update a work type

Permanently deletes a work-item type.

Token scope: api:destroy:work_types
Without it: 403 insufficient-token-scope.
Permission: work_types::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 an unused work type

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

const response = await fetch('https://<your-url>/api/v2/work-types/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/work-types/1');

import requests
response = requests.request(
    'DELETE',
    'https://<your-url>/api/v2/work-types/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. A type that is still used by work items cannot be deleted: it answers 403 forbidden-by-policy, or 404 resource-not-found when your token does not also carry work_types::read, because a refusal naming a specific id must not confirm that id to a caller who cannot read the collection. Without that refusal, deleting the type would also delete every work item of that type together with its comments, subtasks, links and attachments. Retype the affected work items first, then delete.

Path parameters

work_typeintegerRequired

The WorkType'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

Errors

403 Forbidden.

forbidden-by-policy insufficient-permission insufficient-token-scope

forbidden-by-policy: Work items still use this type. Move them to another type first: deleting the type would also delete them, with their comments, subtasks, links and attachments.

412 Precondition failed.

precondition-failed

7 errors every operation can return: 400, 401, 404, 406, 429, 500, 503

400 Bad request.

idempotency-key-required invalid-cursor invalid-query-parameter malformed-request unsupported-parameter

401 Unauthenticated.

token-expired unauthenticated

404 Not found.

endpoint-not-found resource-not-found

406 Not acceptable.

not-acceptable

429 Too many requests.