job-aids

20 endpoints.

GET/api/job-aids/available Bearer token

List the job aids that reach the caller

Lists the live job aids the caller may read, each with their own view standing: organization-owned aids of every organization whose directory names them, department-owned aids of departments they hold a role in (or one nested beneath), and trainers-only aids their job-aids:read covers. Needs no permission grant for the first two: the aid's audience is the authorization.

Responses

Status	Description	Body
200	The caller's job aids.	AvailableJobAidList
401	The access token is missing or invalid.	ErrorResponse
500	The database could not be read.	ErrorResponse

GET/api/job-aids Bearer token

List job aids

Lists the job aids the caller's job-aids:read scope covers, newest first, optionally filtered to one organization or one owning department within it. Readers list what reaches them through GET /job-aids/available 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.

Responses

Status	Description	Body
200	The visible job aids.	JobAidList
400	The department filter was given without an org filter.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
404	No visible organization has that id or slug, or the department is not one of the organization's own.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/job-aids Bearer token

Create a job aid

Creates a job aid — owned by the organization, or by the owning department named within it, tagged with the subjects named, and open to trainees unless audience says trainers only. Files are attached afterwards through POST /job-aids/{job_aid_id}/attachment-uploads and /attachments, links through POST /job-aids/{job_aid_id}/links. Requires job-aids:write over that owner.

Request body

application/jsonrequiredCreateJobAidRequest

Field	Type	Required	Description
org	string	yes	Organization UUID id or slug the job aid belongs to. at least 1 character
department	string	no	UUID id or slug of the owning department within the organization; omit for an aid owned by the organization directly. Ownership scopes administration and limits reading the aid to the department's role holders. at least 1 character
title	string	yes	1–200 characters
description	string	no	Omit or send empty for no summary. at most 2000 characters
body_markdown	string	no	Omit or send empty for no body; files are attached afterwards. at most 200000 characters
audience	string	no	Defaults to trainees: open to everyone the aid's ownership admits. one of "trainees" \| "trainers"
subject_matter_ids	array of string (uuid)	no	Subjects of the aid's organization to tag it with. Omit for an untagged aid. at most 50 items

Responses

Status	Description	Body
201	The created job aid.	JobAid
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the intended owner.	ErrorResponse
404	No visible organization has that id or slug, or the department or a subject matter is not the organization's own.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/job-aids/{job_aid_id}/attachments/{attachment_id}/download Bearer token

Get a download URL for a job aid attachment

Issues a short-lived presigned GET for the private attachment. Readable by anyone the job aid reaches while it is live, and by holders of job-aids:read over its owner. Issuing the URL records a view of this file.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.
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 six hours — long enough to play a video through.	DownloadTicket
401	The access token is missing or invalid.	ErrorResponse
404	No visible job aid 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

PUT/api/job-aids/{job_aid_id}/attachments/{attachment_id}/file Bearer token

Replace a job aid attachment's file

Points the attachment at a newly uploaded file — a pathname an upload ticket was issued for, after PUTting the file there — keeping its id, label, slot and display choice, so everything that names the attachment still does. The previous file is deleted best-effort; the content type is read back from the store, never from the request. requires_recertification says whether the job aid must be read again by everyone certified on it (a compliance change) or the reads on record still count (a typo fix). Requires job-aids:write.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.

Request body

application/jsonrequiredReplaceRecertifiableAttachmentFileRequest

Field	Type	Required	Description
pathname	string	yes	The pathname an upload ticket was issued for, after PUTting the new file there. at least 1 character
file_name	string	yes	1–300 characters
requires_recertification	boolean	yes	True when the new file must be read again by everyone — a compliance change, say: the parent's recertification cutoff moves to now, so opens recorded before the replacement stop satisfying its proof rule. False for a minor fix — a typo, a stale date — that leaves every earlier open standing.

Field

Type

Required

Description

pathname

string

yes

The pathname an upload ticket was issued for, after PUTting the new file there.

at least 1 character

file_name

string

yes

1–300 characters

requires_recertification

boolean

yes

True when the new file must be read again by everyone — a compliance change, say: the parent's recertification cutoff moves to now, so opens recorded before the replacement stop satisfying its proof rule. False for a minor fix — a typo, a stale date — that leaves every earlier open standing.

Responses

Status	Description	Body
200	The attachment, now serving the new file.	DescriptionAttachment
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 job aid but lacks job-aids:write.	ErrorResponse
404	No visible job aid matches the path, or it has no such attachment.	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

POST/api/job-aids/{job_aid_id}/attachment-uploads Bearer token

Request an upload URL for a job aid attachment

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

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

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 job aid but lacks job-aids:write.	ErrorResponse
404	No visible job aid 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/job-aids/{job_aid_id}/attachments Bearer token

Attach an uploaded file to a job aid

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 job-aids:write.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Request body

application/jsonrequiredCreateDescriptionAttachmentRequest

