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": ["property serialNumber should not exist"],
  "error": "Bad Request"
}

For a body that fails validation, message is a list with one entry per problem. Other errors, such as a duplicate value in a unique field, return message as a single string. 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

Asset request bodies

The asset endpoints accept only a short list of top-level fields, and they refuse any other field with a 400 (for example property serialNumber should not exist). Everything else about an asset, such as its serial number, location, lifecycle stage or any custom field, goes inside a customFieldValues object.

Top-level field	Meaning
`name`	The asset’s name. Required on create
`categoryId` or `category`	The category, as the id of a node in the category tree or as its name. Send exactly one of them on create
`customFieldValues`	An object of field values, keyed by field key (see below)
`loanable`	Optional. Overrides the category’s lendability for this asset
`id`	Optional on create. Supply your own UUID to make a retried create safe to repeat
`version`	Optional. A whole number of 1 or more, used to detect conflicting edits

The keys inside customFieldValues are the field keys from your category tree. Read GET /asset-categories to see the fields each category has. Built-in keys include serialNumber, locationId, ownerId, departmentId and lifecycleStage. Relation fields take the id of the record they point to, for example the id of a location for locationId. A select field such as lifecycleStage takes one of its listed options. For a new organisation these are Deployment, In Use, In Repair, Decommission and Disposed. A key the category does not have is dropped without an error, so check the spelling against GET /asset-categories. A field marked required on the category must be sent on create. Create an asset

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

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

A successful create returns 201 and the full asset record, including its generated id. Serial number is a unique field, so a second asset with the same serial number is refused with a 400. Update an asset

PATCH /api/assets/3fa85f64-5717-4562-b3fc-2c963f66afa6
x-api-key: ar_...
Content-Type: application/json

{
  "name": "Dell Latitude 5540 (spare)",
  "customFieldValues": {
    "lifecycleStage": "In Use"
  }
}

Send only what you want to change. Keys you leave out of customFieldValues keep their current values. Use the same top-level fields as a create. Create several identical assets

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

{
  "name": "Conference room chair",
  "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "bulkQuantity": 10,
  "customFieldValues": {
    "lifecycleStage": "Deployment"
  }
}

This sends one asset description plus bulkQuantity (from 2 to 500), and creates that many copies, named Conference room chair #1, #2 and so on. It does not take a list of different assets. A field that must be unique, such as serialNumber, cannot be set this way. The response reports created, ids and createdIds. You can also send an optional ids array of UUIDs, with exactly bulkQuantity entries and no repeats, to choose the new assets’ ids. An id that already exists is skipped, so repeating a request that partly failed creates only the missing copies. Update several assets at once

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

{
  "ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "b2c1a9d0-5717-4562-b3fc-2c963f66afa7"
  ],
  "patch": {
    "customFieldValues": {
      "lifecycleStage": "In Repair"
    }
  }
}

The patch object applies the same change to every asset in ids. It accepts name, category or categoryId, vendorContractIds and customFieldValues.

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.

Policies and violations

Method	Path	Permission	Scope	Description
GET	`/policies`	`policies.view`	`policies:read`	List policies
GET	`/policies/:id`	`policies.view`	`policies:read`	Get a policy
POST	`/policies`	`policies.manage`	`policies:manage`	Create a policy
PUT	`/policies/:id`	`policies.manage`	`policies:manage`	Update a policy
DELETE	`/policies/:id`	`policies.manage`	`policies:manage`	Delete a policy
PATCH	`/policies/:id/active`	`policies.manage`	`policies:manage`	Switch a policy on or off
POST	`/policies/evaluate`	`policies.manage`	`policies:manage`	Re-run evaluation across all assets
GET	`/violations`	`policies.view`	`policies:read`	List violations. Supports `severity`, `status`, `policy`, `page`, `pageSize`
GET	`/violations/notification-config`	`policies.view`	`policies:read`	Get violation notification settings
PATCH	`/violations/notification-config`	`policies.manage`	`policies:manage`	Update violation notification settings

Violations are not resolved or acknowledged by API. They clear on their own when the underlying data is fixed and the policy is re-evaluated. See Policies.

Audit log

Method	Path	Permission	Scope	Description
GET	`/audit-logs`	`audit.view`	`audit:read`	Query the audit log. Supports `entityType`, `action`, `userId`, `limit`, `before`
GET	`/audit-logs/actors`	`audit.view`	`audit:read`	List the people who appear in the log
GET	`/audit-logs/export`	`audit.view`	`audit:read`	Download the log as signed JSON
GET	`/audit-logs/:id/rollback/preview`	`audit.rollback`	`admin` only	Preview a rollback
POST	`/audit-logs/:id/rollback`	`audit.rollback`	`admin` only	Roll back to an entry

