Botree LRS API

Describe the presented access token

Example protected endpoint: echoes back the claims of the bearer token after it has been validated against the OIDC provider.

List organizations

Lists every organization in the directory, archived ones included. Requires a valid access token.

Create an organization

Creates a new top-level organization. Requires a superuser's access token.

Update an organization

Changes an organization's slug, name or description; omitted fields keep their values. Requires a superuser's access token, like creating one.

Create a department

Creates a department in an organization, optionally nested under a parent department in the same organization. Requires a superuser's access token, or one whose subject holds the directory:write permission in a scope covering the parent — the organization for a top-level department, the parent department for a nested one.

Update a department

Changes a department's slug, name or description, or moves it under another parent in the same organization; omitted fields keep their values. Requires a superuser's access token, or one whose subject holds the directory:write permission in a scope covering the department — and, when moving it, the new parent too.

Create a department role

Creates a role in a department of an organization, with the permission strings it grants. Requires a superuser's access token, or one whose subject holds the directory:write permission in a scope covering the department.

Update a department role

Changes a role's slug, name or description, or replaces the permission set it grants; omitted fields keep their values. Requires a superuser's access token, or one whose subject holds the directory:write permission in a scope covering the department.

Import directory members from a CSV file

Adds every row of an uploaded CSV file to the organization's user directory in one request. The file needs a header row naming a user id, name and email column; rows whose subject is already in the directory are skipped rather than overwritten, so an import can safely be re-run. A file with any invalid row imports nothing and reports the problems, so a corrected file can simply be uploaded again. Requires a superuser's access token.

List an organization's user directory

Lists every member of the organization's user directory, named members first, each with the number of roles they currently hold. Requires a valid access token.

Add a user to the directory

Adds a user to the organization's directory: an existing account by user_id, or a pre-provisioned identity by provider_id + subject — the account is created on the spot when that identity is new. Requires a superuser's access token.

Get a directory member

Returns one member of the organization's directory, with every role grant they hold there — expired ones included. Requires a valid access token.

Remove a user from the directory

Removes a member from the organization's directory, revoking every role they hold there. The account itself (and its history) remains. Requires a superuser's access token.

List a directory member's roles

Lists every role grant a member holds in the organization, expired ones included — check expires_at. Requires a valid access token.

Assign a role to a directory member

Grants a member one of the roles defined by a department of the organization, open-ended or until an expiry. Requires a superuser's access token.

Update a directory member's role grant

Changes when a member's grant expires — renewing a lapsed one, scheduling an end, or making it open-ended with null. Requires a superuser's access token.

Revoke a directory member's role

Removes one of a member's role grants. Requires a superuser's access token.

List a role's reporting lines

Lists the roles managing this role and the roles it manages. Holders of a manager role (or of any role above it in the chain) may approve or reject the pending learning-record submissions of the subordinate role's holders.

Make a role a manager of this role

Adds a reporting line: the named role becomes a manager of the role in the path. Both roles must belong to the same organization; a line that would close a cycle is refused. Requires a superuser's access token, or one whose user holds directory:write in a scope covering both roles' departments.

Remove a manager from this role

Removes the reporting line between this role and the named manager role. Requires a superuser's access token, or one whose user holds directory:write in a scope covering both roles' departments.

Get an organization

Returns one organization and every department inside it. Requires a valid access token.

Get a department

Returns one department of an organization. Requires a valid access token.

List a department's roles

Lists the roles a department defines, with the permissions each grants and how many users currently hold it. Requires a valid access token.

Get a department role

Returns one role of a department, with the permissions it grants and how many users currently hold it. Requires a valid access token.

List the sign-in providers

Every registered OpenID Connect provider, disabled ones included. Rows name the env vars their secrets live in; the secrets themselves are never served.

Register a sign-in provider

Registers an OpenID Connect provider whose sign-ins and access tokens this deployment accepts. Secrets stay in the environment: the row names the variables to read. Requires a superuser's access token.

Read one sign-in provider

Update a sign-in provider

Changes a provider's settings; omitted fields keep their values. Disabling a provider stops its sign-ins and token verification while keeping its identities. Requires a superuser's access token.

Delete a sign-in provider

Removes a provider nothing references. A provider whose identities still exist cannot be deleted — disable it, or detach the identities first. Requires a superuser's access token.

Read the caller's account

The account the presented token resolves to: canonical profile and sign-in methods. Accounts come into existence on first contact, so this always answers for a valid token.

Unlink one of the caller's sign-in methods

