REST API Reference

All endpoints are under /v1/ and return JSON. Every request must be authenticated with a Bearer token — see Authentication.

Base URL

https://api.atrope.dev

Request conventions

Pagination — list endpoints accept query parameters:

Parameter	Default	Description
`limit`	`50`	Max records to return
`offset`	`0`	Number of records to skip
`q`	—	Full-text search term

Response envelope — lists return:

{
  "data": [...],
  "count": 12,
  "limit": 50,
  "offset": 0
}

Single-item responses return:

{
  "data": { ... }
}

Health

`GET /health`

Returns service health. Does not require authentication.

curl https://api.atrope.dev/health

{
  "service": "ims-api",
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-05-15T10:00:00Z"
}

Catalog

`GET /v1/items`

List all items. Supports q search against item name and item number.

`POST /v1/items`

Create a new item.

{
  "itemNo": "TBL-NOTE-08",
  "name": "Notebook A5",
  "itemKind": "purchased",
  "baseUomId": "uom_uuid",
  "lotTracking": "tracked",
  "serialTracking": "none",
  "expiryTracking": "none",
  "isActive": true
}

`GET /v1/items/{itemId}`

Get a single item with identifiers, attributes, and UOM conversions.

Inventory

`GET /v1/inventory/balances`

Returns on-hand quantities broken down by item, location, lot, and stock status.

`GET /v1/inventory/availability`

Returns net available quantities per item and location (Available status only).

`GET /v1/inventory/transactions`

Returns the inventory ledger — all posted stock movements. Supports filtering by item, facility, date range.

`GET /v1/inventory/transactions/{transactionId}`

Get a single ledger transaction with all line details.

`POST /v1/inventory/adjustments`

Post a manual stock adjustment directly to the ledger.

{
  "itemId": "...",
  "locationId": "...",
  "statusId": "...",
  "qtyDelta": -5,
  "reason": "Damaged in storage"
}

Reservations & Allocations

`GET /v1/inventory/reservations`

List active inventory reservations.

`POST /v1/inventory/reservations`

Create a reservation — soft-holds stock against a demand document.

`PATCH /v1/inventory/reservations/{reservationId}`

Update an open reservation.

`POST /v1/inventory/reservations/{reservationId}/allocate`

Hard-allocate reserved stock to a specific lot or location.

`POST /v1/inventory/reservations/{reservationId}/release`

Release a reservation without fulfilling it.

`POST /v1/inventory/reservations/{reservationId}/cancel`

Cancel a reservation.

`POST /v1/inventory/reservations/{reservationId}/fulfill`

Mark a reservation fulfilled after shipment.

`GET /v1/inventory/allocations`

List all hard allocations.

Transfers

`GET /v1/inventory/transfers`

List inter-facility transfer orders.

`GET /v1/inventory/transfers/{transferId}`

Get a transfer order with all lines.

Cycle Counts

`GET /v1/inventory/count-sessions`

List cycle count sessions.

Reorder Policies

`GET /v1/inventory/policies`

List reorder policies (min/max, safety stock) by item and facility.

Facilities

`GET /v1/facilities`

List all facilities.

`GET /v1/facilities/{facilityId}/locations`

List the location tree for a facility.

Procurement

`GET /v1/procurement/suppliers`

List supplier parties.

Purchase Orders

Method	Path	Description
`GET`	`/v1/procurement/purchase-orders`	List POs
`POST`	`/v1/procurement/purchase-orders`	Create a PO
`GET`	`/v1/procurement/purchase-orders/{id}`	Get a PO with lines
`PATCH`	`/v1/procurement/purchase-orders/{id}`	Update a draft PO
`POST`	`/v1/procurement/purchase-orders/{id}/submit`	Submit for approval
`POST`	`/v1/procurement/purchase-orders/{id}/approve`	Approve a PO
`POST`	`/v1/procurement/purchase-orders/{id}/send`	Mark sent to supplier
`POST`	`/v1/procurement/purchase-orders/{id}/cancel`	Cancel a PO

Receipts

Method	Path	Description
`GET`	`/v1/procurement/purchase-orders/{id}/receipts`	List receipts for a PO
`POST`	`/v1/procurement/purchase-orders/{id}/receipts`	Record a goods receipt

Requisitions

Method	Path	Description
`GET`	`/v1/procurement/requisitions`	List requisitions
`POST`	`/v1/procurement/requisitions`	Create a requisition
`GET`	`/v1/procurement/requisitions/{id}`	Get a requisition
`PATCH`	`/v1/procurement/requisitions/{id}`	Update a requisition
`POST`	`/v1/procurement/requisitions/{id}/submit`	Submit for approval
`POST`	`/v1/procurement/requisitions/{id}/approve`	Approve

Sales

Method	Path	Description
`GET`	`/v1/sales/orders`	List sales orders
`POST`	`/v1/sales/orders`	Create a sales order
`GET`	`/v1/sales/orders/{id}`	Get a sales order with lines
`PATCH`	`/v1/sales/orders/{id}`	Update a draft order
`POST`	`/v1/sales/orders/{id}/open`	Open an order for fulfillment
`POST`	`/v1/sales/orders/{id}/ship`	Record a shipment
`POST`	`/v1/sales/orders/{id}/cancel`	Cancel an order

Production

Bills of Materials

Method	Path	Description
`GET`	`/v1/production/boms`	List BOMs
`POST`	`/v1/production/boms`	Create a BOM
`GET`	`/v1/production/boms/{id}`	Get a BOM with components
`PATCH`	`/v1/production/boms/{id}`	Update a BOM
`POST`	`/v1/production/boms/{id}/activate`	Activate a BOM version

Work Orders

Method	Path	Description
`GET`	`/v1/production/work-orders`	List work orders
`POST`	`/v1/production/work-orders`	Create a work order
`GET`	`/v1/production/work-orders/{id}`	Get a work order
`POST`	`/v1/production/work-orders/{id}/release`	Release to production floor
`POST`	`/v1/production/work-orders/{id}/complete`	Complete and post output
`POST`	`/v1/production/work-orders/{id}/cancel`	Cancel

Error responses

{
  "error": "not_found",
  "message": "Item not found",
  "status": 404
}

Status	Meaning
`400`	Bad request — validation error
`401`	Missing or invalid token
`403`	Token lacks required permission
`404`	Resource not found
`409`	Conflict — e.g. duplicate item number
`503`	Service unavailable — database unreachable