No non-admin scope grants audit.rollback, so rolling back by API requires a key scoped admin.

Integrations

The organisation id in the path must be the organisation the key belongs to, otherwise the request is refused with 403.

Method	Path	Permission	Scope	Description
GET	`/organisations/:orgId/integrations`	`integrations.view`	`integrations:read`	List integrations
GET	`/organisations/:orgId/integrations/:id`	`integrations.view`	`integrations:read`	Get an integration
GET	`/organisations/:orgId/integrations/:id/logs`	`integrations.view`	`integrations:read`	Sync history for an integration
POST	`/organisations/:orgId/integrations`	`integrations.manage`	`integrations:manage`	Create an integration
PUT	`/organisations/:orgId/integrations/:id`	`integrations.manage`	`integrations:manage`	Update an integration
DELETE	`/organisations/:orgId/integrations/:id`	`integrations.manage`	`integrations:manage`	Delete an integration
POST	`/organisations/:orgId/integrations/:id/sync`	`integrations.manage`	`integrations:manage`	Start a sync
POST	`/organisations/:orgId/integrations/:id/test`	`integrations.manage`	`integrations:manage`	Test a saved integration
PUT	`/organisations/:orgId/integrations/:id/schedule`	`integrations.manage`	`integrations:manage`	Set or clear the automatic sync interval

Reading an integration never returns its credentials. Tokens, passwords, API keys and client secrets come back as ••••••••, while connection details such as the base URL and username are shown as saved. When you update an integration, a credential you leave out or send back as •••••••• keeps the saved value, a new value replaces it, and null clears it.

Asset import

The CSV import endpoints under /imports (for example /imports/csv/analyze and /imports/csv/execute) require assets.import, granted by the assets:import scope. See Importing data for what the import does.

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). See Developer tools for the Power BI/Excel connection walkthrough.

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

There is no write path on this feed. The feed is on by default for every organisation; turning it off in Integrations → Power BI answers every query with 409 Conflict rather than 401/403, so a BI client doesn’t misread a disabled feed as bad credentials.

Webhooks

A key can configure webhooks as well as receive them. The path carries an organisation id, but the key’s own organisation is always used.

Method	Path	Permission	Scope	Description
GET	`/organisations/:orgId/webhooks`	`integrations.view`	`integrations:read`	List webhooks
GET	`/organisations/:orgId/webhooks/:id`	`integrations.view`	`integrations:read`	Get a webhook
GET	`/organisations/:orgId/webhooks/:id/deliveries`	`integrations.view`	`integrations:read`	Delivery history. Supports `limit`
POST	`/organisations/:orgId/webhooks`	`integrations.manage`	`webhooks:manage`	Register a webhook
PATCH	`/organisations/:orgId/webhooks/:id`	`integrations.manage`	`webhooks:manage`	Update a webhook
DELETE	`/organisations/:orgId/webhooks/:id`	`integrations.manage`	`webhooks:manage`	Delete a webhook

The webhooks:manage scope grants only integrations.manage, not integrations.view. A key that should also list webhooks or read their delivery history needs integrations:read as well. 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. The secret is returned once, in the response to the request that registers the webhook. Reading a webhook later, or listing webhooks, does not return it, and it cannot be retrieved or rotated afterwards. If you lose it, delete the webhook and register it again.

Not available by API key

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

The data export (OData) on/off toggle for the organisation
Reports and report templates
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 request bodies

Asset categories

Locations

Departments

Members

Map and geo

AI assistant

Policies and violations

Audit log

Integrations

Asset import

Data export (OData)

Webhooks

Not available by API key

​Authentication

​Scopes

​Base URL and errors

​Assets

​Asset request bodies

​Asset categories

​Locations

​Departments

​Members

​Map and geo

​AI assistant

​Policies and violations

​Audit log

​Integrations

​Asset import

​Data export (OData)

​Webhooks

​Not available by API key

Authentication

Scopes

Base URL and errors

Assets

Asset request bodies

Asset categories

Locations

Departments

Members

Map and geo

AI assistant

Policies and violations

Audit log

Integrations

Asset import

Data export (OData)

Webhooks

Not available by API key