Detaches a sign-in method from the caller's own account. The last method cannot be unlinked — that would lock the account out; ask a superuser to detach it deliberately.

Update an account's profile

Sets the account's display name (null clears it); omitted fields keep their values. The name is the canonical profile the app shows everywhere, and a later sign-in whose ID token carries a name claim refreshes it again. A merged (tombstoned) account cannot be edited — its survivor holds the profile. Requires a superuser's access token.

List an account's sign-in methods

Every identity attached to the account. Requires a superuser's access token.

Attach a sign-in method to an account

Links a (provider, subject) pair to the account — the administrative side of identity linking, for provider migrations and rescues. An identity already attached to a *different* account is refused: merge or detach it first. Requires a superuser's access token.

Detach a sign-in method from an account

Removes one identity from the account. Detaching the *last* one locks the account out of signing in (its history remains) and is refused unless `force=true` — the deliberate offboarding or compromised-credential case. Requires a superuser's access token.

Merge an account into another

Absorbs the account at {user_id} into into_user_id: identities move over, every reference is repointed at the survivor (redundant memberships, grants and duplicates resolve in the survivor's favour), and the absorbed account is tombstoned. The fix for the duplicate a first sign-in creates before its identity is linked. One transaction, irreversible. Requires a superuser's access 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.

Create a subject matter

Creates a subject matter owned by an organization, or by one department within it. Requires subjects:write over the owner.

Get a subject matter

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

Update a subject matter

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

Archive a subject matter

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

Submit a record and its evidence in one request

Creates a learning record together with its evidence rows, atomically. The record and evidence parts are JSON-encoded (shaped like CreateLearningRecordRequest and an array of CreateSupportingEvidenceRequest); the bytes of at most one file evidence entry travel in the file part, so no separate upload round trip is needed. Requires records:write over the owner — or none at all for a pending submission about yourself, which a manager then approves.

List learning records

Lists the learning records the caller can read — their records:read scope, their own records, and the pending submissions of learners in their manager chain — newest first, with cursor pagination.

Create a learning record

Creates a record owned by an organization or one of its departments, optionally tagged with subjects. Requires records:write over the owner. Omit learner_user_id to record about yourself.

Get a learning record

Returns one record with its subjects. Requires records:read over its owner, being its learner, or — while it is pending — being in its learner's manager chain.

Update a learning record

Changes a record's fields, and replaces its subject set when subject_matter_ids is present. Requires records:write.

Archive a learning record

Soft-deletes a record by setting archived_at; its evidence and blobs are kept, so it can be un-archived. Requires records:write.

Approve a pending learning record

Moves a learner's pending submission into the real history — completed by default, or in_progress — and stamps who approved it and when. Requires records:write over the record's owner, or a role in the learner's manager chain; a learner cannot approve their own submission.

Reject a pending learning record

Sends a learner's pending submission back with a note saying what to fix, and stamps who rejected it and when. The learner may edit the record and resubmit it to pending, which clears the rejection. Requires records:write over the record's owner, or a role in the learner's manager chain; a learner cannot reject their own submission.

List a record's evidence

Lists every evidence row of a record, newest first. Requires records:read over the record, being its learner, or — while it is pending — being in its learner's manager chain.

Add evidence to a record

Attaches one measurement to a record. For file evidence, upload the file first via the uploads endpoint and pass the resulting pathname here. Requires records:write.

Request an upload URL for file evidence

Issues a presigned URL to PUT one file straight to private blob storage, scoped to this record, the declared content type and a 25 MB ceiling. Requires records:write.

Update an evidence row

Changes an evidence row's label or replaces its payload (same evidence_type; not for files). Requires records:write over the owning record.

Delete an evidence row

Removes an evidence row for good — a mistaken measurement is deleted, not archived — and deletes its blob, if it has one. Requires records:write over the owning record.

Get a download URL for file evidence

Issues a short-lived presigned GET for the evidence row's private blob, after re-checking read permission. Requires records:read over the owning record, being its learner, or — while the record is pending — being in its learner's manager chain.

Evaluate certification status

Evaluates every certification requirement of a user: the types their unexpired role grants require, the current award, the due date, and per-rule progress since the current award. Any bearer user may read their own status; reading another user's requires certifications:read, and returns only types in the caller's scope.

Claim an automatic certification

Awards the caller a certification of an automatic-mode type they are required to hold, after the server re-validates that every proof rule is satisfied. Answers 409 when a rule is not met, or when the current award changed under the claim (retry after re-reading status).

Request a certification

Files a request for an approval-mode type the caller is required to hold, to be decided by a holder of certifications:write. One pending request per user and type.

Withdraw an own request

Withdraws the caller's own still-pending request.

Approve a request

Approves a pending request: inserts the award and stamps the request in one transaction. The deciding human is the authority — rules are not re-checked. Requires certifications:write over the type's owner.

Reject a request

Rejects a pending request. Requires certifications:write over the type's owner.

List certification requests

The approvals queue: requests whose certification type the caller holds certifications:write over, newest first, with cursor pagination. Defaults to pending requests only.

Grant a certification directly

Awards a certification to a user without a request — for paper history, external audits, or admin discretion. `awarded_at` may be backdated; the recert clock counts from it. Requires certifications:write over the type's owner.

List a type's awards

Lists the award events of one certification type, newest first, revoked ones included. Requires certifications:read over the type's owner.

Revoke an award

Revokes one award. The row stays as history; the user's status reverts to outstanding (or to their previous unrevoked award). Requires certifications:write over the type's owner.

List a type's initial due dates

Lists the admin-set per-person initial due dates of one certification type, soonest first. Requires certifications:read over the type's owner.

Set a member's initial due date

Sets (or replaces) when one organization member's initial certification falls due, overriding any role-level initial due date. Requires certifications:write over the type's owner. The member must be in the organization's directory.

Clear a member's initial due date

Clears a member's per-person initial due date; their requirement falls back to the role-level initial due date, or shows "No due date set" when no role sets one. Requires certifications:write over the type's owner.

List a rule's sign-offs

Lists the sign-offs recorded against one rule, newest first, optionally for one user. Requires certifications:read over the type's owner.

Record a sign-off

Records that a user satisfies one manual_sign_off rule. `signed_off_at` may be backdated; a renewal needs a sign-off after the current award. Requires certifications:write over the type's owner.

Delete a sign-off

Hard-deletes a mistaken sign-off, the way evidence is deleted. Requires certifications:write over the type's owner.

List certification types

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

Create a certification type

Creates a certification type owned by an organization, or by one department within it, tied to a subject matter of the same organization. Requires certifications:write over the owner.

Request an upload URL for a certification type attachment

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

Attach an uploaded file to a certification type

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.

Get a download URL for a certification type attachment

Issues a short-lived presigned GET for the private attachment. Readable by anyone an unexpired role grant requires the type of, and by holders of certifications:read over its owner.

Relabel or reorder a certification type attachment

Changes the attachment's label (null or empty clears it back to the file name) or its slot in the authored order. Requires certifications:write.

Delete a certification type attachment

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

Get a certification type

Returns one certification type with its proof rules, by UUID id or by slug resolved within ?org=. Requires certifications:read over its owner.

Update a certification type

Changes a certification type's slug, name, description or awarding mode. The subject matter is immutable. Requires certifications:write.

Archive a certification type

Soft-deletes a certification type by setting archived_at. Archived types stop being evaluated as requirements; awards already given stay readable. Requires certifications:write.

Add a proof rule

Adds one proof rule to a certification type; all rules of a type must be satisfied at once for it to be awardable. Note that date_range evidence counts its full elapsed wall-clock time towards subject_hours rules, so size thresholds accordingly. Requires certifications:write over the type's owner.

Update a proof rule

Changes a rule's label or configuration. The rule kind is immutable — delete and recreate a rule that should mean something else. Requires certifications:write over the type's owner. Progress is recomputed retroactively; award history is unaffected.

Delete a proof rule

Hard-deletes a rule. Every sign-off recorded against it cascades away with it. Requires certifications:write over the type's owner.

List a role's required certifications

Lists the certification types required of everyone holding one department role, with each link's recertification scheme. Requires certifications:read; links whose type is outside the caller's scope are absent.

Require a certification of a role

Links a certification type to a department role, with a recertification scheme and an optional role-level initial due date every holder inherits. Requires certifications:write over the type's owner. The type must belong to the role's organization.

Change a requirement's schedule

Replaces the recertification scheme and role-level initial due date of one role⇄type link; the scheme, its configuration and the date always travel together — an omitted initial_due_at clears the role-level deadline. Requires certifications:write over the type's owner. Members' due dates are recomputed at read time.

Stop requiring a certification of a role

Hard-deletes one role⇄type link, like revoking a role grant: the requirement simply stops appearing. Awards and history are untouched. Requires certifications:write over the type's owner.