learning-pathways

27 endpoints.

GET/api/learning-pathways/mine Bearer token

List my learning pathways with progress

Every unarchived pathway whose audience covers the caller — through a held role, a department they hold a grant in (or one above it), or organization membership — with every level's derived state. Needs no permission grant: the audience is the gate. Locked levels are presentation only; nothing is enforced server-side.

Responses

Status	Description	Body
200	The caller's learning pathways, each with derived progress.	MyPathways
401	The access token is missing or invalid.	ErrorResponse
500	The database could not be read.	ErrorResponse

GET/api/learning-pathways/{pathway_id}/progress Bearer token

Get my progress on one pathway

The pathway's level graph as it stands for the caller: which levels are complete, unlocked or locked, and where every certification stands. Readable by anyone the pathway's audience covers, and by holders of certifications:read over its owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
200	The pathway as it stands for the caller.	PathwayProgress
401	The access token is missing or invalid.	ErrorResponse
404	No visible pathway has that id or slug.	ErrorResponse
500	The database could not be read.	ErrorResponse

GET/api/learning-pathways/{pathway_id}/attachments/{attachment_id}/download Bearer token

Get a download URL for a pathway attachment

Issues a short-lived presigned GET for the private attachment. Readable by anyone the pathway's audience covers, and by holders of certifications:read over its owner. Trainer resources are listed and downloadable by certifications:read holders only.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
200	Where to fetch the file from, for the next five minutes.	DownloadTicket
401	The access token is missing or invalid.	ErrorResponse
404	No visible pathway matches the path, or it has no such attachment.	ErrorResponse
500	The download URL could not be signed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

POST/api/learning-pathways/{pathway_id}/attachment-uploads Bearer token

Request an upload URL for a pathway attachment

Issues a presigned URL to PUT one file of any type straight to private blob storage, scoped to this pathway, the declared content type and a 500 MB ceiling. Attach it with POST /learning-pathways/{pathway_id}/attachments and the returned pathname afterwards. Requires certifications:write.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredCreateDescriptionUploadRequest

Field	Type	Required	Description
file_name	string	yes	1–300 characters
content_type	string	yes	The file's content type; any type is allowed, but the upload pins this one. 1–200 characters
size_bytes	integer	yes	maximum 524288000

Field

Type

Required

Description

file_name

string

yes

1–300 characters

content_type

string

yes

The file's content type; any type is allowed, but the upload pins this one.

1–200 characters

size_bytes

integer

yes

maximum 524288000

Responses

Status	Description	Body
201	Where to PUT the file, and the pathname the attachment will point at.	DescriptionUploadTicket
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but lacks certifications:write.	ErrorResponse
404	No visible pathway matches the path.	ErrorResponse
500	The upload URL could not be signed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

POST/api/learning-pathways/{pathway_id}/attachments Bearer token

Attach an uploaded file to a pathway

Creates the attachment at the end of the authored order, pointing at a pathname an upload ticket was issued for (after PUTting the file there). The content type is read back from the store, never from the request. Requires certifications:write. Trainer resources are listed and downloadable by certifications:read holders only.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredCreatePathwayAttachmentRequest

any

Responses

Status	Description	Body
201	The created attachment.	PathwayAttachment
400	The body failed validation, or the pathname was not uploaded.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but lacks certifications:write.	ErrorResponse
404	No visible pathway matches the path.	ErrorResponse
409	That upload is already attached.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

PATCH/api/learning-pathways/{pathway_id}/attachments/{attachment_id} Bearer token

Relabel or reorder a pathway attachment

Changes the attachment's label (null or empty clears it back to the file name), its audience,, whether it shows on the page or downloads only, or its slot in the authored order. Requires certifications:write.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredUpdatePathwayAttachmentRequest

any

Responses

Status	Description	Body
200	The updated attachment.	PathwayAttachment
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but lacks certifications:write.	ErrorResponse
404	No visible pathway matches the path, or it has no such attachment.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/learning-pathways/{pathway_id}/attachments/{attachment_id} Bearer token

Delete a pathway attachment

Removes the attachment; the blob it pointed at is deleted best-effort. Requires certifications:write.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
204	The attachment is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but lacks certifications:write.	ErrorResponse
404	No visible pathway matches the path, or it has no such attachment.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/learning-pathway-levels/{level_id}/attachments/{attachment_id}/download Bearer token

Get a download URL for a level attachment

Issues a short-lived presigned GET for the private attachment. Readable by anyone the level's pathway's audience covers, and by holders of certifications:read over its owner. Trainer resources are listed and downloadable by certifications:read holders only.

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.

Responses

Status	Description	Body
200	Where to fetch the file from, for the next five minutes.	DownloadTicket
401	The access token is missing or invalid.	ErrorResponse
404	No visible level matches the path, or it has no such attachment.	ErrorResponse
500	The download URL could not be signed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

POST/api/learning-pathway-levels/{level_id}/attachment-uploads Bearer token

Request an upload URL for a level attachment

Issues a presigned URL to PUT one file of any type straight to private blob storage, scoped to this level, the declared content type and a 500 MB ceiling. Attach it with POST /learning-pathway-levels/{level_id}/attachments and the returned pathname afterwards. Requires certifications:write.

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.

Request body

application/jsonrequiredCreateDescriptionUploadRequest

Field	Type	Required	Description
file_name	string	yes	1–300 characters
content_type	string	yes	The file's content type; any type is allowed, but the upload pins this one. 1–200 characters
size_bytes	integer	yes	maximum 524288000

Field

Type

Required

Description

file_name

string

yes

1–300 characters

content_type

string

yes

The file's content type; any type is allowed, but the upload pins this one.

1–200 characters

size_bytes

integer

yes

maximum 524288000

Responses

Status	Description	Body
201	Where to PUT the file, and the pathname the attachment will point at.	DescriptionUploadTicket
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this level but lacks certifications:write.	ErrorResponse
404	No visible level matches the path.	ErrorResponse
500	The upload URL could not be signed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

POST/api/learning-pathway-levels/{level_id}/attachments Bearer token

Attach an uploaded file to a level

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.

Request body

application/jsonrequiredCreatePathwayAttachmentRequest

any

Responses

Status	Description	Body
201	The created attachment.	PathwayAttachment
400	The body failed validation, or the pathname was not uploaded.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this level but lacks certifications:write.	ErrorResponse
404	No visible level matches the path.	ErrorResponse
409	That upload is already attached.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse
503	File storage is not configured on this deployment.	ErrorResponse

PATCH/api/learning-pathway-levels/{level_id}/attachments/{attachment_id} Bearer token

Relabel or reorder a level attachment

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.

Request body

application/jsonrequiredUpdatePathwayAttachmentRequest

any

Responses

Status	Description	Body
200	The updated attachment.	PathwayAttachment
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this level but lacks certifications:write.	ErrorResponse
404	No visible level matches the path, or it has no such attachment.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/learning-pathway-levels/{level_id}/attachments/{attachment_id} Bearer token

Delete a level attachment

Removes the attachment; the blob it pointed at is deleted best-effort. Requires certifications:write.

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.

Responses

Status	Description	Body
204	The attachment is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this level but lacks certifications:write.	ErrorResponse
404	No visible level matches the path, or it has no such attachment.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

PUT/api/learning-pathways/{pathway_id}/job-aids Bearer token

Replace the job aids presented on a pathway

Sets the complete, ordered list of job aids shown on the pathway's overview beside its handouts. Aids of the pathway's own organization only; each is shown only to viewers its own audience covers. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredSetLinkedJobAidsRequest

Field	Type	Required	Description
job_aid_ids	array of string (uuid)	yes	Replaces the whole list of job aids presented here, in the given order. Aids of the pathway's own organization only. at most 100 items

Field

Type

Required

