---
title: "Delete Role"
method: DELETE
path: "/api/roles/{role_id}"
tags: ["roles"]
---

# Delete Role

`DELETE /api/roles/{role_id}`

## Request

- Base URL: `https://api.parlel.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.parlel.com/api/roles/{role_id}`
- Auth: none declared

Delete a role that was never published. Refuse to delete one that was.

## Why this is not an unconditional delete

A role that has been open has been linked to -- in a message, in a newsletter,
in somebody's saved tabs, and in an agent's finding, which is a claim this
product made to a user about the world at a moment in time. Deleting the row
breaks all of those and rewrites the record so the opening never existed. That
is the exact failure ``models.Role``'s three-state ``status`` was designed
around, and an endpoint that undoes it in one call would make the design
decorative.

So: a draft is genuinely disposable and is deleted outright. Anything with a
``published_at`` is refused with a 409 that names the alternative, which is
``POST /api/roles/{id}/close`` -- it removes the role from the board and from
every match, and leaves the URL resolving.

``published_at`` rather than ``status`` is the test, deliberately. A role that
was open and is now closed has a null-free ``published_at`` and a status of
``closed``; testing the status would let a company close a role and then delete
it, which is the same broken links by two steps.

204 with no body: there is nothing useful to say, and a body on a delete is a
thing clients then start parsing.

## Path parameters

- `role_id` string, required

## Headers

- `authorization` string, nullable

## Response `204`

Successful Response

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/parlel/apis/parlel-api.md) · [All operations](https://skmtc.dev/parlel/apis/parlel-api/llms.txt) · [OpenAPI document](https://skmtc.dev/parlel/apis/parlel-api/revisions/4d41a8f5cfc9?raw)