API

What it is used for

The OpusHub API lets another system read data out of your organisation — checklists, active checklist progress, and Learning Centre assignments and completions. It's a read-only API, meant for connecting OpusHub to reporting tools, dashboards, or other internal systems.

Who can access it

Admins create and manage API keys, from Settings > Integrations. Any system holding a valid key can read the data covered by that key's scopes — treat a key like a password.

Authentication

Every request must include the API key in the Authorization header:

Authorization: Bearer oh_live_xxxxxxxxxxxxxxxxxxxxxxxx

A key only ever returns data for the organisation it was created in, and only for the scopes it was granted.

Scopes

Each API key is created with one or more scopes. A request fails with 403 Forbidden if the key doesn't have the scope an endpoint requires.

• checklists:read — checklist templates and their active progress.
• assignments:read — Learning Centre assignments and completions.

Available endpoints

All endpoints use app.opushub.io as the base URL and are prefixed with /api/v1, e.g. https://app.opushub.io/api/v1/checklists.

Method	Endpoint	Scope required	Returns
GET	/checklists	checklists:read	All checklist templates
GET	/checklists/:checklistId/progress	checklists:read	Progress runs for a checklist, with task completion counts
GET	/assignments	assignments:read	All Learning Centre assignments
GET	/assignments/:assignmentId/completions	assignments:read	Completion status for an assignment, per staff member

Example request:

curl https://app.opushub.io/api/v1/checklists \
  -H "Authorization: Bearer oh_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Every response follows the same shape:

{
  "success": true,
  "data": [ ... ]
}

Step-by-step

1. Go to Settings > Integrations.
2. In the API section, select Create API key.
3. Name the key so you'll recognise it later (e.g. the system that will use it).
4. Select the scopes the key needs — grant only what the integration actually uses.
5. Select Create. The full key is shown once — copy it now.
6. Store the key somewhere secure, such as the receiving system's secret manager.

Important notes

• The full key is only ever shown once, at creation. OpusHub only stores a hash of it — if you lose it, revoke it and create a new one.
• Revoking a key takes effect immediately; any system still using it starts getting 401 Unauthorized.
• Requests are rate-limited per key. A system making very frequent requests may see 429 Too Many Requests and should back off and retry.
• The API is read-only — it can't be used to create, edit or delete anything in OpusHub.

:::info Screenshot placeholder Add screenshot: Settings > Integrations > API section, showing the API key table and the Create API key dialog. :::