Description

job_aid_ids

array of string (uuid)

yes

Replaces the whole list of job aids presented here, in the given order. Aids of the pathway's own organization only.

at most 100 items

Responses

Status	Description	Body
200	The pathway's job aids after the change, in authored order.	array of JobAidRef
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug, or an aid is not the organization's own.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

PUT/api/learning-pathway-levels/{level_id}/job-aids Bearer token

Replace the job aids presented on a level

Sets the complete, ordered list of job aids shown on the level's card beside its handouts. Aids of the pathway's own organization only; each is shown only to viewers its own audience covers. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.

Request body

application/jsonrequiredSetLinkedJobAidsRequest

Field	Type	Required	Description
job_aid_ids	array of string (uuid)	yes	Replaces the whole list of job aids presented here, in the given order. Aids of the pathway's own organization only. at most 100 items

Field

Type

Required

Description

job_aid_ids

array of string (uuid)

yes

Replaces the whole list of job aids presented here, in the given order. Aids of the pathway's own organization only.

at most 100 items

Responses

Status	Description	Body
200	The level's job aids after the change, in authored order.	array of JobAidRef
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this level but does not hold certifications:write.	ErrorResponse
404	No visible level has that id, or an aid is not the organization's own.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/learning-pathways/{pathway_id}/levels Bearer token

Add a level to a pathway

Creates a level at the end of the authored order, with its phase, its prerequisite levels and phases, and its certification contents in one call. A certification type may appear in at most one level per pathway. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredCreatePathwayLevelRequest

Field	Type	Required	Description
name	string	yes	1–200 characters
description	string	no	Omit or send empty for no description. at most 2000 characters
description_markdown	string	no	Omit or send empty for no long-form markdown description. at most 50000 characters
phase_id	string (uuid) \| null	no	An existing phase of the same pathway to group the level under. Omit for none.
depends_on_level_ids	array of string (uuid)	no	Existing levels of the same pathway this one depends on. The edges must keep the pathway acyclic. Omit for a root level. at most 50 items
depends_on_phase_ids	array of string (uuid)	no	Existing phases of the same pathway this one depends on — every level of each must be complete first. Never the level's own phase; the expanded edges must stay acyclic. at most 50 items
certification_type_ids	array of string (uuid)	no	Certification types of the same organization to place in this level, in order. A type may appear in at most one level per pathway. at most 100 items

Responses

Status	Description	Body
201	The created level, with its prerequisites and contents.	PathwayLevel
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug, or a phase, prerequisite level or certification type does not belong to it.	ErrorResponse
409	A certification type is already placed elsewhere in this pathway, the level would depend on its own phase, or the prerequisites would form a cycle.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

PATCH/api/learning-pathway-levels/{level_id} Bearer token

Update a level

Renames or re-describes a level, or moves it between phases (phase_id, null to ungroup); depends_on_level_ids and depends_on_phase_ids each replace its whole prerequisite set of that kind (rejected when the expanded edges would close a cycle, or the level would depend on its own phase), certification_type_ids its whole contents. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.

Request body

application/jsonrequiredUpdatePathwayLevelRequest

Field	Type	Required	Description
name	string	no	1–200 characters
description	string \| null	no	Send null to clear the description. at most 2000 characters
description_markdown	string \| null	no	Send null to clear the long-form markdown description. at most 50000 characters
position	integer	no	minimum 0
phase_id	string (uuid) \| null	no	Moves the level into a phase of its pathway; send null to ungroup it.
depends_on_level_ids	array of string (uuid)	no	Replaces the level's whole level-prerequisite set; must stay acyclic. at most 50 items
depends_on_phase_ids	array of string (uuid)	no	Replaces the level's whole phase-prerequisite set; never its own phase, and the expanded edges must stay acyclic. at most 50 items
certification_type_ids	array of string (uuid)	no	Replaces the level's whole certification list, in the given order. at most 100 items

Responses

