# Update several terms

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

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

Changes up to 500 terms of one set in one call. Send each term's `termId` with only the fields to change. Every term keeps its id, image and review history. All the changes are saved together, or none when a `termId` isn't the set's.

Use this to save content you wrote yourself. It uses none of the user's WorkRoad AI uses.

- MCP tool: `updateSetTerms` on `https://workroad.app/api/mcp`
- Required scopes: sets:update
- Test mode: `PATCH https://workroad.app/api/test/v1/sets/{setId}/terms` 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.

## Request body

JSON.

- `terms`: array of objects, required, 1-500 items. 1-500 terms, each with its `termId` and only the fields to change.
  - `termId`: string (uuid), required. A term of this set.
  - `term`: string, 1-2000 characters
  - `definition`: string, 1-4000 characters
  - `hints`: array of string, up to 10 items. Replaces the full list when sent.

## Response

`200` OK

- `data`: object, required
  - `terms`: array of objects, required. The terms as saved, in the order sent.
    - `id`: string (uuid), required
    - `term`: string, required
    - `definition`: string, required
    - `hints`: array of string, required

### Example

```json
{
  "data": {
    "terms": [
      {
        "id": "2a1b0c9d-8e7f-4a6b-9c5d-4e3f2a1b0c9d",
        "term": "tener (yo)",
        "definition": "tuve",
        "hints": [
          "irregular stem tuv-"
        ]
      }
    ]
  }
}
```

## 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.
- `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