Skip to content
plugboard.appRequest a demo

Build on it

The REST API

Needs module.integrations. Authenticated with an API key.

GET https://helpdesk.yourschool.org/api/v1/ping
x-api-key: pk_...

Every REST request carries the key in x-api-key. There is no session and no cookie.

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.

MethodPathReturnsNeeds
GET/api/v1/pingA liveness response, and confirmation the key worksAny valid key
GET/api/v1/devicesDevicesdevice.view, with Stocktake (module.assets) on
GET/api/v1/submissionsSubmissionsrepair.view, with Repairs (module.repairs) on

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.

With API and webhooks (module.integrations) off, every request gets a 403 saying “The Integrations module is disabled for this school”. An endpoint whose own module is off gets a 403 naming that module, for example “The Stocktake module is disabled for this school”.

From 0.20.0, clients of the authenticated console API should page loan reads:

HTTP
GET /api/loans/inventory?page=1&pageSize=50

This route uses the console’s session/JWT authentication, module.loans and loan.view. It is separate from the /api/v1 API-key surface above. Route names in the upgrade notes omit the /api prefix.

The response contains loans, total, page, pageSize and summary. total counts matching records. summary describes the whole authorised pool, independent of the filters, with total, available, issued, overdue, withoutDueDate and nextNumber.

ParameterMeaning
pagePositive integer, default 1, maximum 1000000
pageSizeInteger from 1 to 100, default 50
statusAVAILABLE, ISSUED or UNAVAILABLE
groupId, kind, userGroup, holderIdExact filters; kind is LAPTOP or IPAD
qSerial, holder or group-name search, or an exact integer loan number
overdueOnly true enables the overdue filter, which selects issued loans

Omit unused filters. Continue paging until all total matching records have been read, and apply updated filters to a new first-page request. The legacy GET /api/loans array response remains available for at most 1,000 matching records; a larger result returns HTTP 400 with a pagination instruction. It does not silently truncate. Update clients before relying on a larger register.

Every request runs inside the institution the key belongs to. No parameter reaches another one.

For local development, or a client that reaches the API by an address that does not identify the institution, send an x-tenant-slug header.

Standard HTTP status codes.

CodeMeans
401Missing or invalid key
403The key lacks the permission for this endpoint
404The module is not enabled, or the record does not exist
429Rate limited

A 404 on an endpoint you expect to exist usually means the module is off. Check Settings, Modules.

Requests are rate limited by the deployment’s endpoint throttling policy. Back off on a 429 rather than retrying immediately.

The REST action surface uses the same permission- and module-filtered catalogue as MCP:

MethodPathPurpose
GET/api/v1/actionsAvailable names and JSON input schemas
GET/api/v1/actions/openapi.jsonOpenAPI 3.1 document filtered for this key
POST/api/v1/actions/:nameInvoke a listed action with its JSON input

Use the x-api-key header. This surface permits 60 requests per minute under the endpoint throttling policy. Unavailable, forbidden and unknown actions all return 404; invalid action input returns 400. The verified key is the actor for mutations. Privileged identity actions are excluded from the tool registry and cannot be invoked through REST or MCP.

The REST surface is small. The larger interface is the MCP server, which exposes the whole desk tool catalogue over JSON-RPC with the same key and the same permission checks. The catalogue includes:

Tool
people.search, people.profileFind somebody, see their loans, devices and submissions
loans.list, loans.issue, loans.returnThe loan desk
submissions.list, submissions.get, submissions.create, submissions.assignDevice repairs: work lodged against a serial number
tickets.list, tickets.get, tickets.byNumberThe service-desk queue. Read only: nothing here changes a ticket
devices.searchThe asset register
costs.breakdownSpend by type, coverage or period

MCP is built for AI clients, but it is ordinary JSON-RPC over HTTP, so anything that can make an HTTP request can use it.

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.

Operations that emit audit events use the key’s actor identity. Not every route emits an event; using a key does not add auditing to an otherwise unaudited operation. See current coverage.

The path carries the version. A breaking change means a new version rather than a change under /v1.