> ## Documentation Index
> Fetch the complete documentation index at: https://help.skillsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Learning Reference List object

> The five company-defined lists that describe a learning item — learning types, training providers, formats, audiences and course levels

<Info>
  **Quick Summary:** A learning item points at up to five reference entries: its type, provider, format, audience and course level. Each list is company-defined, ordered, and served under one parameterised path, `/api/v1/learning-reference/{list}`, with the same shape and operations for all five. Deleting an entry in use is guarded.
</Info>

## Lists

| `{list}`                 | Describes                                       | On the item as                  |
| ------------------------ | ----------------------------------------------- | ------------------------------- |
| `learning-types`         | What kind of content (course, video, document…) | `type` — required on every item |
| `training-providers`     | Who delivers it                                 | `provider`                      |
| `training-formats`       | How it is delivered (online, classroom…)        | `format`                        |
| `training-audiences`     | Who it is for                                   | `audience`                      |
| `training-course-levels` | Difficulty                                      | `courseLevel`                   |

Any other value for `{list}` is a [validation error](/api-docs/errors/validation-error).

## Attributes

| Field            | Type           | Description                                      |
| ---------------- | -------------- | ------------------------------------------------ |
| `id`             | string         | Opaque entry id                                  |
| `name`           | string         |                                                  |
| `description`    | string \| null |                                                  |
| `position`       | integer        | 1-based position in the list's display order     |
| `referenceCount` | integer        | Learning items (and suggestions) using the entry |
| `createdAt`      | string \| null |                                                  |

```json theme={null}
{
  "id": "3",
  "name": "Online course",
  "description": "Self-paced, browser based.",
  "position": 1,
  "referenceCount": 14,
  "createdAt": "2026-01-12T08:30:00.000Z"
}
```

## Operations

| Operation           | Method and path                                  | Requires scope   |
| ------------------- | ------------------------------------------------ | ---------------- |
| List entries        | `GET /api/v1/learning-reference/{list}`          | `learning:read`  |
| List entries in use | `GET /api/v1/learning-reference/{list}/in-use`   | `learning:read`  |
| Get an entry        | `GET /api/v1/learning-reference/{list}/{id}`     | `learning:read`  |
| Create an entry     | `POST /api/v1/learning-reference/{list}`         | `learning:write` |
| Update an entry     | `PATCH /api/v1/learning-reference/{list}/{id}`   | `learning:write` |
| Reorder a list      | `POST /api/v1/learning-reference/{list}/reorder` | `learning:write` |
| Delete an entry     | `DELETE /api/v1/learning-reference/{list}/{id}`  | `learning:write` |

Lists come back in display order and are filterable by `name` (`eq`, `neq`, `like`, `in`) and sortable by `name` and `position`. The **in-use** read returns only entries with a `referenceCount` above zero — the read that drives filter options.

**Create** takes `{ "name": "Workshop", "description": "…" }` and places the entry at the end of the list. **Update** takes `name` and `description`.

**Reorder** takes `{ "ids": ["3", "1", "2"] }` and must list every entry of the list exactly once, in the desired order; a partial, duplicated or foreign list is [422 unprocessable](/api-docs/errors/unprocessable). The response is the whole list with new positions.

**Delete** is guarded. If any learning item uses the entry the call answers [409 conflict](/api-docs/errors/conflict) with `confirmRequired: true` and `dependencies: { "learningItems": 14 }`. Retry with `?confirm=true`: the entry is removed and the reference is cleared from every item — the item's `type`, `provider`, `format`, `audience` or `courseLevel` becomes `null`.

## Permissions

Any person who can see the training library can read the lists. **Creating, updating, reordering and deleting entries follows the same rule as authoring learning items**: global administrators, managers, full-access users and employees may change them; administrators, directors and executives receive [insufficient-permissions](/api-docs/errors/insufficient-permissions). Deleting is restricted to global administrators.

Every operation is company-scoped: an entry of another company is a [404](/api-docs/errors/not-found) to read, update, reorder or delete.

## Related errors

* [validation-error](/api-docs/errors/validation-error) — an unknown `{list}`, a missing name, an unsupported filter operator
* [not-found](/api-docs/errors/not-found) — the entry is not in your company
* [unprocessable](/api-docs/errors/unprocessable) — an incomplete reorder list
* [conflict](/api-docs/errors/conflict) — the guarded delete