Status	Description	Body
200	The updated level, with its prerequisites and contents.	PathwayLevel
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible level has that id, or a phase, prerequisite level or certification type does not belong to its pathway.	ErrorResponse
409	The prerequisites would form a cycle, the level would depend on its own phase, or a certification type is already placed elsewhere in this pathway.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/learning-pathway-levels/{level_id} Bearer token

Delete a level

Removes the level, its edges and its contents; levels that depended on it simply lose that prerequisite. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
level_id	path	string (uuid)	yes	UUID id of the level.

Responses

Status	Description	Body
204	The level is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible level has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/learning-pathways/{pathway_id}/phases Bearer token

Add a phase to a pathway

Creates a phase — a grouping of the pathway's levels — with the phases it comes after. That ordering lays the phases out; it gates nothing. Levels join a phase through their own phase_id. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredCreatePathwayPhaseRequest

Field

Type

Required

Description

name

string

yes

1–200 characters

description_markdown

string

Omit or send empty for no markdown description.

at most 50000 characters

depends_on_phase_ids

array of string (uuid)

Existing phases of the same pathway this one comes after. The edges must keep the phases acyclic. Omit for a first phase.

at most 50 items

Responses

Status	Description	Body
201	The created phase, with the phases it comes after.	PathwayPhase
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug, or a phase it would come after does not belong to it.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

PATCH/api/learning-pathway-phases/{phase_id} Bearer token

Update a phase

Renames or re-describes a phase; depends_on_phase_ids replaces the whole set of phases it comes after (rejected when the ordering would close a cycle). Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
phase_id	path	string (uuid)	yes	UUID id of the phase.

Request body

application/jsonrequiredUpdatePathwayPhaseRequest

Field

Type

Required

Description

name

string

1–200 characters

description_markdown

string | null

Send null to clear the markdown description.

at most 50000 characters

depends_on_phase_ids

array of string (uuid)

Replaces the whole set of phases this one comes after; must stay acyclic.

at most 50 items

Responses

Status	Description	Body
200	The updated phase, with the phases it comes after and its levels.	PathwayPhase
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible phase has that id, or a phase it would come after does not belong to its pathway.	ErrorResponse
409	The ordering would put a phase after itself.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/learning-pathway-phases/{phase_id} Bearer token

Delete a phase

Removes an empty phase. One that still holds levels, or that levels depend on, is refused until those are moved out or re-pointed; phases that came after it simply lose that predecessor. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
phase_id	path	string (uuid)	yes	UUID id of the phase.

Responses

Status	Description	Body
204	The phase is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible phase has that id.	ErrorResponse
409	The phase still holds levels, or levels still depend on it.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/learning-pathways/{pathway_id}/assignments Bearer token

Assign a pathway's audience

Presents the pathway to holders of a role, to everyone with a role grant in a department (or one nested beneath it), or to every member of the organization. The audience is presentation only — it never adds a certification requirement. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredCreatePathwayAssignmentRequest

Field	Type	Required	Description
assignee_kind	string	yes	role: holders of role_id. department: everyone with a role grant in department_id or any department nested beneath it. organization: every member. one of "role" \| "department" \| "organization"
role_id	string (uuid)	no	Required for role assignments; must be a role of the pathway's organization.
department_id	string (uuid)	no	Required for department assignments; forbidden for organization ones.

Field

Type

Required

Description

assignee_kind

string

yes

role: holders of role_id. department: everyone with a role grant in department_id or any department nested beneath it. organization: every member.

one of "role" | "department" | "organization"

role_id

string (uuid)

Required for role assignments; must be a role of the pathway's organization.

department_id

string (uuid)

Required for department assignments; forbidden for organization ones.

Responses

Status	Description	Body
201	The created assignment.	PathwayAssignment
400	The request body failed validation, or the kind/id pairing is off.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug, or the role or department is not in the pathway's organization.	ErrorResponse
409	The pathway already has that audience row.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/learning-pathways/{pathway_id}/assignments/{assignment_id} Bearer token

