# Delete several terms

Source: https://workroad.app/docs/api/delete-set-terms

`POST https://workroad.app/api/v1/sets/{setId}/terms/delete`

Deletes up to 500 terms of one set in one call, with their images. This permanently removes each term's flashcard review history. The set keeps at least one term: a call that would delete them all deletes nothing; delete the set instead. Nothing is deleted when a `termId` isn't the set's.

- MCP tool: `deleteSetTerms` on `https://workroad.app/api/mcp`
- Required scopes: sets:delete
- Test mode: `POST https://workroad.app/api/test/v1/sets/{setId}/terms/delete` checks the request and returns the example response without changing anything.

## Path parameters

- `setId`: string (uuid), required. Study set id, scoped to the key's user.

## Headers

- `Idempotency-Key`: string, optional, 1-255 visible ASCII characters. Makes the POST safe to retry: a retry with the same key and body replays the first response, and the same key with a different body returns 409 `idempotency_conflict`. Kept for 24 hours. Over MCP it is the `idempotencyKey` argument.

## Request body

JSON.

- `termIds`: array of string (uuid), required, 1-500 items. 1-500 ids of this set's terms.

## Response

`200` OK

- `data`: object, required
  - `termIds`: array of string (uuid), required. The deleted terms.
  - `deleted`: `true`, required

### Example

```json
{
  "data": {
    "termIds": [
      "2a1b0c9d-8e7f-4a6b-9c5d-4e3f2a1b0c9d"
    ],
    "deleted": true
  }
}
```

## Errors

Every error has the body `{ "error": { "code", "message", "details" } }`.

- `400`: Invalid body, or `details.reason` `unknown-term` with the ids that aren't the set's in `details.termIds`.
- `401`: Missing, invalid, disabled or expired API key
- `403`: The API key lacks the required scope
- `404`: No study set with that id exists for this key's user.
- `405`: Method not allowed. Use a method from the Allow header.
- `409`: The call would delete every term (`details.reason` is `last-term`). The Idempotency-Key was reused with a different request body, or a request with the same key is still in progress.
- `429`: Rate limit exceeded. Wait for Retry-After before retrying. The rate-limit headers are absent when the key's own limiter rejected the request before the per-endpoint bucket check ran.
- `500`: Internal server error