The REST API
Needs module.integrations. Authenticated with an API
key.
GET https://helpdesk.yourschool.org/api/v1/pingAuthorization: Bearer pb_live_...Authentication
Section titled “Authentication”Every request carries the key as a bearer token. There is no session, no cookie and no ambient administrator.
The key’s scopes determine what it can do, using
the same permission set as roles. A key without device.view gets a 403 from the
devices endpoint.
Endpoints
Section titled “Endpoints”| Method | Path | Returns | Needs |
|---|---|---|---|
GET | /api/v1/ping | A liveness response, and confirmation the key works | Any valid key |
GET | /api/v1/devices | Devices | device.view |
GET | /api/v1/submissions | Submissions | repair.view |
ping is the first call to make with a new key. It confirms the key is valid and
the module is enabled, without needing any particular scope.
Tenancy
Section titled “Tenancy”Every request runs inside the key’s tenant. There is no cross-tenant access and no parameter that would grant it.
For local development or a client that reaches the API by an address that does
not identify the tenant, x-tenant-slug resolves it. See how it fits
together.
Errors
Section titled “Errors”Standard HTTP status codes.
| Code | Means |
|---|---|
| 401 | Missing or invalid key |
| 403 | The key lacks the permission for this endpoint |
| 404 | The module is not enabled, or the record does not exist |
| 429 | Rate limited |
A 404 on an endpoint you expect to exist is usually the module being off rather than a wrong path. Check Admin, Features.
Rate limiting
Section titled “Rate limiting”Requests are rate limited per key. Back off on a 429 rather than retrying immediately.
If you need more than three endpoints
Section titled “If you need more than three endpoints”The REST surface is deliberately small. The richer interface is the MCP server, which exposes the whole desk tool catalogue over JSON-RPC with the same key and the same permission checks:
| Tool | |
|---|---|
people.search, people.profile | Find somebody, see their loans, devices and submissions |
loans.list, loans.issue, loans.return | The loan desk |
submissions.list, submissions.get, submissions.create, submissions.assign | Tickets and repairs |
devices.search | The asset register |
costs.breakdown | Spend by type, coverage or period |
MCP is designed for AI clients but it is ordinary JSON-RPC over HTTP, so anything that can make an HTTP request can use it.
Reacting to changes
Section titled “Reacting to changes”Do not poll. Register an outbound webhook and receive signed callbacks when things happen.
For a browser client, the realtime event stream is the same events over server-sent events.
Auditing
Section titled “Auditing”Every action taken with a key is written to the audit log, attributed to the key. Nothing is exempt.
Versioning
Section titled “Versioning”The path carries the version. A breaking change means a new version rather than a
change under /v1.