Remove one audience row

Withdraws the pathway from that role, department or organization audience. Requires certifications:write over the pathway's owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
assignment_id	path	string (uuid)	yes	UUID id of the assignment.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
204	The assignment is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug, or no such assignment on it.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/learning-pathways Bearer token

List learning pathways

Lists the learning pathways the caller can administer, newest first, with cursor pagination. Requires certifications:read in scope; rows outside the caller's scope are simply absent. Trainees list what is assigned to them at /learning-pathways/mine instead.

Parameters

Name	In	Type	Required	Description
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).
department	query	string	no	Department UUID id or slug, resolved within org (which is then required).
include_archived	query	string	no	Include archived rows. Defaults to false.
limit	query	integer	no	Page size, 1-200. Defaults to 50.
cursor	query	string	no	Opaque cursor from a previous page's next_cursor.

Responses

Status	Description	Body
200	One page of learning pathways, and the cursor for the next.	PathwayList
400	A filter did not resolve, or the cursor is malformed.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/learning-pathways Bearer token

Create a learning pathway

Creates a pathway, owned by an organization or one department within it. A pathway arranges existing certification types into levels with prerequisite edges — a presentation overlay that never adds a requirement. Add levels and assign the audience next. Requires certifications:write over the owner.

Request body

application/jsonrequiredCreatePathwayRequest

Field	Type	Required	Description
owner_organization_id	string (uuid)	yes	Organization the pathway belongs to. Always required.
owner_department_id	string (uuid)	no	Omit for a pathway owned by the organization directly.
slug	string	yes	Unique within the organization. Slugs are lowercase letters and digits in words separated by single hyphens, like new-hire-path. 1–100 characters · matches ^[a-z0-9]+(-[a-z0-9]+)*$
name	string	yes	1–200 characters
description_markdown	string	no	Omit or send empty for no markdown description. at most 50000 characters

Responses

Status	Description	Body
201	The created pathway, with no levels yet.	Pathway
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold certifications:write over the owner.	ErrorResponse
404	The organization, or the department within it, does not exist.	ErrorResponse
409	The organization already has a pathway with that slug.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/learning-pathways/{pathway_id} Bearer token

Get a pathway with its structure

The pathway, its phases, every level with its phase, prerequisites, certification contents and job aids, and the audience — the authoring read. Requires certifications:read over the owner; trainees read their own derived view at /learning-pathways/{pathway_id}/progress instead.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
200	The pathway, its phases and levels, and its audience.	PathwayDetail
401	The access token is missing or invalid.	ErrorResponse
404	No visible pathway has that id or slug.	ErrorResponse
500	The database could not be read.	ErrorResponse

PATCH/api/learning-pathways/{pathway_id} Bearer token

Update a pathway

Renames, re-slugs or re-describes a pathway. File attachments are managed through the /learning-pathways/{pathway_id}/attachments endpoints. Requires certifications:write over the owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Request body

application/jsonrequiredUpdatePathwayRequest

Field

Type

Required

Description

slug

string

1–100 characters · matches ^[a-z0-9]+(-[a-z0-9]+)*$

name

string

1–200 characters

description_markdown

string | null

Send null to clear the markdown description.

at most 50000 characters

Responses

Status	Description	Body
200	The updated pathway.	Pathway
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug.	ErrorResponse
409	The organization already has a pathway with the new slug.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/learning-pathways/{pathway_id}/archive Bearer token

Archive a pathway

Retires the pathway: it stays readable to administrators but leaves every trainee's pathway list. Idempotent. Requires certifications:write over the owner.

Parameters

Name	In	Type	Required	Description
pathway_id	path	string	yes	UUID id, or a slug resolved within the organization given by the org query parameter.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
200	The archived pathway.	Pathway
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this pathway but does not hold certifications:write.	ErrorResponse
404	No visible pathway has that id or slug.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse