Reference
AMS API Reference
Authenticated Worker routes for AMS registers, identity, custody, transit, audit, and finance.
First created Last updated
Contract rules
All routes are under /api/assets, require a validated dashboard session, and require partnerId. Physical mutations require Idempotency-Key; retry a timed-out request with the same key. Actor IDs in request bodies are not trusted for physical events.
The metadata-only schema is published at GET /api/assets/openapi.json. It declares OpenAPI 3.1, JSON Schema 2020-12, dashboard bearer security, and every mounted AMS operation. Its 74-operation inventory is generated from the route module and checked for drift during API certification. Hub task, Hub companion, Hub summary, and Settings record projections are strict schemas; older route-specific mutation bodies still use the documented generic command envelope and remain completion work.
Route families
| Area | Routes |
|---|---|
| Overview/register | GET /summary, /owned, /loaned, /items/:id, /work-orders/:id, /search |
| Personal views | GET/POST /saved-views; DELETE /saved-views/:id |
| Authorized users | GET /eligible-users?capability=… for active-partner, role/grant-filtered user comboboxes |
| Private drafts | GET/PUT/DELETE /drafts/:workflowKey for actor-, partner-, route-, and workflow-scoped expiring drafts |
| Master data | GET/POST /locations, /parties, /agreements; GET /catalog; POST /catalog/categories, /catalog/models |
| Assets/identity | POST /assets, /items/:id/activate, /items/:id/move, /items/:id/consume, /identifiers/issue, /identifiers/:id/transition, /scan/resolve |
| Custody | GET/POST /checkouts, POST /reservations, /checkouts/:id/acknowledge, /extend, /transfer, /return |
| Transit | GET/POST /shipments; POST /shipments/:id/containers, /dispatch, /handoff, /receive, /exceptions, /return-to-sender; POST /containers/:id/pack, /repack, /unpack |
| Audit/maintenance | GET /movements, /audits, /audits/:id/results, /work-orders, /work-orders/:id; POST /movements/:id/correct, /audits, /audits/:id/counts, /audits/:id/results/:resultId/review, /audits/:id/post, /work-orders, /work-orders/:id/complete, /pause, /reassign |
| Finance | GET /finance/rollforward, /finance/context, /finance/adapters/:format; POST /finance/value-entries, /value-entries/:id/reverse, /periods/:id/close, /depreciation/:id/run, /depreciation/:id/change-estimate, /depreciation/:id/schedule, /components/:id/replace, /nrv-reviews, /tco/analyze, /lifecycle-costs, /budgets, /insurance/policies, /insurance/policies/:id/approve, /coverages, /insurance/claims, /replacement-forecasts, /journal-batches, /journal-batches/:id/export, /receipts, /reconcile, /disposals/:id/complete |
| Logistics hub | GET /hub/overview, /hub/summary, /hub/tasks, /hub/records; POST /hub/tasks, /hub/tasks/assign, /hub/tasks/:id/assign, /advance; /hub/dock-appointments, /:id/transition; /hub/quality-holds, /:id/resolve; /hub/replenishment-rules; /hub/continuity-runs, /:id/complete |
| Settings master data | GET /settings/records; GET/POST /locations, /catalog/categories, /catalog/models, /parties, /agreements; policy and capability routes below |
| Interoperability | GET /interoperability/snapshot, /interoperability/epcis; POST /interoperability/jobs, /interoperability/epcis/validate |
| Imports | POST /imports/csv/validate, /imports/:id/commit; GET /imports/:id |
| Protected evidence | POST /evidence; GET /evidence; GET /evidence/:id/content; POST /evidence/:id/review |
| Alerts | GET /alerts; POST /alerts/:id/acknowledge |
| Webhooks | GET/POST /webhooks; PUT /webhooks/:id; POST /webhooks/:id/test; GET /webhooks/:id/deliveries |
| Accountable workflows | GET /workflow-cases, GET /workflow-cases/:id, POST /workflow-cases, and POST /workflow-cases/:id/decision for typed request, independent review, atomic application, and durable history |
| Policies/capabilities | GET/POST /policies; GET /policies/:id; POST /policies/:id/submit, /decision for governed identity, custody, depreciation, and permission-policy lifecycle/history; GET /capabilities; PUT /capabilities/:key |
New and corrected evidence responses use camelCase. Some older AMS projections are still being normalized under the approved-design completion task. Validation returns 400, missing/hidden records 404, locked or unreviewed evidence 423, conflicts/invariant failures 409, capability denial 403, expired authentication 401, and unexpected failures 500. Reads are bounded to at most 200 rows.
GET /owned and GET /loaned accept q, lifecycle, condition, qualityStatus, categoryId, locationId, availability, limit, and an opaque cursor. Their ordering is the stable descending pair (updated_at,id), and responses include items, nextCursor, limit, exact filtered total, asOf, and the normalized filter set. GET /checkouts, /shipments, /audits, /work-orders, /hub/tasks, /hub/records, and /settings/records also return nextCursor, limit, exact total, and asOf; Hub task pages use tasks, while Hub companion and Settings pages use records. Cursors pair the route’s authoritative timestamp with immutable ID. Hub tasks accept bounded q, status, and taskType. Hub companion records require recordType=appointment|hold|rule|continuity, accept bounded q and status where supported, and sort by the record’s authoritative appointment, placement, update, or continuity timestamp plus immutable ID. GET /hub/summary returns exact receiving, putaway, picking, packing, replenishment, quality, dock, continuity, open-task, unassigned, and urgent-unassigned counts for the current partner; clients must not derive these totals from a visible page. Settings records accept recordType (location, catalog, party, or agreement), bounded q/status, and kind (category or model) for the catalogue sub-register. Invalid cursors return 400. Cursors are opaque and must stay paired with the same filters. GET /finance/rollforward accepts bookId, ISO currency, asOf in YYYY-MM-DD, and bounded limit; responses echo the applied filter/as-of context.
Saved views are scoped to the authenticated user, partner, and AMS surface. The Worker accepts only the supported query-state keys, applies case-insensitive normalized-name uniqueness, increments the view version on update, and never accepts an owner/actor ID from the request body.
GET /eligible-users requires AMS view access and a recognized AMS capability. It resolves only active-partner memberships allowed by role defaults or non-expired capability grants and returns membershipId, immutable userId, display name, role, and capability. It does not return email addresses or accept an actor identity. Dashboard reviewer controls additionally exclude the current maker where independent review is required.
Workflow drafts are stored server-side and derive their owner from the authenticated user. The route and workflow key form part of the scope; payloads are versioned, limited to 64 KiB, and expire no later than 30 days. Saving, loading, or deleting a draft does not create a workflow case, notify a reviewer, approve a policy, or mutate asset state.
POST /hub/tasks/assign accepts 1–100 unique taskIds, one capability-eligible assigneeUserId, and a non-empty reason. It locks and validates the complete partner-scoped selection before changing any task. Every successful task receives its own actor-attributed history event; a missing, completed, duplicate, cross-scope, or otherwise invalid task rolls the whole command back. The response uses normalized camelCase Hub task records. The older single-task assignment endpoint applies the same assignee-capability and reason rules.
The canonical snapshot declares schema version 1.0 and preserves assets, identifiers, event/record chronology, containment, custody, corrections, sensor evidence, economic entries, and provenance. UBL 2.3, XBRL GL 2025, and IFRS Accounting Taxonomy adapters identify their mapping version and carry a non-filing/non-certification disclaimer.
CSV imports always run as a bounded dry run first. The response provides normalized rows, errors, and warnings; only a clean validated batch can be atomically committed with an idempotency key.
Evidence is uploaded as multipart data to the authenticated Worker. The Worker validates the target and capability, calculates SHA-256, encrypts private and restricted bytes with a per-file AES-GCM key, uploads only ciphertext to Sanity, stores canonical metadata in Postgres, and queues malware/MIME review. Content remains locked until the scan state is clean. Authorized downloads stream through /evidence/:id/content; responses never expose a Sanity API/CDN URL, provider token, bucket, or storage path. Restricted evidence additionally requires AMS administrator capability, and upload/download/review activity is recorded.
Direct operations write through their dedicated command route. POST /workflow-cases creates an actor-locked pending request; it never applies the represented operation by itself. Authorized reviewers use POST /workflow-cases/:id/decision with decision, a non-empty reason, expectedVersion, Idempotency-Key, and a recent AAL2 session. The maker cannot decide their own request. A stale version conflicts without changing state, and replaying the same decision key returns the existing outcome.
Approval atomically applies the supported typed operation and completes the case with applicationReceipt: lifecycle disposition, return of externally owned property, overdue-custody escalation, transit-exception resolution, inspection/calibration, warranty claim creation, bounded bulk move/lifecycle change, or a typed finance value entry. Rejection records versioned history without applying the operation. Finance proposals require finance_propose, an FPH-owned asset, active book whose policy matches the proposal, open fiscal period, active policy, exactly one positive debit or credit, and ISO currency. A different finance_approve user applies the proposal atomically; the append-only value entry and finance_value_entry receipt commit together, and an identical idempotent replay returns the original result. Unsupported or invalid proposals fail without completing the case. GET /workflow-cases returns only requests created by the caller or reviewable through their capability; detail includes durable history.
Policy creation validates a strict typed document for identity, custody, depreciation, or permissions and creates a versioned draft. The author submits that exact revision through POST /policies/:id/submit. A different authorized reviewer uses POST /policies/:id/decision with a recent AAL2 session, non-empty reason, expected revision, and Idempotency-Key. Approval atomically activates the version, supersedes any prior active version of the same partner/type, and records a durable policy_activation receipt; rejection leaves no active-policy side effect. Detail returns immutable history. Stale revisions conflict, and an identical decision replay returns the original result. The signed-in user and server timestamp are authoritative for every created, submitted, or reviewed record.
The Worker cron materializes durable, fingerprint-deduplicated alerts every minute for due or overdue checkouts, expiring agreements/assets, due audits, delayed shipments, and overdue work orders. Acknowledgement records the signed-in user; it does not rewrite or resolve the underlying operational record.
EPCIS exports declare EPCIS 2.0.1 and CBV 2.0.0 mapping versions, use ObjectEvent and AggregationEvent records, preserve event/record time, read point, business location, actor, correction, packing, and unpacking facts, and are bounded to 10,000 events or 366 days. This is a documented mapping profile, not a GS1 certification claim.
The certification gate downloads GS1’s versioned EPCIS 2.0.1 draft-07 JSON Schema and CBV 2.0 ontology, validates representative ObjectEvent/AggregationEvent documents, and requires every mapped business step/disposition to exist. Sensitive snapshot, EPCIS, accounting-adapter, webhook-mutation, and capability-configuration requests additionally require AAL2 with a passkey or MFA authentication method no older than 15 minutes; a stale session returns 403 step_up_required.
Webhook movement events enter a durable outbox in the same database transaction. Delivery uses X-FPH-AMS-Delivery, X-FPH-AMS-Event, X-FPH-AMS-Timestamp, and X-FPH-AMS-Signature: v1=<hex HMAC-SHA256>. Verify HMAC over <timestamp>.<delivery-id>.<raw-body>, reject stale timestamps and replayed delivery IDs, return a 2xx only after durable receipt, and retain delivery history. Configure AMS_WEBHOOK_ENCRYPTION_KEY as a Worker secret before enabling endpoints.