The Learning Item object

Quick Summary: A learning item is an entry in your company’s training catalogue. It carries a title, an optional link or file, a learning type and up to four further references (provider, format, audience, course level) drawn from the company’s reference lists. Items are attached to skills and careers, labelled, and assigned to people as learning plans. Deleting is guarded.

Attributes

Field	Type	Description
`id`	string	Opaque learning item id
`title`	string
`description`	string \| null
`url`	string \| null	Link to the content. Unique within the company
`durationHours`	number \| null
`cost`	number \| null
`costDescription`	string \| null	Free text next to the cost
`type`	`{ id, name }` \| null	Learning type (reference list)
`provider`	`{ id, name }` \| null	Training provider (reference list)
`format`	`{ id, name }` \| null	Training format (reference list)
`audience`	`{ id, name }` \| null	Training audience (reference list)
`courseLevel`	`{ id, name }` \| null	Training course level (reference list)
`imageUrl`	string \| null	Display image
`hasFile`	boolean	An attached file exists; fetch it with the download-url operation
`referenceId`	string \| null	Caller-supplied external identifier
`labels`	`[{ id, name }]`	Labels attached to the item
`skillNames`	string[]	Names of the skills the item is attached to
`careerNames`	string[]	Names of the careers the item appears on
`assignedCount` / `inProgressCount` / `completedCount`	integer	Learning plans for active people, by state
`averageRating`	number \| null	Mean of the thumbs ratings (0 down, 1 up, 2 double up); `null` until someone rates
`createdAt` / `updatedAt`	string \| null

The five references are published as { id, name } pairs resolved against the reference lists. The legacy free-text provider, level, format and audience columns the app still stores are not part of the object.

{
  "id": "512",
  "title": "Forklift Safety Refresher",
  "description": "Annual refresher for licensed operators.",
  "url": "https://learn.example.com/forklift",
  "durationHours": 2.5,
  "cost": 120,
  "costDescription": null,
  "type": { "id": "3", "name": "Online course" },
  "provider": { "id": "1", "name": "Acme Learning" },
  "format": null,
  "audience": null,
  "courseLevel": null,
  "imageUrl": null,
  "hasFile": false,
  "referenceId": "LMS-4471",
  "labels": [{ "id": "12", "name": "Safety" }],
  "skillNames": ["Forklift Operation"],
  "careerNames": [],
  "assignedCount": 40,
  "inProgressCount": 12,
  "completedCount": 25,
  "averageRating": 1.6,
  "createdAt": "2026-01-12T08:30:00.000Z",
  "updatedAt": null
}

Operations

Catalogue

Operation	Method and path	Requires scope
List learning items	`GET /api/v1/learning-items`	`learning:read`
Get a learning item	`GET /api/v1/learning-items/{id}`	`learning:read`
Create a learning item	`POST /api/v1/learning-items`	`learning:write`
Create a learning item with a file	`POST /api/v1/learning-items/with-file`	`learning:write`
Update a learning item	`PATCH /api/v1/learning-items/{id}`	`learning:write`
Delete a learning item	`DELETE /api/v1/learning-items/{id}`	`learning:write`

The list is filterable by title, id, labels, people, rating, cost, duration and skill — the app’s library filters under the same names — and sortable by title, cost, duration, rating and id. Pending and rejected suggestions are not part of the catalogue. Create needs title and typeId; providerId, formatId, audienceId, courseLevelId, labelIds and skillIds are optional. A reference id that is not an entry of the company’s list is a field-level validation error. Create with a file is the two-step path: send the same body plus fileName, receive { item, uploadUrl }, then PUT the file’s bytes to uploadUrl (a short-lived pre-signed URL). hasFile is true from the moment the item exists. Update is partial: a field that is absent is left alone, an explicit null clears it. A url already used by another item is a 409 conflict. Delete is guarded. If the item is assigned to anyone or attached to a skill or career the call answers 409 conflict:

{
  "type": "https://help.skillsdb.com/api-docs/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The learning item is assigned to people or attached to skills or careers. Retry with ?confirm=true to delete it anyway: every assignment and attachment is removed with it.",
  "confirmRequired": true,
  "dependencies": { "learningPlans": 40, "skills": 2, "careers": 1 }
}

Retry with ?confirm=true to delete the item together with every assignment and attachment.

Skills

Operation	Method and path	Requires scope
List an item’s skills	`GET /api/v1/learning-items/{id}/skills`	`learning:read`
Attach a skill	`POST /api/v1/learning-items/{id}/skills`	`learning:write`
Feature or unfeature for a skill	`PATCH /api/v1/learning-items/{id}/skills/{skillId}`	`learning:write`
Detach a skill	`DELETE /api/v1/learning-items/{id}/skills/{skillId}`	`learning:write`

Attach takes { "skillId": "77", "featured": true } (featured optional) and is idempotent — attaching a skill the item already carries succeeds without change. Detaching a skill the item does not carry is a no-op. Every call answers the item’s current skills, each as { skill: { id, name }, featured }. A featured item is shown first for the skill.

Careers, labels, ratings and file

Operation	Method and path	Requires scope
List the careers an item appears on	`GET /api/v1/learning-items/{id}/careers`	`learning:read`
Replace an item’s labels	`PUT /api/v1/learning-items/{id}/labels`	`learning:write`
Get rating counts	`GET /api/v1/learning-items/{id}/ratings`	`learning:read`
Get a download URL for the file	`GET /api/v1/learning-items/{id}/download-url`	`learning:read`

Replace labels takes { "labelIds": ["12", "15"] } and sets the complete set; an empty list clears every label. Incremental attach and detach live on the Label resource. Ratings answers { thumbsDown, thumbsUp, doubleThumbsUp }. Download URL answers a short-lived pre-signed URL; an item without a file is a 404.

Permissions

Any person who can see the training library in the app can read items here. Creating and updating items, and attaching skills or labels, requires a person who may author training in the app (global administrators, managers, full-access users and employees); administrators, directors and executives receive insufficient-permissions even when the key holds learning:write. Deleting is restricted to global administrators.

Excluded

Assigning an item to a person, progress and completion, and thumbs ratings belong to the Learning Plan resource. Proposals from people who cannot author the catalogue are Learning Suggestions. CSV import and the “fetch the page’s title” convenience when pasting a URL are in-app paths.

not-found — the item, or a skill named in a feature or detach call, is not in your company or not attached
validation-error — a missing title or type, a reference id that is not in the company’s list, an unknown skill or label
conflict — a duplicate URL; the guarded delete
insufficient-permissions — the acting person may not author or delete training

Using the API

System Objects

Team Data

Errors

The Learning Item object

Attributes

Operations

Catalogue

Skills

Careers, labels, ratings and file

Permissions

Excluded

​Attributes

​Operations

​Catalogue

​Skills

​Careers, labels, ratings and file

​Permissions

​Excluded

​Related errors

Attributes

Operations

Catalogue

Skills

Careers, labels, ratings and file

Permissions

Excluded

Related errors