Field	Type	Required	Description
pathname	string	yes	The pathname an upload ticket was issued for, after PUTting the file. at least 1 character
file_name	string	yes	1–300 characters
label	string	no	Omit or send empty to show the file name instead. at most 200 characters
prefer_inline_display	boolean	no	Omit to show the file on the page where its type allows it. Send false for a file meant to be downloaded and worked on locally — a blank form, a spreadsheet — so it renders as a download instead of an inline viewer.

Responses

Status	Description	Body
201	The created attachment.	DescriptionAttachment
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 job aid but lacks job-aids:write.	ErrorResponse
404	No visible job aid 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/job-aids/{job_aid_id}/attachments/{attachment_id} Bearer token

Relabel or reorder a job aid attachment

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

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.
attachment_id	path	string (uuid)	yes	UUID id of the attachment.

Request body

application/jsonrequiredUpdateDescriptionAttachmentRequest

Field	Type	Required	Description
label	string \| null	no	Send null or empty to clear the label back to the file name. at most 200 characters
position	integer	no	New slot in the authored order. minimum 0
prefer_inline_display	boolean	no	Switches the file between showing on the page and being offered as a download only.

Field

Type

Required

Description

label

string | null

Send null or empty to clear the label back to the file name.

at most 200 characters

position

integer

New slot in the authored order.

minimum 0

prefer_inline_display

boolean

Switches the file between showing on the page and being offered as a download only.

Responses

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

DELETE/api/job-aids/{job_aid_id}/attachments/{attachment_id} Bearer token

Delete a job aid attachment

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

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.
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 job aid but lacks job-aids:write.	ErrorResponse
404	No visible job aid matches the path, or it has no such attachment.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/job-aids/{job_aid_id}/links Bearer token

Add a link to a job aid

Adds one http(s) link at the end of the authored order the aid's files and links share. Requires job-aids:write over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Request body

application/jsonrequiredCreateJobAidLinkRequest

Field	Type	Required	Description
url	string (uri)	yes	Where the link points; http and https only. 1–2000 characters
label	string	no	Omit or send empty to show the URL itself. at most 200 characters

Field

Type

Required

Description

url

string (uri)

yes

Where the link points; http and https only.

1–2000 characters

label

string

Omit or send empty to show the URL itself.

at most 200 characters

Responses

Status	Description	Body
201	The created link.	JobAidLink
400	The request body failed validation, or the URL is not http(s).	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the aid's owner.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

PATCH/api/job-aids/{job_aid_id}/links/{link_id} Bearer token

Edit or reorder a job aid link

Changes the link's destination, its label (null or empty clears it back to the URL) or its slot in the authored order the aid's files share. Requires job-aids:write over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.
link_id	path	string (uuid)	yes	UUID id of the link.

Request body

application/jsonrequiredUpdateJobAidLinkRequest

Field	Type	Required	Description
url	string (uri)	no	Where the link points; http and https only. 1–2000 characters
label	string \| null	no	Send null or empty to clear the label back to the URL. at most 200 characters
position	integer	no	New slot in the authored order the aid's files share. minimum 0

Field

Type

Required

Description

url

string (uri)

Where the link points; http and https only.

1–2000 characters

label

string | null

Send null or empty to clear the label back to the URL.

at most 200 characters

position

integer

New slot in the authored order the aid's files share.

minimum 0

Responses

Status	Description	Body
200	The updated link.	JobAidLink
400	The request body failed validation, or the URL is not http(s).	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the aid's owner.	ErrorResponse
404	No visible job aid has that id, or it has no such link.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/job-aids/{job_aid_id}/links/{link_id} Bearer token

Delete a job aid link

Removes the link from the aid; what it pointed at is untouched. Requires job-aids:write over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.
link_id	path	string (uuid)	yes	UUID id of the link.

Responses

Status	Description	Body
204	The link is gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the aid's owner.	ErrorResponse
404	No visible job aid has that id, or it has no such link.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

PUT/api/job-aids/{job_aid_id}/subjects Bearer token

Replace a job aid's subject tags

Sets the complete set of subjects the job aid is filed under. Subjects of the aid's own organization only. Requires job-aids:write over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Request body

application/jsonrequiredSetJobAidSubjectsRequest

Field	Type	Required	Description
subject_matter_ids	array of string (uuid)	yes	Replaces the job aid's subject-matter tags. at most 50 items

Field

Type

Required

Description

subject_matter_ids

array of string (uuid)

yes

Replaces the job aid's subject-matter tags.

at most 50 items

Responses

Status	Description	Body
200	The aid's subjects after the change, alphabetically.	array of JobAidSubject
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the aid's owner.	ErrorResponse
404	No visible job aid has that id, or a subject is not the organization's own.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/job-aids/{job_aid_id}/views Bearer token

Record that the caller opened a job aid

