API Documentation
Inventory Management System Backend
The live API is mounted under /api. Client sign-in happens
directly with Cognito, while this backend handles token verification,
session resolution, organization workflows, inventory operations, and a
deprecated compatibility layer for older backend-managed auth routes.
Base Paths
GET /Documentation landing page.GET /agentsAgent-facing integration handoff for client builders.GET /authDocumentation for authentication routes.GET /usersDocumentation for user routes.GET /organizationsDocumentation for organization routes.GET /categoriesDocumentation for category routes.GET /productsDocumentation for product routes.GET /inventoryDocumentation for inventory routes.GET /metricsDocumentation for metric catalog, definitions, previews, and inventory aggregate routes.GET /alertsDocumentation for alert definition and alert record routes.GET /api/healthBackend and database health check.
Agent Handoff
GET /agentsAgent-facing notes for building or adapting a client against the live backend.
Authentication
GET /api/auth/accountsProtected account listing. Accepts Cognito or backend bearer tokens.GET /api/auth/permissionsProtected canonical permission catalog with integer ids.GET /api/auth/cognitoCognito status for the preferred direct client auth flow.POST /api/auth/cognito/refreshRefresh Cognito access and ID tokens using a refresh token.POST /api/auth/cognito/verifyVerify a Cognito access token without changing local state.POST /api/auth/cognito/resolveVerify Cognito tokens and resolve or provision the local account session.POST /api/auth/cognito/loginDeprecated backend-mediated Cognito login retained only for compatibility.POST /api/auth/cognito/registerDeprecated backend-mediated Cognito registration retained only for compatibility.POST /api/auth/backend/loginDeprecated local backend login retained only for compatibility.POST /api/auth/backend/registerDeprecated local backend registration retained only for compatibility.POST /api/auth/loginDeprecated alias for local backend login.
Users and Organizations
PATCH /api/users/meUpdate the authenticated user's profile fields.GET /api/organizations/meGet the authenticated user's current organization summary, including org-wide stock thresholds.GET /api/organizations/me/membersList members in the authenticated user's current organization.GET /api/organizations/me/members/countGet the member count for the authenticated user's current organization.GET /api/organizations/me/rolesList assignable organization roles in the current organization.GET /api/organizations/me/permissionsGet the assignable organization permission catalog.POST /api/organizations/me/rolesCreate a new role in the current organization.PATCH /api/organizations/me/members/:accountIdUpdate a member's role assignment in the current organization.POST /api/organizationsCreate a new organization and switch the current account into it as owner.PATCH /api/organizations/:organizationIdUpdate the authenticated user's current organization name and stock thresholds.DELETE /api/organizations/:organizationIdDelete the authenticated user's current organization when allowed.
Metrics
GET /api/metrics/catalogGet the backend base-metric catalog available for custom formula definitions.GET /api/metrics/definitionsList the current organization's custom metric definitions.GET /api/metrics/definitions/:metricIdGet one custom metric definition by id.POST /api/metrics/definitionsCreate a custom metric definition from validated formula JSON.PATCH /api/metrics/definitions/:metricIdUpdate an existing metric definition.DELETE /api/metrics/definitions/:metricIdDelete an existing metric definition.POST /api/metrics/definitions/previewPreview a metric definition against live base metrics without persisting it.GET /api/metrics/inventory/overviewGet inventory overview metrics with optional dashboard filters and threshold overrides; otherwise org thresholds are used.GET /api/metrics/inventory/movement-trendGet daily inbound and outbound movement metrics with `days`, optional dashboard filters, and org-default threshold behavior.GET /api/metrics/inventory/movement-summaryGet org-wide or per-product movement totals with optional filters; threshold-sensitive filters default to org settings.GET /api/metrics/inventory/category-breakdownGet inventory value breakdown by category with `top`, optional filters, and org-default threshold behavior.
Alerts
GET /api/alerts/definitionsList organization-scoped alert definitions backed by validated condition JSON.GET /api/alerts/definitions/:alertDefinitionIdGet one alert definition by id.POST /api/alerts/definitionsCreate an alert definition. Evaluation engine status is currently stubbed.PATCH /api/alerts/definitions/:alertDefinitionIdUpdate an existing alert definition. Evaluation engine status is currently stubbed.DELETE /api/alerts/definitions/:alertDefinitionIdDelete an alert definition from the current organization scope.GET /api/alertsList alert records and sync active alert definitions into persisted alerts before returning results.GET /api/alerts/:alertIdGet one persisted alert record by id.POST /api/alertsCreate a persisted alert record. Productless records are allowed only for custom definition-linked alerts.PATCH /api/alerts/:alertIdUpdate an alert record and acknowledge it when status becomes acknowledged.DELETE /api/alerts/:alertIdDelete an alert record from the current organization scope.
Products, Categories, and Inventory
GET /api/categoriesList categories.GET /api/categories/:categoryIdGet a category.POST /api/categoriesCreate a category.PUT /api/categories/:categoryIdUpdate a category.DELETE /api/categories/:categoryIdDelete a category.GET /api/productsList products.GET /api/products/:productIdGet a product.POST /api/uploads/products/presignCreate a presigned S3 upload URL for product images.POST /api/productsCreate a product.PUT /api/products/:productIdUpdate a product.DELETE /api/products/:productIdDelete a product.GET /api/inventory/movements/typesGet the supported stock movement type catalog.GET /api/inventoryInventory snapshot alias.GET /api/inventory/summaryInventory snapshot.POST /api/inventory/adjustmentsRecord a manual inventory adjustment with a required persisted reason.GET /api/inventory/movementsList stock movements.POST /api/inventory/movementsRecord stock movement with an optional persisted reason.GET /api/inventory/:productIdGet inventory for a single product.POST /api/inventoryCreate an inventory record.PATCH /api/inventory/:productIdUpdate inventory for a product.DELETE /api/inventory/:productIdDelete inventory for a product.