API Conventions
The one-page contract every Signals v1 endpoint follows — pagination, errors, includes, sparse fieldsets, idempotency, async, and events.
Rental fields use flat database names on REST, MCP, webhook, plugin, import/export, report and merge-field surfaces. For example, starts_at, uses_billable_days, customer_collects, subtotal, tax_total and total have the same names everywhere. Rental money responses are decimal strings with currency metadata. See Rental fields.
Overview
Every endpoint under /api/v1/ follows the same conventions. Learn them once and
they apply everywhere. This page is the canonical checklist; individual resource
pages only document what is specific to them.
JSON command objects accept only documented fields. Unknown keys, including
misspelled keys inside structured objects and list entries, return 422 with
the field path in errors. Authorization is checked before command validation.
Documented open maps, including custom fields, metadata, settings values and
workflow configuration, retain their own extensible keys. Required fields,
allowed enum values, numeric bounds and text limits appear in the request schema.
Curated MCP tools publish these property constraints and nested request shapes
alongside their tool arguments.
Base URL & versioning
All endpoints are prefixed with /api/v1/. Version 1 is additive-only — see
API versioning. Discover changes at
GET /api/v1/changelog.
Authentication
Requests authenticate with a Sanctum bearer token:
curl -H "Authorization: Bearer {token}" {app-url}/api/v1/accounts
Tokens carry abilities in resource:action form (e.g. accounts:read,
invoices:write). A missing ability returns 403; a missing/invalid token
returns 401.
Response envelopes
Every body-bearing success response has a data key and optional sibling meta.
A single resource or action result is an object; a collection is an array:
{ "data": { "id": 1 } }
{
"data": [ { "id": 1 } ],
"meta": { "total": 47, "per_page": 20, "page": 1, "last_page": 3 }
}
Code fields use stable machine values; their human-readable display text uses a matching _label field. For example, transaction_type: "rental" has transaction_type_label: "Rental". Custom-field types, equipment-test tasks, outcomes and enforcement modes follow the same convention with field_type_label, task_type_label, outcome_label and enforcement_mode_label. Send the code value when writing or filtering; labels are response display text.
Pagination
Lists using the shared query paginator default to offset pagination with
?page=1&per_page=20. page is 1-based; per_page defaults to 20 and is
clamped to 1–100. Offset meta contains total, per_page, page, and
last_page.
On these lists, opt into cursor pagination with ?cursor=1&per_page=20.
cursor= and cursor=true also select the first page. Pass the returned
meta.next_cursor or meta.prev_cursor unchanged as the next request's
cursor value, keeping the same filters and sort. URL-encode the value.
The presence of cursor overrides page; per_page still applies.
Cursor meta contains per_page, next_cursor, and prev_cursor; a null
cursor means there is no page in that direction. Cursor pages omit total,
page, and last_page.
OpenAPI and the Postman export declare the optional cursor input for every
list using the shared query paginator, and OpenAPI describes both metadata
shapes. Complete collections do not gain cursor pagination. Endpoints with
native cursor-only pagination retain their documented defaults and cursor
semantics.
For example, a final cursor page (resources abbreviated):
GET /api/v1/accounts?cursor=1&per_page=20&filter[updated_at][gte]=2026-11-04T00:00:00Z&include_deleted=true
{
"data":[{"id":42,"updated_at":"2026-11-04T09:30:00Z","deleted_at":null,"merged_into_account_id":null}],
"meta":{"per_page":20,"next_cursor":null,"prev_cursor":null}
}
Filtering
Use ?filter[field][operator]=value, or ?filter[field]=value for equality. Every field and operator must be permitted by the selected endpoint. Conditions on different fields, and multiple operators on one field, are ANDed:
GET /api/v1/rentals?filter[state]=order&filter[starts_at][gte]=2026-10-01T00:00:00Z&filter[starts_at][lt]=2026-11-01T00:00:00Z&sort=-starts_at
| Operators | Meaning |
|---|---|
eq, ne |
Equals, does not equal |
in, not_in |
In a list, outside a list |
contains, not_contains |
Literal case-insensitive substring or exclusion |
starts_with, ends_with |
Literal case-insensitive prefix or suffix |
gt, gte, lt, lte |
Ordered comparisons |
null, not_null |
SQL nullness; missing custom-field rows count as null |
blank, present |
Empty or populated according to the field type |
Only operators supported by the field's type are accepted. String matching escapes %, _, and the escape character. Negative comparisons exclude SQL NULL values. Unary null, not_null, blank, and present require true or 1 over HTTP, and the boolean true in JSON or MCP. Filter booleans with eq=true or eq=false.
For lists, use filter[id][in]=1,2 or repeated filter[id][in][]=1&filter[id][in][]=2. Comma-list elements are trimmed; a value containing a comma needs array syntax. JSON uses a native array. Empty lists, empty elements, nested lists, and mixed list encodings are rejected.
Use public enum strings such as filter[status]=quote_held for rental status, never backing integers. List-backed custom fields accept an authorized active entry ID or an exact unique active name from the field's selected list. Integer-looking values select IDs; fractional or exponent forms are rejected.
Dates are real YYYY-MM-DD dates. Datetimes require ISO-8601 with Z or an explicit offset and are compared in UTC. Time-only fields accept HH:MM or HH:MM:SS. Integers are signed base-10 whole numbers; decimal values use finite decimal strings within the field's precision and scale. HTTP booleans accept true, false, 1, or 0; JSON also accepts native booleans. Empty strings and meaningful whitespace remain values. JSON null is not a binary operand or list element; use a unary operator.
Incremental sync and tombstones
Every stored-record list, including nested and hand-built lists, accepts filter[created_at] and filter[updated_at] when those timestamps exist on its model. For example, poll ?filter[updated_at][gte]=2026-01-01T00:00:00Z&sort=updated_at. Both /payments and /invoices/{invoice}/payments use this contract. Append-only logs without an updated_at column accept created_at only. Computed catalogues, search results and projections without record timestamps are not incremental-sync feeds. Endpoint-specific filters, parent constraints, permissions and warehouse restrictions still apply.
Every row in a list with a deletion marker carries deleted_at, including live rows (null). Use ?include_deleted=true to include soft-deleted rows, or any filter[deleted_at] condition to opt in implicitly. For example, ?filter[deleted_at][gte]=2026-01-01T00:00:00Z returns tombstones since that instant. The shared field also represents archived_at or voided_at on models with those markers; when several markers exist, a physical deletion takes precedence, followed by archive and void. Existing archive/void visibility defaults remain unchanged. Merged accounts also carry merged_into_account_id.
Assets, activities and repairs now support retained soft-delete tombstones. The repair DELETE operation still cancels the repair: its cancellation timestamp is also exposed as deleted_at, and a tombstone request includes inactive repairs unless an explicit status filter narrows the result. Existing cancelled repairs are backfilled from their last update timestamp. Historical hard deletions cannot be recovered. Combine include_deleted=true with the changed-since filter and page through the complete result to synchronize live changes and removals together. Soft deletion advances updated_at; changing a line (rental, invoice, credit note, purchase order or warehouse transfer lines) also bumps its parent's updated_at. Tombstones require the same read permission as the list and never bypass its other access restrictions.
A tombstone-only request uses the same filter grammar:
GET /api/v1/accounts?filter[deleted_at][gte]=2026-11-04T00:00:00Z&cursor=1
{
"data":[{"id":41,"updated_at":"2026-11-04T10:00:00Z","deleted_at":"2026-11-04T10:00:00Z","merged_into_account_id":42}],
"meta":{"per_page":20,"next_cursor":null,"prev_cursor":null}
}
Resources are abbreviated. Persist a sync checkpoint only after consuming every page; use an overlapping gte boundary and deduplicate by resource ID and version/timestamp so equal timestamps are not skipped. Refetch changed parents with the relations your integration needs. Cursor pagination does not freeze the underlying collection while writes continue.
Custom fields and relations
Use filter[custom_fields.po_reference][contains]=PO- for an active searchable custom field visible to the caller. Relation paths require an explicitly published relation and column; the catalogue-item list, for example, permits filter[catalogueItemGroup.name][contains]=Lighting. An arbitrary relation path is rejected.
Array fields use eq/contains for one typed element and in for any element in a typed list; negative forms exclude elements. For JSON arrays, null tests SQL NULL, while blank also includes JSON null and an empty array. Scalar-string blank means NULL or an empty string, with whitespace considered populated. For other scalar types, blank/present mean null/non-null. A missing related row satisfies no related-column condition.
JSON key/value custom fields support structural contains/not_contains with a nonempty object. URL/form requests send an encoded JSON object:
filter[custom_fields.attributes][contains]=%7B%22colour%22%3A%22blue%22%7D
JSON requests send native objects and lists:
{"filter":{"id":{"in":[1,2]},"custom_fields.attributes":{"contains":{"colour":"blue"}}}}
Object operands preserve scalar JSON types and support nested object/array containment. They reject null at every depth, duplicate keys, and empty object operands. File/image fields accept only unary operators. For object and file custom fields, blank includes an absent value row, SQL NULL, JSON null, or {}; not_null requires an existing SQL non-NULL value, including JSON null and {}. Multi-list fields use the same array emptiness rules and resolve each element to a permitted list entry.
Requests allow at most 50 field/operator conditions, 100 entries per list, one relation hop, 255 characters per scalar string, and 2,048 bytes per field path. Custom-field keys are a single segment after custom_fields.. Object operands allow at most four nested levels below their root, 100 total keys/array elements, 255 characters per string/key, and 8,192 encoded UTF-8 bytes. Repeated decoded field/operator paths, scalar/object collisions, repeated JSON keys, and conflicting query/body conditions are rejected before execution.
Search and MCP
On supported indexed lists, filter[search]=stage searches indexed title, content, and metadata and is ANDed with other conditions. Empty search is a no-op. Account list search requires accounts.identity.view; callers without it receive HTTP 422 with unknown_filter_field, including for an empty search. Queries under three characters match a title prefix or exact metadata value; longer queries also match substrings and full-text terms. On supported embeddable lists, filter[similar_to]=rental:12 selects semantic neighbours. These operations are available only where the endpoint publishes them. Ranked cross-resource search remains GET /api/v1/search?query=stage; semantic cross-resource search uses /api/v1/search/semantic?query=stage. Both cross-resource endpoints accept the same query DTO (255 characters, configurable per-type ceiling). Unrecognised types[] keys appear in meta.ignored_types; recognised keys still restrict the result groups. The approval inbox and catalogue-tag list retain their separate search parameters.
MCP curated tools and execute-endpoint accept the same field/operator map under filters, forwarded to the API as filter:
{"filters":{"name":{"contains":"stage"},"id":{"in":[1,2]},"custom_fields.attributes":{"contains":{"colour":"blue"}}}}
Convenience arguments combine with explicit filters. Duplicate canonical field/operator pairs, including aliases, shorthand equality, or conflicts with query.filter, are rejected. Distinct operators on the same field combine.
Filter errors and ignored sorts
Invalid filters return HTTP 422 before the query runs:
{
"message": "The given data was invalid.",
"errors": { "filter.name.foo": ["The operator is not supported for this field."] },
"code": "invalid_filter_operator"
}
Codes are unknown_filter_field for unknown or unavailable fields/relations, invalid_filter_operator for unsupported operators, invalid_filter_value for invalid shape/type/value, and filter_limit_exceeded for limits. The first failure in input order supplies the top-level code and public error path. Correct that condition before retrying. Aggregate requests use the same contract.
Unsupported sort fields are reported separately in meta.ignored_sorts; the key is absent when every requested sort is accepted.
Saved views and meta.view
Offset-paged collections include meta.total, meta.per_page, meta.page, and meta.last_page.
meta.view is not universal — treat it as optional and never require it.
An index that is backed by saved views (live filters) reports the view whose filters, sort, and column selection it applied:
{
"data": [ { "id": 1 } ],
"meta": { "total": 12, "per_page": 20, "page": 1, "last_page": 1, "view": { "id": 7, "name": "Out this week" } }
}
The object carries exactly id and name. The key is absent when no view
was applied; it is never null and never an empty object.
Three things resolve a view, in this order, so meta.view can appear on a
request that never mentioned one:
- An explicit
?filter_id=(afilter_idthat the caller cannot see is404, not a silent fallback). - The authenticated caller's saved view preference for that entity.
- A global default view for that entity.
Because of (2) and (3), a client that wants the unfiltered set must not assume
"no filter_id sent" means "no view applied" — read meta.view back and, when
one was applied, send the filters it needs explicitly.
Every index that can return meta.view accepts ?filter_id=; the reverse does
not always hold, since an endpoint may resolve a view for its own defaults
without reporting one. Saved views cover the main operational and finance
registers — accounts, rentals, rental projects, invoices, credit notes,
purchase orders, catalogue items, assets, repairs, equipment tests, stock
checks, warehouse transfers, virtual stock intakes, asset retirements,
vehicles, facilities, services, resource assignments, document templates,
approval-chain delegations, and the pricing and tax reference lists. Purpose-
built endpoints — scan_contexts, scannable_identifiers, aggregate,
events, changelog, and the other meta routes — never carry it.
Sorting
Sort with ?sort=field (ascending) or ?sort=-field (descending), restricted
to each endpoint's allow-listed sortable fields. Rejected sort fields are
reported via meta.ignored_sorts (see above).
Includes
Lazy relationships are opt-in via ?include=lines,costs on rentals. Omitted relationships
are not present in the body (not null). Protected includes require the same
permission and token read ability as the related resource endpoint: rates
requires rates.view and rates:read; assets requires assets.view and
assets:read; invoice payments requires invoices.view and payments:read;
invoice creditNotes (or credit_notes) requires invoices.view and
credit-notes:read. These checks also cover nested paths, default includes,
and MCP calls. Missing access refuses the request with 403 before loading
any requested relationships or running a mutation, consistent with the API authorization contract.
Parent includes also require access to their serializer dependencies: transfer
lines (including its nested aliases) requires asset read access because line
receipts contain asset snapshots. virtualAssets requires asset read access too.
Protected relationships loaded implicitly by actions or serializers are withheld
when the caller lacks access; transfer receipt asset numbers, serial numbers and
barcodes are then null.
Unknown include names continue to be ignored.
Sparse fieldsets
Narrow the resource inside data with ?fields=a,b,c, and nested relations with
?fields[lines]=id,quantity. id is always included and custom_fields is
addressable as a field. Do not prefix field names with data. Omitting fields returns the full, byte-identical
default body. Sparse fieldsets are for response projection; saved-view column
selection continues via ?filter_id.
Custom fields
Custom fields are serialised as a flat object: {"custom_fields": {"po_ref": "PO-1"}}.
The same custom_fields object is accepted by the existing create and update
commands for these records. Omit it on updates to retain existing values. Keys
must name active fields defined for that module; required fields, types, role
visibility and conditional field rules are validated by the server.
| Record | Custom-field module |
|---|---|
| Credit notes | CreditNote |
| Payments | InvoicePayment |
| Purchase orders | PurchaseOrder |
| Addresses | Address |
| Labour services | Service |
| Equipment test results | EquipmentTestResult |
| Rental projects | RentalProject |
| Documents | Document |
| Workflows | Workflow |
| Reports | Report |
| Approval chains | ApprovalChainDefinition |
These extend the existing account, activity, asset, catalogue item/group,
equipment test, facility, invoice, rental/line, repair, stock check, vehicle,
warehouse and warehouse transfer modules. Discover the authoritative module
names and definitions through describe-custom-field-schema. The curated MCP
commands get-entity-custom-field-values and set-entity-custom-field-values
use the same module names, record permissions and validation as the UI.
Credit notes and payments are created through their invoice commands. Their
fields are metadata and do not change amounts or financial postings. Historic
credit notes remain locked. Purchase orders are editable only while draft;
final documents, published approval chains and voided equipment test results
also reject metadata edits. Read-only API resources expose values without
adding a new general update endpoint; eligible records can use the guarded MCP
custom-field command. The approval-chain API path is
/api/v1/approval-chain-definitions.
Dates & money
Dates are ISO 8601 in UTC (2026-01-15T14:30:00Z). Money is returned as decimal
strings ("125.50") — never floats or raw minor units.
Errors
message is the readable explanation. code is optional: coded domain refusals include it, while plain validation 422s and some 409/425 responses omit it. Handle the HTTP status first and inspect code only when present. Do not require current_version, retry_after or errors on every failure. Finance in-flight 425s and signed inbound workflow replay 409s can contain only message; write-off, reversal and write-off approval 409s can contain message and optional errors.
Shared OpenAPI error responses use NotFound, ValidationError, Unauthenticated, Forbidden, Conflict, and TooEarly. Their bodies use the Laravel shape:
{ "message": "The given data was invalid.", "errors": { "field": ["..."] } }
Validation failures return 422; auth 401/403; not-found 404; conflicts
409.
Shortage and virtual stock refusals
Commands refuse these operations with 422 and a stable top-level code
alongside message and field errors. Scan submissions instead record a blocked
outcome and carry the code in the scan event/command result or bulk item:
| Code | Meaning |
|---|---|
virtual_stock_not_received |
Allocation, substitution or dispatch requires receipt evidence for the virtual asset's intake. Single scans expose the code in event/command metadata; bulk scans return it with a message on the blocked item. |
shortage_already_planned |
The sub-hire option is stale because a resolution already covers the requested quantity. Refresh the shortage before applying another option. |
shortage_rental_inactive |
The rental is inactive, held, closed or completed and cannot acquire a shortage resolution. |
purchase_order_intake_received |
PO cancellation would discard a physically received intake. Return or reconcile received kit first; the PO and intake remain unchanged on refusal. |
Confirmed but unreceived sub-hire remains planning supply. Receipt undo restores that planned state, keeps the standing PO/resolution, and removes allocation and dispatch readiness until re-receipt. PO-line receipt evidence is accepted only when its received quantity covers the entire intake. If the intake still exceeds the received quantity, all its virtual units remain unallocatable. Returning fulfilled sub-hire kit to the supplier preserves the fulfilled resolution history.
Idempotency
Any side-effecting POST (payments, credit notes, issue/void, stock
transactions, transfers, PO send/receive, document generation, …) accepts an
optional Idempotency-Key request header. Replaying the same key returns the
stored response with Idempotency-Replayed: true. Reusing a key with a
different body returns 409; an in-flight key returns 425. Sending the header
is optional by default, subject to the finance exceptions below. Keys must contain 1–255 characters. The shared OpenAPI parameter is #/components/parameters/IdempotencyKey and appears on every covered mutating operation, including rental transitions, unless the operation declares its own header. An explicit operation-level requirement takes precedence. Enabling api.require_idempotency_key makes it mandatory on mutating POST requests; omitting it then returns 428. Read-only rate previews and identifier-label rendering do not use replay keys.
These finance operations always require Idempotency-Key, regardless of strict mode:
POST /api/v1/invoices/{invoice}/write_offsPOST /api/v1/invoices/{invoice}/write_off_reversalsPOST /api/v1/invoices/{invoice}/settlement_allocationsPOST /api/v1/invoices/{invoice}/write_off_approval_requests/{approvalChainDefinition}
Partial standard invoice checkout requires the header or the documented idempotency_key body field. The six scan-session operations marked auto let generated clients supply a key; that marker does not make the header universally required. Plugin callbacks use their plugin's declared contract.
The claim namespace is (tenant, credential or connection, key). Two
credentials may use the same key without colliding. A named connection keeps
one stable claim owner when its grant generation changes. This prevents a
retry after grant rotation from running the original effect again.
Every claim also records a one-way authorization fingerprint. A replay is
refused with 403 and code idempotency_replay_authorization_changed when the
current grant generation, token abilities, application permissions, user
state, OAuth scopes, or warehouse scope differs from the original call. The
stored response is not returned. Claims stored without this fingerprint also
fail closed.
Claims and completed responses have a 24-hour TTL by default
(idempotency.ttl_hours) and are pruned after expiry.
The OpenAPI operation extension x-signals-idempotency has three states:
auto means generated clients should create a key automatically, accepted
means the route accepts a caller-supplied key without automatic SDK synthesis,
and an absent extension means the operation has no route-level idempotency
contract.
For example, a generated client reads these operation fragments as follows:
{ "operationId": "v1.scan_sessions.scans.bulk", "x-signals-idempotency": "auto" }
Create and send a new key unless the caller supplied one. The six automatic
operations are scan-session store, close, abandon, single-scan store,
bulk scan, and scan void.
{ "operationId": "v1.invoices.issue", "x-signals-idempotency": "accepted" }
Expose an opt-in key helper, but do not silently add a key.
{ "operationId": "v1.accounts.index" }
The absent extension means the route does not advertise idempotency handling; clients must not infer it merely from the HTTP method.
An operator can enable strict mode via api.require_idempotency_key. When
on, it requires the header on every mutating POST /api/v1/... request
(428 if missing) — not just the routes above that also get replay/conflict
semantics. Strict mode never applies to GET/HEAD/OPTIONS, to
PUT/PATCH/DELETE, or to unauthenticated endpoints
(inbound webhook receivers, the token-in-URL export download) — those callers
have no bearer token and, for inbound webhooks, no way to send a
Signals-specific header at all.
Successful 2xx responses and validation 422 responses are cached, except
the lock-timeout 422 refusals rental_lock_timeout and credit_lock_timeout.
Those refusals are not stored for replay: they leave the claim retryable or
uncertain according to the recorded execution evidence. Server 5xx responses
are never cached: they leave the claim uncertain, as does an unhandled handler
exception. Other 4xx responses normally release the claim so the request can
be attempted again. A completed replay restores the stored status and JSON
body, including 207 Multi-Status from a partial bulk operation, and adds the
Idempotency-Replayed response header.
Retrying a 425
A finance 425 may be just {"message":"Request in progress."}. Neither code: request_in_progress nor a retry_after property is guaranteed. Apply the retry policy below without requiring either field.
A 425 is the in-flight response when no stored response is available. It
normally means another request still holds an active processing lease. The
lease defaults to 300 seconds, configured by
idempotency.lease_seconds (API_IDEMPOTENCY_LEASE_SECONDS). A 425 carries
no Retry-After header. Retry the identical request with the same key, using
exponential backoff and jitter (for example, start at 1 second and cap at 30
seconds). Clients may stop waiting sooner and escalate; stopping a poll does
not establish whether the operation completed.
When a matching request finds an expired lease without a stored response, the
server marks the claim uncertain and returns 409 with
code: idempotency_outcome_uncertain and idempotency_claim_id. A handler
exception or server error can also leave the claim uncertain before the lease
expires. Stop retrying and escalate to an operator, including that claim ID.
The 24-hour default retention (idempotency.ttl_hours) is not permission to
repeat an operation whose domain outcome is unknown. Do not switch to a new
key to retry a payment, invoice or credit-note write: that can apply it twice.
Reconciling an uncertain outcome
An operator must first confirm the domain outcome from authoritative records, including any external provider outcome. Then resolve the uncertain claim in the installation that owns it:
php artisan signals:api-idempotency:reconcile CLAIM_ID completed --evidence="Authoritative outcome checked" --status=200 --response-json='{"data":{"result":"confirmed"}}' --no-interaction
php artisan signals:api-idempotency:reconcile CLAIM_ID retryable --evidence="Confirmed operation did not take effect" --no-interaction
claimis the positive integeridempotency_claim_idfrom the409body.outcomeiscompletedto save a reconciled response, orretryableonly after confirming that another attempt is safe. Only uncertain claims in the current tenant can be reconciled.--evidenceis required, non-empty operator or domain evidence describing the authoritative check; it is retained with the claim.--statusis required forcompletedand must be an HTTP status from 100 through 599. Use the status that matches the confirmed outcome.- For a body-bearing success status (2xx except 204),
--response-jsonis required and must be an object withdataand optionalmetaas its only root keys. For 204 and error statuses it may be omitted; error bodies retain their error contract. Supply the confirmed response to replay verbatim. The example payload above is illustrative, not a payment response.
After completed, the same matching request replays the stored response.
After retryable, the next matching request with the same key acquires a
new fenced processing lease.
Scan ingestion with stable references
For scan ingestion only, a stable client_ref for each physical scan provides
separate session-level deduplication. A client may retry with a new key,
the same request data, and the same client_ref values: a recorded scan
returns already_recorded instead of applying its domain effect twice.
Changed normalized input, method or requested quantity is a client_ref
validation error, not a successful replay. Current session authorization still
applies before a saved result is returned. This exception does not apply to
money-moving writes. See Scanning API.
Asynchronous operations
Long-running operations return 202 Accepted with a uniform body:
{ "data": { "message": "Accepted", "job_id": "…", "status_url": "/api/v1/jobs/{job}" } }
Poll data.status_url (GET /api/v1/jobs/{job}) for progress. It returns the job's
published status payload, or 404 once the status has expired.
Rate limiting
Requests are rate-limited per credential or approved connection, or per IP when
unauthenticated. With unit throughput metering enabled, no flat rate-limit headers are returned to authenticated
callers. Every authenticated external principal uses unit throughput metering
by default. Authenticated responses carry
X-Signals-Units-Remaining, X-Signals-Units-Restore-Rate,
X-Signals-Units-Daily-Remaining, and X-Signals-Units-Charged instead.
These integer headers are reusable OpenAPI components.headers, referenced
by operation responses (including successful responses). They describe the
short-term balance, units restored per minute, daily balance, and final
charge respectively. They are conditional: disabled metering or a request
without an external principal does not emit them. When unit throughput metering is disabled, authenticated requests use the flat limiter and its X-RateLimit-* headers instead.
An idempotency replay reports X-Signals-Units-Charged: 0 and does not consume
the short-term bucket or daily allowance again. A 304 Not Modified response
costs one unit. Authorization denials and missing resources (401, 403, and
404) cost zero units. Validation failures and other completed calls use the
declared operation weight.
Unauthenticated endpoints keep the flat per-minute limiter and its
X-RateLimit-Limit / X-RateLimit-Remaining headers. Quota discovery lives on
GET /api/v1/me, which reports rate_limit_per_minute, the live per-minute
unit balance, and the daily balance. A 429 includes Retry-After. A token may
be given a bespoke per-minute limit from the API Tokens admin screen.
Every OpenAPI operation references the reusable TooManyRequests 429 response.
Its Retry-After header references a reusable integer header measured in
seconds (at least 1). Throughput enforcement returns
{"message":"Too Many Requests"}, a zero short-term remaining balance, the
restore rate, and the daily remaining balance; it omits X-Signals-Units-Charged.
Observe mode logs over-budget calls and lets them proceed; enforce mode rejects
them with 429. Clients should wait for Retry-After before retrying.
Webhooks & events
Subscribe to events with an outbound webhook; deliveries carry X-Signals-Signature, an HMAC-SHA256 over {X-Signals-Timestamp}.{raw body}. Verify the timestamp within 300 seconds and deduplicate by meta.event_id (also sent in X-Signals-Event-Id). See Webhooks for the metadata envelope and recovery endpoints. Event names are registered in the Webhook Event
Registry (resource.action, e.g. invoice.issued). Adding a new event is an
additive change.
CORS
Cross-origin access is scoped to /api/*. Allowed origins default to the app URL
(override via CORS_ALLOWED_ORIGINS). Rate-limit, request-id, retry, idempotency-replay, and deprecation headers are exposed to browser
clients.
Credentialed cross-origin requests are disabled — use bearer tokens.
Identifier conventions
Primary keys are auto-incrementing integers. Every resource is addressed by
id (/api/v1/rentals/1042). id is always an integer. Integer keys keep URLs
short and are what most integration tooling expects.
Integer route parameters must be plain digit strings within PHP_INT_MAX (9223372036854775807 on the supported 64-bit runtime). Fractional values (12.0), exponent notation (1e3), signed values (+5), whitespace and overflow return 404 before binding, including numeric flightcase lookups. Leading zeros still resolve. UUID and slug bindings retain their own rules.
Identifier lists in request bodies must be JSON arrays of integers, for example {"activity_ids":[12,34]}. Activity bulk completion and route-stop reorder reject associative objects, numeric strings, booleans and fractional numbers with 422 before changing records.
Public UUID secondaries. Where an identifier is printed, scanned, or handed
to a third party — and must therefore stay stable and unguessable independently
of the database row — the record carries a uuid column alongside the integer
PK. Flightcase and Attachment work this way: the integer id remains the
relational key, and route binding resolves the public uuid. A UUID secondary
never replaces id.
Four intentional UUID-PK exceptions. These models use a UUID as the primary key:
| Model | Endpoint area |
|---|---|
ImportBatch |
Imports |
ImportPlan |
Imports |
ImportProfile |
Imports |
ExportJob |
Exports |
They are the async import/export job records. Their identifiers are minted
client-side or queue-side before the row exists — a staged import is
addressable while it is still being assembled, and a caller polling
202 Accepted holds the job identifier before any insert has run — so an
identifier that depends on a database sequence would not work. They are also
short-lived operational artefacts rather than durable business records, so they
carry no reason to be integers. Everything else in
the API uses integer PKs; these four are the complete list of exceptions.
Cross-surface references (ref)
Every top-level resource in a REST/MCP response carries a ref: a stable,
human-readable identifier formatted entity:id.
{
"data": {
"id": 1042,
"title": "Summer Festival",
"ref": "rental:1042"
}
}
The entity slug is singular snake_case (rental, account,
catalogue_item_group, warehouse_transfer). The same value and the same format are
stamped in webhook delivery meta.ref for that record, so an event delivery and a
resource read correlate without a lookup:
{ "data": { "id": 1042 }, "meta": { "event": "rental.updated", "timestamp": "2026-01-15T14:30:00Z", "actor_type": "user", "ref": "rental:1042", "event_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "occurred_at": "2026-01-15T14:30:00Z", "resource_type": "rental", "resource_id": 1042, "resource_version": null, "schema_version": 1 } }
ref is additive and derived entirely from id — it never replaces the integer
primary key, and every existing field keeps its meaning. It appears on both
show and each row of an index response. Under a sparse projection
(?fields=) it is emitted only when explicitly requested (?fields=name,ref),
so a projection still returns exactly the fields you asked for plus id.
Dry runs (dry_run)
Every lifecycle transition that can be refused before it mutates accepts a
dry_run flag, as ?dry_run=1 or a boolean body field. The endpoint runs the
same preconditions the real call would run, mutates nothing, and returns a
verdict instead of the resource:
{ "data": { "dry_run": true, "allowed": false, "reason": "Only an enquiry can be converted to a quote.", "code": "invalid_state" } }
data.allowed is the answer; reason is human-readable and code is stable and
safe to branch on. Both are null when allowed is true.
Supported on POST /api/v1/rentals/{rental}/transitions with a to target,
the rental change_status endpoint,
and POST /api/v1/invoices/{invoice}/issue.
Rental state-transition entries in available_actions use key = to. Pass the
action key directly as the transition target; quote covers enquiry-to-quote
and order-to-quote moves. Restoration targets are quote_pencilled for a
parked quote, order_active for a cancelled order, and active for a completed
order. Read the current allowed, reason and code before submitting.
change_status additionally returns valid_statuses, and the invoice issue
dry-run adds two previews of what issuing would do:
{
"data": {
"dry_run": true,
"allowed": true,
"reason": null,
"code": null,
"would_lock_rental": true,
"due_at": "2026-08-27T09:00:00+00:00"
}
}
Both extras are computed from the very same helpers the issue action uses, so a preview and the subsequent issue cannot disagree.
Dispatch needs no dedicated dry-run endpoint: its precheck is already reachable
without mutating, both through GET /api/v1/rentals/{rental}/available_actions
(which reports the dispatch action's allowed/reason/code) and through the
transition dry-runs that share the same guard pipeline.
A dry run takes no row lock, so it neither checks nor consumes
expected_version — see below.
Optimistic concurrency (expected_version)
Rentals, invoices, purchase orders and virtual stock intakes — the four
event-sourced aggregates — carry an aggregate_version: an integer that
increases by exactly one each time a mutation is successfully committed against
that record. It is returned on every response for those four resources.
To make a mutation conditional on the copy you already read, send back the version you saw:
POST /api/v1/rentals/1042/transitions
{ "to": "order", "expected_version": 7 }
If the record has since moved on, nothing is mutated and the request fails with
409 Conflict:
{
"message": "This rental has changed since you loaded it (expected version 7, current version 9). Reload and retry.",
"code": "version_conflict",
"current_version": 9,
"expected_version": 7,
"errors": {}
}
current_version tells you exactly what to re-read and retry against. This is
deliberately a 409, not the 422 used for domain-rule refusals: the request
is not malformed and may well succeed once you are up to date.
Omitting expected_version runs the mutation unchecked, which is the
default and keeps every existing client working. Opt in per request wherever a
lost update would matter.
The check is performed after the row is locked for update, so it cannot itself be raced, and the version is only incremented once the mutation has committed — a refused transition or a failed guard never advances it.
Accepted on the rental transitions (transitions, change_status), on the invoice draft mutations
(PATCH /invoices/{invoice}, the draft line-item endpoints) and
POST /invoices/{invoice}/issue, on the purchase order mutations
(PATCH /purchase_orders/{purchase_order}, send, cancel, receive) and on
the virtual stock intake mutations
(PATCH /virtual_stock_intakes/{virtual_stock_intake}, confirm, receive,
return, cancel).
Receiving a purchase order also advances the aggregate_version of any virtual
stock intake it confirms or adjusts as a side effect, so a client holding an
intake's older version is correctly treated as stale.
Other mutations advance a rental's aggregate_version as a side effect, once
per rental and mutation:
- voiding an invoice, or deleting a draft invoice, that counts towards the rental's invoiced quantities (a standard, posting invoice owned by the rental);
- raising a repair or retiring an asset that displaces a confirmed allocation on the rental;
- apportioning or removing virtual stock costs that change the rental's costs.
A request that changes line dates on a rental that shares a date-sensitive virtual stock intake can therefore advance the rental version twice: once for the date change, and once when the cost re-apportionment that follows it changes the rental's cost.
Enum values
Enum-backed resource fields use stable lowercase snake_case strings in request bodies, responses and filter[field][operator] filters. For example use tracking: "serialised", transaction_type: "sub_hire" on a rental line, and schedule_type: "month" on an equipment test. Integer enum codes are rejected on input. Storage continues to use the existing integer codes. Human display labels may accompany these values where they have a presentation purpose. Tenant-configured list-entry IDs, within-state rental status identities, and historical audit state keep their recorded identity.
Purchase orders use supplier_id, supplier_reference, notes, subtotal, created_by, and items in responses (lines for write payloads). reference remains the separate internal reference and filters that same field. Repairs use notes. Equipment test results use performed_at, performed_by, notes, outcome, and items. Removed alternate names return 422 with a message naming the core field.
Calendar windows and partial updates
Bounded calendar endpoints accept inclusive viewer-local dates from and to (YYYY-MM-DD). The maximum window is 92 calendar days. Invalid dates, reversed ranges and longer windows return 422. Boundaries are converted to UTC for the shared overlap query. Results use cursor pagination, with per_page from 1 to 100 and opaque next_cursor / prev_cursor values in meta.
Activity updates distinguish omission from explicit null. Omitted keys retain their values; null clears nullable description, location, subject, type, schedule or participants. An activity always requires an owner: owner_id: null returns 422. Activity creation uses the authenticated user when owner_id is omitted. Reminder lead time is reminder_minutes_before; null disables reminders.
Bulk operations return {data: [...]} with one result per input position, each containing index, a string status, and either id or field-keyed errors. Full success returns 201; mixed or failed results return 207. Activity bulk completion accepts at most 100 integer activity_ids in a JSON array; numeric strings and booleans return 422. Create, complete, bulk-complete and assign accept the shared Idempotency-Key header.
Activity edits accept both PUT and PATCH at the same resource path and apply the same omitted-versus-null rules.
Empty maps
Map-valued fields return JSON objects, including {} when empty. This applies to custom_fields, workflow maps, availability demand_breakdown, report drill meta, workflow validation warnings, and invoice settings write_off_maximum_minor_by_currency. Treat them as dictionaries, not lists. Warning values are lists of strings keyed by JSON pointer; currency ceilings are non-negative integers in minor units keyed by currency. Empty or reset currency ceilings return {}. Genuine lists continue to return [].
Maps settings
Read GET /api/v1/settings/maps with settings:read:maps. MapsSettingsData describes enabled, tile_url_template, subdomains, attribution, max_zoom (1–22), and stale_after_seconds (30–86400). The group also appears in the visible settings catalogue. GET /api/v1/settings is unpaginated: per_page is rejected and page is ignored. Updating settings uses the documented settings write ability and permission checks.
Administrator filters and required command headers
The users is_admin filter is a derived boolean: it tests membership of the system-keyed Administrator role, including when that role has been renamed. It does not read a stored user flag.
An operation that explicitly requires Idempotency-Key keeps that requirement even when the general API setting makes the header optional elsewhere. The relationship-review dismissal command accepts confirmation values true, 1 or "1"; other values fail validation.