Records one open of the aid's page by the caller — what the aid's page does on every load, and what a job_aid_viewed proof rule counts. Never deduplicated: a refresh is another view. Opens of individual files are recorded by their download route instead. Allowed to anyone the aid reaches, and to job-aids:read holders over its owner; administrators' opens count like everyone else's.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Responses

Status	Description	Body
201	The recorded view.	JobAidView
401	The access token is missing or invalid.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/job-aids/{job_aid_id}/analytics Bearer token

Read who has viewed a job aid

Every recorded open of the aid, folded per person: how many times each opened it and when first and last, with the totals. Requires job-aids:read over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Responses

Status	Description	Body
200	The aid's view analytics.	JobAidAnalytics
401	The access token is missing or invalid.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

GET/api/job-aids/{job_aid_id}/permanent-deletion Bearer token

Preview permanently deleting a job aid

Counts everything DELETE on this path would remove: the proof rules requiring that the aid be viewed, every recorded view, the files, and the pathway placements. Nothing is changed. Requires job-aids:delete over the aid's owner — a grant separate from job-aids:write, which only archives.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

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 does not hold job-aids:delete over the aid's owner.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

DELETE/api/job-aids/{job_aid_id}/permanent-deletion Bearer token

Permanently delete a job aid

Hard-deletes the job aid — unlike archiving, which only hides it. The job_aid_viewed rules pointing at it are deleted (so those certifications no longer require it), every recorded view goes, the pathway placements are removed, and the files are deleted from the store. Irreversible. Preview the cost with GET first. Requires job-aids:delete over the aid's owner — a grant separate from job-aids:write, which only archives.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Responses

Status	Description	Body
204	The job aid, its rules, views, placements and files are gone.	—
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:delete over the aid's owner.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/job-aids/{job_aid_id}/duplicate Bearer token

Duplicate a job aid

Creates a copy of a job aid: its summary, markdown body, audience, subject tags, links, and files — each file copied in the store, so deleting either aid later leaves the other's files alone. Views, the recertification cutoff, pathway placements and the proof rules naming the original stay with it, and the copy starts unarchived. The copy is titled after the original with " (copy)" appended unless a title is given. Requires job-aids:write over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Request body

application/jsonoptionalDuplicateJobAidRequest

Field	Type	Required	Description
title	string	no	The copy's title; omit for the original's with " (copy)" appended. 1–200 characters

Field

Type

Required

Description

title

string

The copy's title; omit for the original's with " (copy)" appended.

1–200 characters

Responses

Status	Description	Body
201	The copy, with its subjects, files and links.	JobAid
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the aid's owner.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be reached, or the write or a file copy failed.	ErrorResponse
503	The aid has files and file storage is not configured here.	ErrorResponse

GET/api/job-aids/{job_aid_id} Bearer token

Read one job aid

Reads one job aid with its subjects, files and links. Readable by anyone the aid reaches — its audience, while it is live — and by holders of job-aids:read over its owner, archived or not. Reading here records no view; POST /job-aids/{job_aid_id}/views does.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Responses

Status	Description	Body
200	The job aid.	JobAid
401	The access token is missing or invalid.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

PATCH/api/job-aids/{job_aid_id} Bearer token

Edit or archive a job aid

Changes a job aid's title, summary, markdown body or audience (trainees, or trainers only), or archives/restores it. The subject tags are replaced as a set through PUT /job-aids/{job_aid_id}/subjects; the files through the attachment routes, the links through /job-aids/{job_aid_id}/links. Views are history, so there is no delete here; archiving hides the aid from its audience. require_recertification: true marks the edit as one everyone certified on the aid must read again — opens recorded before it stop satisfying job_aid_viewed rules. Requires job-aids:write over the aid's owner.

Parameters

Name	In	Type	Required	Description
job_aid_id	path	string (uuid)	yes	UUID id of the job aid.

Request body

application/jsonrequiredUpdateJobAidRequest

Field	Type	Required	Description
title	string	no	1–200 characters
description	string \| null	no	Send null or empty to clear the summary. at most 2000 characters
body_markdown	string \| null	no	Send null or empty to clear the body. at most 200000 characters
audience	string	no	Whom the job aid is for. trainees: everyone its ownership admits — every member for an organization-owned aid, the owning department's role holders for a department-owned one — trainers included. trainers: only holders of job-aids:read over the aid's owner, for facilitator guides and the like; the aid is absent from everyone else's list. one of "trainees" \| "trainers"
archived	boolean	no	True archives the job aid (hidden from its audience); false restores it.
require_recertification	boolean	no	True moves the aid's recertification cutoff to now: opens recorded before this edit stop satisfying job_aid_viewed rules, so everyone certified on the aid must read it again. For a rewrite that changes what readers must know, not for a typo. Omit or send false to leave every earlier open standing.

Responses

Status	Description	Body
200	The updated job aid.	JobAid
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller does not hold job-aids:write over the aid's owner.	ErrorResponse
404	No visible job aid has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse