TrakRF API (1.0.0)

Required scope: assets:read

Paginated assets list with natural-key filters, sort, and substring search.

Default scope returns currently-effective assets only — rows whose valid_from is in the past AND whose valid_to is null or in the future. The is_active filter is independent of temporal validity; omit it to include both active and inactive rows within the effective window, or pass ?is_active=true/false to filter further.

Required scope: assets:write

Create a new asset record, optionally with one or more tags (RFID, BLE, barcode).

The external_key field is optional. Provide a value from your system of record (ERP, WMS, asset management) for natural-key joins, or omit it to receive a server-assigned external_key in the format ASSET-NNNN (per-organization sequence). A caller-supplied external_key that collides with an existing asset returns 409.

Returns the created asset with its assigned tags. The Location response header contains the canonical URL.

Required scope: assets:write

Delete an asset by its canonical id. The asset is removed from all subsequent queries and its external_key becomes immediately available for reuse. Returns 204 on success, 404 if the asset does not exist or has already been deleted.

Required scope: assets:read

Retrieve an asset by its canonical id. Returns 404 if the asset does not exist.

Path-addressed retrieval bypasses the temporal-validity filter applied on list endpoints — any non-deleted asset is returned regardless of its valid_from / valid_to values. Use this endpoint when you have an id and need the row even if its effective window has elapsed.

Required scope: assets:write

Apply a JSON Merge Patch (RFC 7396) to an asset. Only fields included in the request body are changed; fields set to null clear the corresponding nullable column. Omitted fields are left unchanged. An empty body ({}) is a no-op and returns the current resource unchanged. Read-only fields are uniformly governed by the accept-if-matches, reject-if-differs rule: a value matching the current resource state is silently normalized out (so a verbatim GET → PATCH round-trip succeeds without manual scrubbing), and a differing value returns 400 with code: read_only. This applies to the server-managed surrogate id + timestamps (id, created_at, updated_at, deleted_at), the tags collection, and the natural-key reference fields (external_key, location_id, location_external_key). Mutate external_key via POST /assets/{asset_id}/rename; asset location is collected through scan event ingestion (fixed-reader MQTT pipeline or handheld UI submission) and is not directly settable through the public API; mutate tags via POST /assets/{asset_id}/tags and DELETE /assets/{asset_id}/tags/{tag_id}.

Required scope: tracking:read

Location history for an asset identified by its canonical id.

The asset existence check follows path-addressed semantics — the asset is returned even if its valid_to has elapsed. Each history row's location reference applies the temporal-validity predicate, so an event referencing a location whose effective window is past surfaces with null location_external_key.

Required scope: assets:write

Mutate the asset's external_key (natural / join key). This operation is destructive to downstream joins: any external system that has cached or indexed records on the old external_key will silently disconnect. Prefer a coordinated cutover with downstream consumers.

external_key is immutable via PATCH; this operation is the only way to change it. Distinct from a regular PATCH in audit logs (different URL surface).

The response includes descendant_count_affected for shape uniformity with the location rename verb. Assets have no hierarchy, so this value is always 0; it is emitted to save typed-client consumers from branching on rename verb.

Required scope: assets:write

Attach a tag (RFID EPC, BLE beacon ID, barcode, etc.) to an existing asset. The tag must be unique within the organization.

Required scope: assets:write

Detach a tag from an asset by its tag record id. First successful removal returns 204; repeated calls return 404 — consistent with top-level resource DELETE semantics. The cross-asset / cross-org case (a tag that exists but is not attached to this asset, or belongs to a different org) also surfaces as 404.

Required scope: locations:read

Paginated locations list with natural-key filters, sort, and substring search.

Default scope returns currently-effective locations only — rows whose valid_from is in the past AND whose valid_to is null or in the future. The is_active filter is independent of temporal validity; omit it to include both active and inactive rows within the effective window, or pass ?is_active=true/false to filter further.

Required scope: locations:write

Create a new location in the hierarchy, optionally with one or more tags. Set parent_id (canonical) or parent_external_key (alternate) to nest under an existing parent.

The external_key field is optional. Provide a value from your system of record (ERP, WMS, layout/plan) for natural-key joins, or omit it to receive a server-assigned external_key in the format LOC-NNNN (per-organization sequence). A caller-supplied external_key that collides with an existing location returns 409.

Required scope: locations:write

Delete a location by its ID. Returns 204 on success, 404 if the location does not exist or has already been deleted, and 409 if the location has descendant locations or assets placed directly at it. Descendants must be reassigned or removed and placed assets must be moved or removed before their parent location can be deleted; bulk cascade is not supported.

Required scope: locations:read

Retrieve a location by its canonical ID. Returns 404 if not found.

Path-addressed retrieval bypasses the temporal-validity filter applied on list endpoints — any non-deleted location is returned regardless of its valid_from / valid_to values. Use this endpoint when you have an id and need the row even if its effective window has elapsed.

Required scope: locations:write

Apply a JSON Merge Patch (RFC 7396) to a location. Only fields included in the request body are changed; fields set to null clear the corresponding nullable column. Omitted fields are left unchanged. An empty body ({}) is a no-op and returns the current resource unchanged. Read-only fields are uniformly governed by the accept-if-matches, reject-if-differs rule: a value matching the current resource state is silently normalized out (so a verbatim GET → PATCH round-trip succeeds without manual scrubbing), and a differing value returns 400 with code: read_only. This applies to the server-managed surrogate id + timestamps (id, created_at, updated_at, deleted_at), the tags collection, and the external_key natural key. To re-parent, send EITHER parent_id (surrogate) OR parent_external_key (natural key); both forms accept null to clear the FK, and supplying both in the same body returns 400 ambiguous_fields (symmetric with CreateLocationRequest). Mutate external_key via POST /locations/{location_id}/rename; mutate tags via POST /locations/{location_id}/tags and DELETE /locations/{location_id}/tags/{tag_id}.

Required scope: locations:read

Sort order is fixed: ancestors are returned root first (walking up the parent_id chain), with id ascending as a deterministic tiebreaker. No sort query parameter is exposed because the natural order toward the root is the only meaningful order for this list.

Required scope: locations:read

Sort order is fixed: immediate children are returned ordered alphabetically by name ascending, with id ascending as a deterministic tiebreaker when sibling names collide. No sort query parameter is exposed because alphabetical-by-name is the only meaningful order for a single level of siblings.

Required scope: locations:read

Sort order is fixed: descendants are returned in depth-first tree order (each level sorted by lowercased external_key), with id ascending as a deterministic tiebreaker. No sort query parameter is exposed because the depth-first tree walk is the only meaningful order for this list.

Required scope: locations:write

Mutate the location's external_key. This operation is destructive to downstream joins because consumers of the natural key must re-resolve it. Only this row's external_key changes on the server; descendants are not modified.

The response includes descendant_count_affected (the live descendant count reachable through parent_id) so an integrator can decide whether to refresh derived natural-key joins for the subtree. external_key is immutable via PATCH; this operation is the only way to change it. Distinct from a regular PATCH in audit logs (different URL surface).

Required scope: locations:write

Required scope: locations:write

Detach a tag from a location by its tag record id. First successful removal returns 204; repeated calls return 404 — consistent with top-level resource DELETE semantics. The cross-location / cross-org case (a tag that exists but is not attached to this location, or belongs to a different org) also surfaces as 404.

Returns the organization scoped by the API key presented in Authorization. Intended as a lightweight health-check primitive for integrators verifying a key works end-to-end.

Required scope: tracking:read

Snapshot of each asset's most recent location, filterable by either side of the join. Filter by location (location_id / location_external_key) to retrieve everything currently at a place; filter by asset (asset_id / asset_external_key, repeatable) to resolve a batch of assets from a master system to their current locations in one round-trip. Within each pair the surrogate and natural-key forms are mutually exclusive (400 ambiguous_fields if both are supplied); the asset and location filter pairs are independent and intersect when combined. Because this view is derived from immutable scan history, it can resolve references for assets that have since been deleted. By default those rows are excluded; pass include_deleted=true to include them, and check asset_deleted_at to distinguish deleted from live.

Temporal validity is applied to both joined entities. Assets whose effective window is past or future are excluded entirely. Locations whose effective window is past or future surface with null location_id / location_external_key while the parent asset row remains visible. Soft-deleted locations are projected the same way here — null on the report row — even though the identifier still lives on the location row; reports endpoints intentionally hide tombstoned anchor points from scan-derived summaries. Use the locations endpoint with include_deleted=true to retrieve the underlying identifier.