The REST API

Needs module.integrations. Authenticated with an API key.

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

Authentication

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.

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.

Loan inventory for console clients

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

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.

Parameter	Meaning
page	Positive integer, default 1, maximum 1000000
pageSize	Integer from 1 to 100, default 50
status	AVAILABLE, ISSUED or UNAVAILABLE
groupId, kind, userGroup, holderId	Exact filters; kind is LAPTOP or IPAD
q	Serial, holder or group-name search, or an exact integer loan number
overdue	Only 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.

Tenancy

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.

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 usually means the module is off. Check Admin, Features.

Rate limiting

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

Action catalogue

The 0.12.0-rc.3 candidate REST action surface uses the same permission- and module-filtered catalogue as MCP. Check the deployment status:

Method	Path	Purpose
GET	/api/v1/actions	Available names and JSON input schemas
GET	/api/v1/actions/openapi.json	OpenAPI 3.1 document filtered for this key
POST	/api/v1/actions/:name	Invoke 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.

MCP clients

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:

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 built for AI clients, and it is ordinary JSON-RPC over HTTP, so anything that can make an HTTP request can use it.

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

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.

Versioning

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