subjects

9 endpoints.

GET/api/subjects Bearer token

List subject matters

Lists the subject matters the caller can read, newest first, with cursor pagination. Requires subjects:read in scope; rows outside the caller's scope are simply absent.

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 subject matters, and the cursor for the next.	SubjectMatterList
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/subjects Bearer token

Create a subject matter

Creates a subject matter owned by an organization, or by one department within it, optionally filed beneath broader subjects of the same organization. Requires subjects:write over the owner.

Request body

application/jsonrequiredCreateSubjectMatterRequest

Field	Type	Required	Description
owner_organization_id	string (uuid)	yes	Organization the subject belongs to. Always required.
owner_department_id	string (uuid)	no	Omit for a subject 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 forklift-safety. 1–100 characters · matches ^[a-z0-9]+(-[a-z0-9]+)*$
name	string	yes	1–200 characters
description	string	no	Omit or send empty for no description. at most 2000 characters
parent_ids	array of string (uuid)	no	Broader subjects of the same organization to file the new one beneath; omit for a top-level subject. at most 50 items

Responses

Status	Description	Body
201	The created subject matter.	SubjectMatter
400	The request body failed validation, or a parent is the subject itself.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold subjects:write over the owner.	ErrorResponse
404	The organization, the department within it, or a parent subject in it does not exist.	ErrorResponse
409	The organization already has a subject with that slug.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/subjects/{subject_id}/permanent-deletion Bearer token

Preview permanently deleting a subject matter

Counts everything DELETE on this path would untag or remove: the learning records, events, quizzes, courses and certification types tagged with the subject, the proof rules scoped to it, and its narrower subjects. Nothing is changed. Requires subjects:delete — a grant separate from subjects:write, which only archives.

Parameters

Name	In	Type	Required	Description
subject_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	What the deletion would take with it.	DeletionImpact
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this subject but does not hold subjects:delete over it.	ErrorResponse
404	No visible subject matter has that id or slug.	ErrorResponse
500	The database could not be read.	ErrorResponse

DELETE/api/subjects/{subject_id}/permanent-deletion Bearer token

Permanently delete a subject matter

Hard-deletes the subject — unlike DELETE /subjects/{subject_id}, which only archives. Every learning record, event, quiz, SCORM course, external course and certification type loses the tag (the rows themselves stay), so hours and record counts filed under it stop satisfying any certification rule on this subject; proof rules scoped to the subject alone are deleted, and hierarchy edges go. Irreversible. Preview the cost with GET first. Requires subjects:delete — a grant separate from subjects:write, which only archives.

Parameters

Name	In	Type	Required	Description
subject_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
204	The subject matter and its tags are gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this subject but does not hold subjects:delete over it.	ErrorResponse
404	No visible subject matter has that id or slug.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/subjects/{subject_id} Bearer token

Get a subject matter

Returns one subject matter, by UUID id or by slug resolved within ?org=. Requires subjects:read over its owner.

Parameters

Name	In	Type	Required	Description
subject_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 subject matter.	SubjectMatter
401	The access token is missing or invalid.	ErrorResponse
404	No visible subject matter has that id or slug.	ErrorResponse
500	The database could not be read.	ErrorResponse

PATCH/api/subjects/{subject_id} Bearer token

Update a subject matter

Changes a subject matter's slug, name or description. Requires subjects:write.

Parameters

Name	In	Type	Required	Description
subject_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/jsonrequiredUpdateSubjectMatterRequest

Field	Type	Required	Description
slug	string	no	1–100 characters · matches ^[a-z0-9]+(-[a-z0-9]+)*$
name	string	no	1–200 characters
description	string \| null	no	Send null to clear the description. at most 2000 characters

Field

Type

Required

Description

slug

string

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

name

string

1–200 characters

description

string | null

Send null to clear the description.

at most 2000 characters

Responses

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

DELETE/api/subjects/{subject_id} Bearer token

Archive a subject matter

Soft-deletes a subject matter by setting archived_at; records filed under it keep their tags. Requires subjects:write.

Parameters

Name	In	Type	Required	Description
subject_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 subject matter.	SubjectMatter
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this subject but does not hold subjects:write over it.	ErrorResponse
404	No visible subject matter has that id or slug.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/subjects/{subject_id}/hierarchy Bearer token

Read a subject matter's place in the hierarchy

Returns the subject with the broader subjects it sits beneath (its parents, and every ancestor above them) and the narrower subjects directly beneath it. Requires subjects:read over the subject's owner; the related subjects are named regardless of their own owners.

Parameters

Name	In	Type	Required	Description
subject_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 subject and its parents, ancestors and children.	SubjectMatterHierarchy
401	The access token is missing or invalid.	ErrorResponse
404	No visible subject matter has that id or slug.	ErrorResponse
500	The database could not be read.	ErrorResponse

PUT/api/subjects/{subject_id}/parents Bearer token

Set a subject matter's parents

Replaces the broader subjects this one sits beneath — "arithmetic" under "mathematics". Parents must belong to the subject's own organization, and the hierarchy stays acyclic: a subject cannot be placed beneath itself or beneath one of its own descendants. Requires subjects:write over the subject's owner.

Parameters

Name	In	Type	Required	Description
subject_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/jsonrequiredSetSubjectMatterParentsRequest

Field	Type	Required	Description
parent_ids	array of string (uuid)	yes	Replaces the subject's parents. Each must be a subject of the same organization, and none may be the subject itself or one already beneath it. at most 50 items

Field

Type

Required

Description

parent_ids

array of string (uuid)

yes

Replaces the subject's parents. Each must be a subject of the same organization, and none may be the subject itself or one already beneath it.

at most 50 items

Responses

Status	Description	Body
200	The subject with its new parents.	SubjectMatterHierarchy
400	The body failed validation, or a parent is the subject itself or one beneath it.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this subject but does not hold subjects:write over it.	ErrorResponse
404	No visible subject matter has that id or slug, or a parent is not in its organization.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse