API reference

The developer API lets an API key create, read, update and delete data in World Asset Register, within the scopes chosen when the key was created and the permissions of the member who created it. This page lists the endpoints an API key can reach, grouped by resource, plus the parts of the app that stay sign-in only. See Developer tools for how to create a key.

Authentication

Send your key on every request as a header:

x-api-key: ar_...

A key’s access is set in two steps. First, the scopes chosen when the key was created (below) determine which permissions it could hold at most. Second, that set is narrowed to whatever the creating member’s own role actually grants - a key can never reach more than its creator could. There is no separate read-only API mode: a scope that maps to a write permission (for example assets:write) lets the key write by API exactly as a member with that permission can in the app, provided the creator’s role grants it too. See Roles and permissions for how member permissions work, and Developer tools for the scope picker.

Scopes

Each key is created with one or more scopes, chosen when the key is made. Each scope maps to one or more of the permissions used elsewhere in the app - use this table to work back from an endpoint’s Permission column to the scope that grants it:

Scope	Grants	Description
`assets:read`	`assets.view`	View asset listings and details
`assets:write`	`assets.create`, `assets.edit`, `assets.bulk_edit`	Create and edit assets
`assets:delete`	`assets.delete`	Delete and retire assets
`assets:import`	`assets.import`	Bulk import via CSV
`members:read`	`members.view`	View team members
`departments:read`	`departments.view`	View departments
`departments:manage`	`departments.manage`, `departments.view`	Create and edit departments
`locations:read`	`locations.view`	View locations
`locations:manage`	`locations.manage`, `locations.view`	Create and edit locations
`audit:read`	`audit.view`	View audit logs
`policies:read`	`policies.view`	View compliance policies
`policies:manage`	`policies.manage`, `policies.view`	Create and edit policies
`integrations:read`	`integrations.view`	View integrations
`integrations:manage`	`integrations.manage`, `integrations.view`	Configure integrations
`webhooks:manage`	`integrations.manage`	Create and manage webhooks
`odata:read`	`assets.export`	Access the OData feed, and the CSV/JSON asset export endpoints below
`ai:use`	`ai.use`	Use the AI assistant
`admin`	every permission	Full administrator access - the only scope that reaches a route marked “admin only” below

No scope grants asset_schema.manage (asset category writes) or members.invite (inviting, updating or importing members) on its own - only the admin scope does. The tables below mark every route that is reachable only with admin.

Base URL and errors

Every endpoint below is prefixed with /api. Errors share one shape:

{
  "statusCode": 400,
  "message": "Validation failed: serialNumber must be a string",
  "error": "Bad Request"
}

401 means the key is missing, invalid, expired or revoked. 403 means the key’s role does not carry the permission the endpoint requires. 429 means the request was rate limited.

Assets

Method	Path	Permission	Scope	Description
GET	`/assets`	`assets.view`	`assets:read`	List assets. Supports `search`, `category`, `lifecycleStage`, `locationId`, `departmentId`, `assignedTo`, `page`, `pageSize`, `orderBy`, `order`
GET	`/assets/:id`	`assets.view`	`assets:read`	Get a single asset
POST	`/assets`	`assets.create`	`assets:write`	Create an asset
PATCH	`/assets/:id`	`assets.edit`	`assets:write`	Update an asset
DELETE	`/assets/:id`	`assets.delete`	`assets:delete`	Soft-delete an asset
POST	`/assets/bulk-create`	`assets.create`	`assets:write`	Create multiple assets in one request
PATCH	`/assets/bulk`	`assets.bulk_edit`	`assets:write`	Patch fields across multiple asset IDs
POST	`/assets/bulk-delete`	`assets.delete`	`assets:delete`	Bulk soft-delete
GET	`/assets/export.csv`	`assets.export`	`odata:read`	Download assets as CSV
GET	`/assets/export.json`	`assets.export`	`odata:read`	Download assets as JSON

Create an asset

POST /api/assets
x-api-key: ar_...
Content-Type: application/json

{
  "name": "Dell Latitude 5540",
  "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "serialNumber": "ABC123",
  "locationId": "b2c1a9d0-...",
  "lifecycleStage": "DEPLOYMENT"
}

A successful create returns the full asset record, including its generated id.

Asset categories

Method	Path	Permission	Scope	Description
GET	`/asset-categories`	`assets.view`	`assets:read`	Get the category tree
POST	`/asset-categories`	`asset_schema.manage`	`admin` only	Create a category
PATCH	`/asset-categories/:id`	`asset_schema.manage`	`admin` only	Update a category, including its custom fields
DELETE	`/asset-categories/:id`	`asset_schema.manage`	`admin` only	Delete a category

No non-admin scope grants asset_schema.manage - creating, editing or deleting a category by API requires a key scoped admin.

Locations

Method	Path	Permission	Scope	Description
GET	`/locations`	`locations.view`	`locations:read`	List locations
GET	`/locations/:id`	`locations.view`	`locations:read`	Get location details
POST	`/locations`	`locations.manage`	`locations:manage`	Create a location
PATCH	`/locations/:id`	`locations.manage`	`locations:manage`	Update a location
DELETE	`/locations/:id`	`locations.manage`	`locations:manage`	Delete a location
POST	`/locations/import/analyze`	`locations.manage`	`locations:manage`	Upload a CSV/Excel file and preview the column mapping
POST	`/locations/import/commit`	`locations.manage`	`locations:manage`	Commit a location import

Locations follow a four-tier hierarchy (site, facility, level, space). See Locations and mapping for the full model.

Departments

Method	Path	Permission	Scope	Description
GET	`/departments`	`departments.view`	`departments:read`	List departments
POST	`/departments`	`departments.manage`	`departments:manage`	Create a department
PATCH	`/departments/:id`	`departments.manage`	`departments:manage`	Update a department
DELETE	`/departments/:id`	`departments.manage`	`departments:manage`	Delete a department

Members

Method	Path	Permission	Scope	Description
GET	`/members`	`members.view`	`members:read`	List members
POST	`/members/import`	`members.invite`	`admin` only	Bulk-import members
POST	`/members/import/parse`	`members.invite`	`admin` only	Parse an uploaded CSV/Excel file (multipart, 50MB max) into a preview, without saving
POST	`/members/invite`	`members.invite`	`admin` only	Invite a member by email
PATCH	`/members/:id`	`members.invite`	`admin` only	Update a member’s profile fields

No non-admin scope grants members.invite - every members write above requires a key scoped admin, even though members:read alone is enough to list members.

Map and geo

Method	Path	Permission	Scope	Description
GET	`/map/placements`	`assets.view`	`assets:read`	List asset pin placements
GET	`/map/assets`	`assets.view`	`assets:read`	List assets for map view
PUT	`/map/placements/:assetId`	`assets.edit`	`assets:write`	Place or move an asset’s pin
GET	`/map/nearby`	`assets.view`	`assets:read`	Find assets within a radius of a point
GET	`/geo/search`	`locations.view`	`locations:read`	Address autocomplete

AI assistant

Method	Path	Auth	Scope	Description
POST	`/ai/chat`	API key or workspace token	`ai:use`	Send a message; returns a server-sent event stream
GET	`/ai/usage`	Workspace token only	-	Usage metrics

A key with the ai:use scope drives the same assistant the in-app chat uses, bound by that key’s own permissions and field access - so an ai:use-only key can converse but cannot act on anything unless the key also carries the resource scopes (assets:write, and so on) for what you want it to do. See AI assistant.

Data export (OData)

A read-only OData v4 feed for BI tools, gated by assets.export (scope odata:read - the same scope that covers the CSV/JSON export endpoints above):

Method	Path	Description
GET	`/odata/Assets`	Query assets. Supports OData `$filter`, `$select`, `$top`, `$skip`
GET	`/odata/$metadata`	EDMX metadata document
GET	`/odata/Assets/$count`	Count matching assets

There is no write path on this feed. Whether the feed itself is turned on for your organisation is a separate, sign-in-only setting (see below).

Webhooks

An API key receives webhook deliveries but cannot configure them: creating, updating or deleting a webhook subscription requires a signed-in session, not an API key. Once a webhook is registered, every delivery is signed:

X-WAR-Signature: sha256=<hmac>

Compute the same HMAC-SHA256 over the raw request body using your webhook’s secret, and compare it to the header to confirm a delivery genuinely came from World Asset Register. Event types include asset.created, asset.updated and asset.deleted.

Not available by API key

These stay sign-in only, whatever permissions the key’s role carries:

Webhook configuration
The data export (OData) on/off toggle for the organisation
The audit log
Reports and report templates
Policies and violations
Roles
Billing
GDPR export and erasure

Welcome

Assets

Organisation setup

Day-to-day operations

AI & integrations

Account & billing

Support

Authentication

Scopes

Base URL and errors

Assets

Asset categories

Locations

Departments

Members

Map and geo

AI assistant

Data export (OData)

Webhooks

Not available by API key

​Authentication

​Scopes

​Base URL and errors

​Assets

​Asset categories

​Locations

​Departments

​Members

​Map and geo

​AI assistant

​Data export (OData)

​Webhooks

​Not available by API key

Authentication

Scopes

Base URL and errors

Assets

Asset categories

Locations

Departments

Members

Map and geo

AI assistant

Data export (OData)

Webhooks

Not available by API key