Tagaris REST API v1

The API lets external tools read and write assets, people and locations: a mobile app, reporting tools, or your own automation. It is versioned under /api/v1 and authenticated with a token you create in the app.

API access is included in the paid Team plans; see Licensing. On an unlicensed organisation, key creation is unavailable and requests are refused with 403.

Authentication

There are two kinds of key, both shown once (only a hash is stored, so a lost key cannot be recovered and must be replaced), and both with an expiry you choose when you create them (30, 90, 180 or 365 days, or never). An expired key returns 401.

• Personal keys (My account, API keys). Any user can create their own. A personal key acts as that user and is limited to what their role allows: a read-only viewer only ever gets a read key, and changes made with it are recorded as that person. If the user's role is later reduced or they leave the organisation, the key loses that access automatically.
• Organisation keys (Settings, API keys, an administrator only). For headless integrations. Not tied to a person; they act for the whole organisation with the scopes the admin grants.

The API can be turned off install-wide by the install owner (Application, API) or with the API_ENABLED=false environment variable. When it is off, every request returns 403 regardless of the key.

Send the token as a bearer token:

Authorization: Bearer tag_xxxxxxxxxxxxxxxxxxxxxxxx

A token has one org and a set of scopes:

• read: GET requests.
• write: POST, PATCH and DELETE. A read-only token gets 403 on writes.

All data is scoped to the token's org. A token cannot see or change another org's records.

Rate limit

Requests are limited to 120 per minute per token. Over the limit returns:

429 Too Many Requests
Retry-After: 60

Responses and errors

Successful reads and writes return { "data": ... }. List endpoints return { "data": [...], "total", "limit", "offset" }. Errors return { "error": "message" }, and validation errors add { "fieldErrors": { field: message } }.

Status	Meaning
200	OK
201	Created
400	Bad request (for example invalid JSON)
401	Missing or invalid token
403	Token lacks the required scope
404	Not found in your org
422	Validation failed
429	Rate limit exceeded

Assets

• GET /api/v1/assets?limit=&offset= list (limit up to 200, default 50).
• POST /api/v1/assets create. Body fields match the asset form: name (required), status, assetTag (optional, auto-generated when blank), categoryId, locationId, assignedToId, withAssignee (boolean: the asset is with its assignee rather than at a location, requires assignedToId and clears locationId), serialNumber, manufacturer, model, supplier, purchaseDate (YYYY-MM-DD), warrantyEnd, purchasePrice, ipAddress, hostname, macAddress, notes.
• GET /api/v1/assets/{id} fetch one.
• PATCH /api/v1/assets/{id} update. Send only the fields you want to change.
• DELETE /api/v1/assets/{id} delete.

Example:

curl -X POST https://your-host/api/v1/assets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Reception iPad","status":"IN_USE","manufacturer":"Apple"}'

People

• GET /api/v1/people
• POST /api/v1/people body: name (required), email (optional).
• GET /api/v1/people/{id}
• PATCH /api/v1/people/{id}
• DELETE /api/v1/people/{id}

Locations

• GET /api/v1/locations
• POST /api/v1/locations body: name (required), parentId (optional, must be another location in your org).
• GET /api/v1/locations/{id}
• PATCH /api/v1/locations/{id} a location cannot be its own parent.
• DELETE /api/v1/locations/{id}

Health check

GET /api/health needs no token and returns { "status": "ok", "db": "up" } when the app and database are reachable, or 503 with { "status": "degraded" } when the database is down. Use it for uptime monitoring.

Notes

• Relations are referenced by id (categoryId, locationId, assignedToId, parentId). Ids must belong to your org or the request returns 422.
• Deleting a category, location or person that assets reference sets that link to empty on those assets; the assets are kept.

Stability

v1 is stable: fields may be added, but existing fields and endpoints will not change shape or be removed under /api/v1. Any breaking change ships under a new version prefix, so a token-authed client can rely on v1.