JobAid
A request or response body; the type column links to the schemas it refers to.
JobAid
| Field | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | yes | — |
| organization_id | string (uuid) | yes | — |
| owner_department_id | string (uuid) | null | yes | Owning department within the organization; null = owned by the organization directly. Scopes which job-aids:read/write grants cover the aid, and narrows who may read it: an organization-owned aid reaches every member, a department-owned one only the owning department's role holders. |
| title | string | yes | — |
| description | string | null | yes | One-line summary shown in listings. |
| body_markdown | string | null | yes | Narrative markdown rendered on the aid's page; never parsed. A job aid may be this body alone, files alone, or both. |
| audience | string | yes | 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" |
| subjects | array of JobAidSubject | yes | The subject matters the aid is tagged with, alphabetically. |
| attachments | array of DescriptionAttachment | yes | Every file of the aid, in authored order. The bytes are fetched through GET /job-aids/{job_aid_id}/attachments/{attachment_id}/download, which also records a view of that file. |
| links | array of JobAidLink | yes | Every link of the aid, in authored order. Files and links share one `position` sequence, so a reader's list interleaves the two by it; opening a link records no view, since it leaves this deployment. |
| recertification_required_at | string (date-time) | null | yes | The recertification cutoff: opens of the aid's page before this instant no longer satisfy job_aid_viewed rules, so certified readers must open it again. Set when a file is replaced, or the aid edited, with recertification required; null when every open on record still counts. |
| created_by | string | null | yes | — |
| created_at | string (date-time) | yes | — |
| archived_at | string (date-time) | null | yes | An archived job aid is hidden from its audience; its views stay on record. |
{
"id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
"organization_id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
"owner_department_id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
"title": "string",
"description": "string",
"body_markdown": "string",
"audience": "trainees",
"subjects": [
{
"id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
"slug": "string",
"name": "string"
}
],
"attachments": [
{
"id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
"file_name": "string",
"content_type": "string",
"label": "string",
"position": 0,
"prefer_inline_display": true
}
],
"links": [
{
"id": "1b671a64-40d5-491e-99b0-da01ff1f3341",
"url": "https://www.osha.gov/powered-industrial-trucks",
"label": "string",
"position": 0
}
],
"recertification_required_at": "2026-01-01T00:00:00.000Z",
"created_by": "string",
"created_at": "2026-01-01T00:00:00.000Z",
"archived_at": "2026-01-01T00:00:00.000Z"
}