API Endpoint Catalog

Environment Base Hosts

Environment	Host
Development	https://dev.alpha002.io.arda.cards
Staging	https://stage.alpha002.io.arda.cards
Production	https://prod.alpha001.io.arda.cards
Local	https://localhost:8889

OpenAPI and Swagger UI links below use relative paths. Prepend the base host for the target environment (e.g., https://stage.alpha002.io.arda.cards/v1/tenant/docs/openApi.json).

URL shape note. The Email module’s endpoints (under Shop Access APIs) use the canonical URL shape /v{module-version}/{domain}/{module}/... defined in Functional Decomposition. Every other Module’s endpoints in this catalog use the pre-canonical shape /v{module-version}/{module}/... — the Domain segment is absent. The divergence and the migration mechanics are documented in Legacy State.

Endpoints at a glance

Every Endpoint currently published, with its canonical URL (the shape per Functional Decomposition) and its current URL (the shape live today). Where the two differ, the gap is documented in Legacy State.

The “Collapse pattern” column shows the M / S / E chain shape under the URL collapse rule. Notation: (x/x/x) = M = S = E canonical (pure DataAuthority, all three coincide); m/(x/x) = Module distinct, S = E; m/s/e = all three distinct.

operations component

Domain	Module	Service	Endpoint	Canonical URL	Current URL	Collapse pattern
procurement	orders	order	order	/v1/procurement/orders/order	/v1/order	m/(x/x)
reference	item	item	item	/v1/reference/item	/v1/item	(x/x/x)
reference	business-affiliate	business-affiliate	business-affiliate	/v1/reference/business-affiliate	/v1/business-affiliate	(x/x/x)
resources	kanban	kanban-card	kanban-card	/v1/resources/kanban/kanban-card	/v1/kanban	m/(x/x)
shop-access	email	configuration	configuration	/v1/shop-access/email/configuration	/v1/shop-access/email/configuration	m/(x/x)
shop-access	email	job	job	/v1/shop-access/email/job	/v1/shop-access/email/job	m/(x/x)
shop-access	email	job	postmark-events	/v1/shop-access/email/job/postmark-events	/v1/shop-access/email/job/postmark-events	m/s/e

accounts-component

Domain	Module	Service	Endpoint	Canonical URL	Current URL	Collapse pattern
system	tenant	tenant	tenant	/v1/system/tenant	/v1/tenant	(x/x/x)
system	user-account	user-account	user-account	/v1/system/user-account	/v1/user-account	(x/x/x)
system	agent-for	agent-for	agent-for	/v1/system/agent-for	/v1/agent-for	(x/x/x)
system	invitation	invitation	invitation	/v1/system/invitation	/v1/invitation	(x/x/x)

Modules with no public REST Endpoint

Four configured Modules across both components have no *Endpoint.kt class and therefore no row above. They are catalogued for completeness:

Domain	Module	Component	Why no Endpoint
shop-access	pdf-render	operations	Consumed in-pod by Item and Kanban via Kotlin references. The Helm apis: entry exists but no REST handler is registered.
resources	facility	operations	No Module.kt; FacilityService is injected into Kanban / Station at mount time.
resources	station	operations	No Module.kt; StationService is injected into Kanban.
system	batch	operations	No Module.kt; JobService is injected into Item / Kanban for CSV-upload flows.

System APIs

Operations, Administration and Management endpoints.

Tenant

Hosts the Tenant Management Module with API Endpoints for managing organizational units (tenants) within the system.

• Swagger UI: /v1/tenant/docs/openapi/index.html
• OpenAPI 3: /v1/tenant/docs/openApi.json

Method	Path	Summary
POST	/v1/tenant/tenant	Create a new tenant
POST	/v1/tenant/tenant/query	Query tenant entities
GET	/v1/tenant/tenant/query/{page}	Get a specific page of tenant query results
GET	/v1/tenant/tenant/{entity-id}	Get detailed information for a single tenant
PUT	/v1/tenant/tenant/{entity-id}	Update an existing tenant
DELETE	/v1/tenant/tenant/{entity-id}	Delete a tenant
POST	/v1/tenant/tenant/{entity-id}/history	Query the audit history of a tenant
GET	/v1/tenant/tenant/{entity-id}/history/{page}	Get a specific page of a tenant’s audit history

User Account

Manages user accounts, providing endpoints for registration, profile management, and account status tracking.

• Swagger UI: /v1/user-account/docs/openapi/index.html
• OpenAPI 3: /v1/user-account/docs/openApi.json

Method	Path	Summary
POST	/v1/user-account/user-account	Create a new user-account
POST	/v1/user-account/user-account/query	Query user-account entities
GET	/v1/user-account/user-account/query/{page}	Get a specific page of user-account query results
GET	/v1/user-account/user-account/{entity-id}	Get detailed information for a single user-account
PUT	/v1/user-account/user-account/{entity-id}	Update an existing user-account
DELETE	/v1/user-account/user-account/{entity-id}	Delete a user-account
POST	/v1/user-account/user-account/{entity-id}/history	Query the audit history of a user-account
GET	/v1/user-account/user-account/{entity-id}/history/{page}	Get a specific page of a user-account’s audit history

Agent For

Handles the associations between users and the tenants they are authorized to act upon (“Agent For” relationships).

• Swagger UI: /v1/agent-for/docs/openapi/index.html
• OpenAPI 3: /v1/agent-for/docs/openApi.json

Method	Path	Summary
POST	/v1/agent-for/agent-for	Create a new agent-for relationship
POST	/v1/agent-for/agent-for/query	Query agent-for entities
GET	/v1/agent-for/agent-for/query/{page}	Get a specific page of query results
GET	/v1/agent-for/agent-for/{entity-id}	Get detailed information for a single relationship
PUT	/v1/agent-for/agent-for/{entity-id}	Update an existing relationship
DELETE	/v1/agent-for/agent-for/{entity-id}	Delete an agent-for relationship
POST	/v1/agent-for/agent-for/{entity-id}/history	Query the audit history of a relationship
GET	/v1/agent-for/agent-for/{entity-id}/history/{page}	Get a specific page of audit history

Invitation

Manages the lifecycle of invitations sent to potential users to join a tenant.

• Swagger UI: /v1/invitation/docs/openapi/index.html
• OpenAPI 3: /v1/invitation/docs/openApi.json

Method	Path	Summary
POST	/v1/invitation/invitation	Create a new invitation
POST	/v1/invitation/invitation/query	Query invitation entities
GET	/v1/invitation/invitation/query/{page}	Get a specific page of query results
GET	/v1/invitation/invitation/{entity-id}	Get detailed information for an invitation
PUT	/v1/invitation/invitation/{entity-id}	Update an existing invitation, used for all lifecycle operations.
DELETE	/v1/invitation/invitation/{entity-id}	Delete an invitation
POST	/v1/invitation/invitation/{entity-id}/history	Query the audit history of an invitation
GET	/v1/invitation/invitation/{entity-id}/history/{page}	Get a specific page of audit history

Reference Data APIs

Business Affiliate

Manages information about business partners, suppliers, and affiliates, including their assigned roles within the organization.

• Swagger UI: /v1/business-affiliate/docs/openapi/index.html
• OpenAPI 3: /v1/business-affiliate/docs/openApi.json

Method	Path	Summary
POST	/v1/business-affiliate/business-affiliate	Add a new business affiliate
GET	/v1/business-affiliate/business-affiliate/{entity-id}	Get affiliate details by Entity Id
PUT	/v1/business-affiliate/business-affiliate/{entity-id}	Update affiliate information
DELETE	/v1/business-affiliate/business-affiliate/{entity-id}	Delete a business affiliate
POST	/v1/business-affiliate/business-affiliate/query	Query business affiliates
GET	/v1/business-affiliate/business-affiliate/query/{page}	Get a specific page of query results
GET	/v1/business-affiliate/business-affiliate/rid/{entity-record-id}	Get a specific record by its record Id
GET	/v1/business-affiliate/business-affiliate/with-details/{entity-id}	Get affiliate details including all enabled roles
POST	/v1/business-affiliate/business-affiliate/{entity-id}/history	Query affiliate audit history
GET	/v1/business-affiliate/business-affiliate/{entity-id}/history/{page}	Get a specific page of audit history
GET	/v1/business-affiliate/business-affiliate/{entity-id}/roles	Get all business roles associated with an affiliate
POST	/v1/business-affiliate/business-affiliate/{entity-id}/roles	Create a new business role for an affiliate
PUT	/v1/business-affiliate/business-affiliate/{entity-id}/roles/{business-role-eid}	Update an existing business role

Items

Manages the catalog of items, including their properties, supplies, and documentation (labels/breadcrumbs).

• Swagger UI: /v1/item/docs/openapi/index.html
• OpenAPI 3: /v1/item/docs/openApi.json

Method	Path	Summary
POST	/v1/item/item	Add a new item
GET	/v1/item/item/{entity-id}	Get item details by Entity Id
PUT	/v1/item/item/{entity-id}	Update an existing item
DELETE	/v1/item/item/{entity-id}	Delete an item
POST	/v1/item/item/query	Query items
GET	/v1/item/item/query/{page}	Get a specific page of query results
GET	/v1/item/item/rid/{entity-record-id}	Get a specific record by its record Id
GET	/v1/item/item/{entity-id}/draft	Get the current draft for an item
PUT	/v1/item/item/{entity-id}/draft	Update the draft for an item
POST	/v1/item/item/print-label	Request label printing for a list of items
POST	/v1/item/item/print-breadcrumb	Request breadcrumb printing for a list of items
GET	/v1/item/item/{parent-item-id}/supply	Get all supplies associated with an item (legacy alias)
POST	/v1/item/item/{parent-item-id}/supply	Add a new supply to an item (legacy alias)
PUT	/v1/item/item/{parent-item-id}/supply/{item-supply-id}	Update an existing item supply (legacy alias)
DELETE	/v1/item/item/{parent-item-id}/supply/{item-supply-id}	Remove a supply from an item (legacy alias)
GET	/v1/item/lookup-suppliers	Fuzzy search for supplier names
GET	/v1/item/lookup-units	Fuzzy search for unit names
POST	/v1/item/upload-job/upload-url	Generate a URL for CSV upload
GET	/v1/item/upload-job/{job-id}	Get status of a CSV upload job

Item Supply (canonical reference-data routes)

Item supplies are exposed on their own canonical endpoint under the reference-data domain, keyed by the parent item Entity Id. These routes share the same handlers as the legacy /v1/item/item/{parent-item-id}/supply/... aliases listed above; both remain active. The add / update / delete routes accept a mutation-mode query parameter that is retained for compatibility but accepted-and-ignored since 6.0.0 — the former STRICT / LAX values were removed, leaving PROPAGATE canonical create-on-the-fly resolution as the sole mode.

Method	Path	Summary
POST	/v1/reference-data/item/item-supply/supply/{item-eId}/add	Add a new supply to an item
GET	/v1/reference-data/item/item-supply/supply/{item-eId}/list	List all supplies associated with an item
PUT	/v1/reference-data/item/item-supply/supply/{item-eId}/{supply-id}/update	Update an existing item supply
DELETE	/v1/reference-data/item/item-supply/supply/{item-eId}/{supply-id}/delete	Remove a supply from an item (clears any referencing slot first)

Resources APIs

Kanban Cards

Manages Kanban cards used for inventory and process tracking, supporting a full lifecycle of events (request, accept, fulfill, use, etc.).

• Swagger UI: /v1/kanban/docs/openapi/index.html
• OpenAPI 3: /v1/kanban/docs/openApi.json

Method	Path	Summary
POST	/v1/kanban/kanban-card	Add a new Kanban card
GET	/v1/kanban/kanban-card/{entity-id}	Get card details
PUT	/v1/kanban/kanban-card/{entity-id}	Update card information
DELETE	/v1/kanban/kanban-card/{entity-id}	Delete a Kanban card
POST	/v1/kanban/kanban-card/query	Query Kanban cards
GET	/v1/kanban/kanban-card/query/{page}	Get query results page
GET	/v1/kanban/kanban-card/rid/{entity-record-id}	Get specific record by ID
POST	/v1/kanban/kanban-card/details	Query cards and return extended details (including item info)
GET	/v1/kanban/kanban-card/details/{card-eid}	Get extended details for a specific card
GET	/v1/kanban/kanban-card/details/{page}	Get a page of extended details
POST	/v1/kanban/kanban-card/details/{status}	Query detailed cards filtered by status
GET	/v1/kanban/kanban-card/for-item/{item-eid}	Get all cards associated with a specific item
POST	/v1/kanban/kanban-card/summary	Get aggregated status summary of cards
POST	/v1/kanban/kanban-card/summary/requested	Get summary of cards in REQUESTED status
POST	/v1/kanban/kanban-card/summary/in-process	Get summary of cards in IN_PROCESS status
POST	/v1/kanban/kanban-card/print-card	Request printing for a list of cards
PUT	/v1/kanban/kanban-card/{card-eid}/notes	Update private notes/annotations on a card
POST	/v1/kanban/kanban-card/{card-eid}/event/request	Post a REQUEST event
POST	/v1/kanban/kanban-card/{card-eid}/event/accept	Post an ACCEPT event
POST	/v1/kanban/kanban-card/{card-eid}/event/start-processing	Post a START_PROCESSING event
POST	/v1/kanban/kanban-card/{card-eid}/event/complete-processing	Post a COMPLETE_PROCESSING event
POST	/v1/kanban/kanban-card/{card-eid}/event/fulfill	Post a FULFILL event
POST	/v1/kanban/kanban-card/{card-eid}/event/receive	Post a RECEIVE event
POST	/v1/kanban/kanban-card/{card-eid}/event/use	Post a USE event
POST	/v1/kanban/kanban-card/{card-eid}/event/deplete	Post a DEPLETE event
POST	/v1/kanban/kanban-card/{card-eid}/event/withdraw	Post a WITHDRAW event

Procurement APIs

Orders

Manages the procurement order lifecycle, from creation (optionally from Items or Kanban cards) to submission and receiving.

• Swagger UI: /v1/order/docs/openapi/index.html
• OpenAPI 3: /v1/order/docs/openApi.json

Method	Path	Summary
POST	/v1/order/order	Create a new order
GET	/v1/order/order/{entity-id}	Get header details
PUT	/v1/order/order/{entity-id}	Update order header
DELETE	/v1/order/order/{entity-id}	Delete an order
POST	/v1/order/order/query	Query orders
GET	/v1/order/order/query/{page}	Get query results page
GET	/v1/order/order/full/{entity-id}	Get full order including all line items
GET	/v1/order/order/full/rid/{entity-record-id}	Get full order by specific record ID
POST	/v1/order/order/from-items	Create a new order from a list of items
PUT	/v1/order/order/from-items/{entity-id}	Add lines to existing order from items
POST	/v1/order/order/from-kanban-cards	Create a new order from a list of Kanban cards
PUT	/v1/order/order/from-kanban-cards/{entity-id}	Add lines to existing order from Kanban cards
POST	/v1/order/order/{entity-id}/lines	Add a free-form line to an order
PUT	/v1/order/order/{entity-id}/lines/{order-line-eid}	Update an existing order line
DELETE	/v1/order/order/{entity-id}/lines/{order-line-eid}	Remove a line from an order
PUT	/v1/order/order/{entity-id}/lines/move-line/{order-line-eid}	Change the position of an order line
PUT	/v1/order/order/{entity-id}/submit	Transition order to SUBMITTED status
PUT	/v1/order/order/{entity-id}/accepted	Mark order as ACCEPTED by supplier
PUT	/v1/order/order/{entity-id}/receive	Record receiving against order lines
PUT	/v1/order/order/{entity-id}/archive	Archive a completed order
PUT	/v1/order/order/{entity-id}/annotate	Add a private note to the order
PUT	/v1/order/order/{entity-id}/annotate-line/{order-line-eid}	Add a private note to a specific line

Shop Access APIs

PDF Render

In-pod printing capability. Consumed by Item (label and breadcrumb printing) and Kanban (card printing) through Kotlin references; no public REST surface today despite the catalog entry. The Swagger UI link is reserved.

API	Swagger UI
PDF Render	https://stage.alpha002.io.arda.cards/v1/pdf-render/docs/openapi/index.html

Email

Per-tenant email sending capability provided by the ShopAccess/Email Module. Three Endpoints, in the canonical URL shape per Functional Decomposition. The Module covers tenant provisioning, transactional sending, and ingestion of Postmark webhook events (delivery, bounce, complaint, open, click).

• Swagger UI (Configuration): /v1/shop-access/email/configuration/docs/openapi/index.html
• Swagger UI (Job): /v1/shop-access/email/job/docs/openapi/index.html
• Swagger UI (Postmark Events): /v1/shop-access/email/job/postmark-events/docs/openapi/index.html

Configuration Endpoint

DataAuthority over the per-tenant EmailConfiguration entity, extended with operator-signal sub-routes that drive the configuration’s two-region (Operational + Administrative) lifecycle state engine.

Method	Path	Summary
POST	/v1/shop-access/email/configuration	Create a new email configuration for a tenant
GET	/v1/shop-access/email/configuration/{entity-id}	Get configuration by Entity Id
PUT	/v1/shop-access/email/configuration/{entity-id}	Update an existing configuration
DELETE	/v1/shop-access/email/configuration/{entity-id}	Remove a configuration (lifecycle terminal)
POST	/v1/shop-access/email/configuration/query	Query configurations
GET	/v1/shop-access/email/configuration/query/{page}	Get a specific page of query results
POST	/v1/shop-access/email/configuration/{entity-id}/signals/provision	Drive the Operational region into PROVISIONING
POST	/v1/shop-access/email/configuration/{entity-id}/signals/re-provision	Restart provisioning from a recoverable failure
POST	/v1/shop-access/email/configuration/{entity-id}/signals/re-verify	Re-run Sender Signature verification after a DNS fix
POST	/v1/shop-access/email/configuration/{entity-id}/signals/restore	Restore a FAILED configuration to DEGRADED
POST	/v1/shop-access/email/configuration/{entity-id}/signals/lock	Graceful lock (drains in-flight sends)
POST	/v1/shop-access/email/configuration/{entity-id}/signals/force-lock	Force lock (cancels in-flight sends)
POST	/v1/shop-access/email/configuration/{entity-id}/signals/unlock	Unlock the Administrative region
POST	/v1/shop-access/email/configuration/{entity-id}/history	Query the audit history of a configuration
GET	/v1/shop-access/email/configuration/{entity-id}/history/{page}	Get a specific page of audit history

Job Endpoint

DataAuthority over the EmailJob entity. Send operations carry a caller-supplied Idempotency-Key. The job-full sub-resource returns the EmailJob plus its associated EmailEvent rows (delivery, bounce, complaint, open, click) in one read.

Method	Path	Summary
POST	/v1/shop-access/email/job	Submit a transactional send (Idempotency-Key required)
GET	/v1/shop-access/email/job/{entity-id}	Get an EmailJob by Entity Id
POST	/v1/shop-access/email/job/query	Query EmailJobs
GET	/v1/shop-access/email/job/query/{page}	Get a specific page of query results
GET	/v1/shop-access/email/job/rid/{entity-record-id}	Get a specific record by its Record Id
GET	/v1/shop-access/email/job/job-full/by-eid/{entity-id}	Get the EmailJob plus its EmailEvents by Entity Id
GET	/v1/shop-access/email/job/job-full/by-rid/{entity-record-id}	Get the EmailJob plus its EmailEvents by Record Id
POST	/v1/shop-access/email/job/{entity-id}/history	Query the audit history of an EmailJob
GET	/v1/shop-access/email/job/{entity-id}/history/{page}	Get a specific page of audit history

Postmark Events Endpoint

Ingests Postmark’s transactional-stream webhooks. The {tenant-hash} path segment carries a SHA-256 of the tenant identifier; the in-pod handler verifies the bearer token and the hash. The Endpoint never returns 403 (Postmark interprets 403 as a permanent failure and stops retrying).

Method	Path	Summary
POST	/v1/shop-access/email/job/postmark-events/{tenant-hash}	Receive a Postmark webhook event (Delivery, Bounce, SpamComplaint, Open, Click, SubscriptionChange) for the tenant identified by {tenant-hash}