> ## Documentation Index > Fetch the complete documentation index at: https://docs.worldassetregister.com/llms.txt > Use this file to discover all available pages before exploring further. # API reference > Authentication, permissions, and the endpoints available to an API key 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](/connect/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](/setup/roles-and-permissions) for how member permissions work, and [Developer tools](/connect/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: ```json theme={null} { "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](/setup/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](/connect/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= ``` 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