REST API
The warecache server exposes a REST API for managing parts, BOMs, projects, containers,
sensors, distributors, production orders, and user accounts.
The full OpenAPI specification is available at your server's /apidoc/openapi.json endpoint.
A demo instance is available at demo.warecache.com/apidoc/openapi.json.
Authentication
The API supports two authentication methods:
- Username/Password: POST to
/auth/login with credentials to receive a JWT token.
- OIDC: If configured, authenticate via an external identity provider using the
/auth/oidc/ endpoints.
- API Tokens: Create long-lived tokens via
/api/v1/tokens for programmatic access.
Include the token in the Authorization header:
Authorization: Bearer <token>
Endpoints
Authentication
| Method |
Path |
Description |
| POST |
/auth/login |
Login to user account |
| GET |
/auth/methods |
List available authentication methods |
| POST |
/auth/oidc/{provider}/callback |
Handle OIDC authorization code callback |
| POST |
/auth/oidc/{provider}/device |
Initiate OIDC device authorization flow |
| POST |
/auth/oidc/{provider}/device/token |
Poll for device authorization token |
| GET |
/auth/oidc/{provider}/login |
Initiate OIDC login flow |
Users
| Method |
Path |
Description |
| GET |
/api/v1/users |
Get all users in system |
| POST |
/api/v1/users |
Create new user |
| GET |
/api/v1/users/{uname} |
Get user by username |
| PUT |
/api/v1/users/{uname} |
Edit user account |
| DELETE |
/api/v1/users/{uname} |
Delete user account |
| GET |
/api/v1/users/{uname}/auth-methods |
List a user's linked auth methods |
| POST |
/api/v1/users/{uname}/auth-methods |
Manually link an OIDC identity to a user |
| DELETE |
/api/v1/users/{uname}/auth-methods/{method_id} |
Unlink an OIDC identity from a user |
| PUT |
/api/v1/users/{uname}/passwd |
Change user password |
| PUT |
/api/v1/users/{uname}/role |
Assign role to user |
API Tokens
| Method |
Path |
Description |
| GET |
/api/v1/tokens |
List API tokens for current user |
| POST |
/api/v1/tokens |
Create a new API token |
| DELETE |
/api/v1/tokens/{label} |
Revoke an API token by label |
Parts
| Method |
Path |
Description |
| GET |
/api/v1/parts/{ptype} |
Get all parts for a given part type |
| POST |
/api/v1/parts/{ptype} |
Create new part |
| GET |
/api/v1/parts/{ptype}/{ipn} |
Get specific part |
| PUT |
/api/v1/parts/{ptype}/{ipn} |
Edit specific part |
| DELETE |
/api/v1/parts/{ptype}/{ipn} |
Delete specific part |
| POST |
/api/v1/parts/batch |
Get multiple parts by type and IPN |
| GET |
/api/v1/parts/search/{mpn} |
Search for parts by MPN across all part types |
| GET |
/api/v1/parts/{ptype}/{ipn}/alternates |
Get alternate parts for a specific part |
| POST |
/api/v1/parts/{ptype}/{ipn}/alternates |
Add an alternate part link |
| DELETE |
/api/v1/parts/{ptype}/{ipn}/alternates/{alt_ipn} |
Remove an alternate part link |
| GET |
/api/v1/parts/{ptype}/{ipn}/distributors |
Get all distributors for a specific part |
| GET |
/api/v1/parts/{ptype}/{ipn}/history |
Get stock history for a part across all sensors |
Part Types
| Method |
Path |
Description |
| GET |
/api/v1/part_types |
Get all part types |
| POST |
/api/v1/part_types |
Create new part type |
| GET |
/api/v1/part_types/{id} |
Get part type by ID |
| DELETE |
/api/v1/part_types/{id} |
Delete part type |
| GET |
/api/v1/part_types/{id}/info_keys |
Get info field keys for a part type |
BOMs
| Method |
Path |
Description |
| GET |
/api/v1/boms |
Get all BOMs |
| POST |
/api/v1/boms |
Create new BOM |
| POST |
/api/v1/boms/batch |
Get multiple BOMs by IPN |
| POST |
/api/v1/boms/versions/batch |
Get multiple BOM versions by IPN and version |
| GET |
/api/v1/boms/{ipn} |
Get BOM for a given IPN |
| PUT |
/api/v1/boms/{ipn} |
Edit specific BOM |
| DELETE |
/api/v1/boms/{ipn} |
Delete specific BOM |
| GET |
/api/v1/boms/{ipn}/version |
Get all versions for a specific BOM |
| GET |
/api/v1/boms/{ipn}/version/{vnum} |
Retrieve BOM version |
| POST |
/api/v1/boms/{ipn}/version/{vnum} |
Add a new version to a specific BOM |
| DELETE |
/api/v1/boms/{ipn}/version/{vnum} |
Delete a version from a specific BOM |
Projects
| Method |
Path |
Description |
| GET |
/api/v1/prjs |
Get all projects |
| POST |
/api/v1/prjs |
Create new project |
| POST |
/api/v1/prjs/batch |
Get multiple projects by IPN |
| POST |
/api/v1/prjs/versions/batch |
Get multiple project versions by IPN and version |
| GET |
/api/v1/prjs/{ipn} |
Get project from IPN |
| PUT |
/api/v1/prjs/{ipn} |
Edit specific project |
| DELETE |
/api/v1/prjs/{ipn} |
Delete specific project |
| GET |
/api/v1/prjs/{ipn}/version |
Get all versions for a specific project |
| GET |
/api/v1/prjs/{ipn}/version/{vnum} |
Retrieve project version |
| POST |
/api/v1/prjs/{ipn}/version/{vnum} |
Add a new version to a specific project |
| DELETE |
/api/v1/prjs/{ipn}/version/{vnum} |
Delete a version from a specific project |
Containers
| Method |
Path |
Description |
| GET |
/api/v1/containers |
Get all containers with full type info and sensor grid |
| PUT |
/api/v1/containers |
Register new container, return certificates |
| POST |
/api/v1/containers/batch |
Get multiple containers by serial number |
| GET |
/api/v1/containers/flat |
Get all containers (flat, without sensor grid) |
| GET |
/api/v1/containers/{sn} |
Get container with full type info and sensor grid |
| PUT |
/api/v1/containers/{sn} |
Edit container |
| DELETE |
/api/v1/containers/{sn} |
Delete container |
| GET |
/api/v1/containers/{sn}/flat |
Get container (flat, without sensor grid) |
Container Types
| Method |
Path |
Description |
| GET |
/api/v1/container_types |
Get all container types |
| POST |
/api/v1/container_types |
Create new container type |
| GET |
/api/v1/container_types/{id} |
Get container type by ID |
| DELETE |
/api/v1/container_types/{id} |
Delete container type |
Sensors
| Method |
Path |
Description |
| GET |
/api/v1/sensors |
Get all sensors |
| POST |
/api/v1/sensors/batch |
Get multiple sensors by serial number |
| GET |
/api/v1/sensors/{sn} |
Get specific sensor |
| POST |
/api/v1/sensors/{sn} |
Register sensor and assign part |
| PUT |
/api/v1/sensors/{sn} |
Unregister sensor |
| DELETE |
/api/v1/sensors/{sn} |
Reset sensor |
Sensor Types
| Method |
Path |
Description |
| GET |
/api/v1/sensor_types |
Get all sensor types |
| POST |
/api/v1/sensor_types |
Create new sensor type |
| GET |
/api/v1/sensor_types/{id} |
Get sensor type by ID |
| DELETE |
/api/v1/sensor_types/{id} |
Delete sensor type |
Distributors
| Method |
Path |
Description |
| GET |
/api/v1/distributors |
Get all distributors |
| POST |
/api/v1/distributors |
Create new distributor |
| GET |
/api/v1/distributors/{id} |
Get distributor by ID |
| PUT |
/api/v1/distributors/{id} |
Edit distributor |
| DELETE |
/api/v1/distributors/{id} |
Delete distributor |
| GET |
/api/v1/distributors/{id}/discover-fields |
Discover distributor field names per part type |
| GET |
/api/v1/distributors/{id}/field-mappings |
Get all field mappings for a distributor |
| POST |
/api/v1/distributors/{id}/field-mappings |
Create field mappings for a distributor |
| PUT |
/api/v1/distributors/{id}/field-mappings |
Edit a field mapping |
| DELETE |
/api/v1/distributors/{id}/field-mappings |
Delete a field mapping |
| GET |
/api/v1/distributors/{id}/field-mappings/{ptype_id} |
Get field mappings for a distributor filtered by part type |
| GET |
/api/v1/distributors/{id}/parts |
Get all parts for a distributor |
| POST |
/api/v1/distributors/{id}/parts |
Create distributor part mapping |
| GET |
/api/v1/distributors/{id}/parts/{part_id} |
Get specific distributor part |
| DELETE |
/api/v1/distributors/{id}/parts/{part_id} |
Delete distributor part mapping |
| POST |
/api/v1/distributors/{id}/sync |
Trigger immediate sync for a distributor |
Production
| Method |
Path |
Description |
| GET |
/api/v1/production/orders |
Get all production orders |
| POST |
/api/v1/production/orders |
Create new production order |
| POST |
/api/v1/production/orders/batch |
Get multiple production orders by ID |
| GET |
/api/v1/production/orders/{id} |
Get production order by ID |
| DELETE |
/api/v1/production/orders/{id} |
Delete production order |
| PUT |
/api/v1/production/orders/{id}/lines |
Update production order lines (Draft only) |
| GET |
/api/v1/production/orders/{id}/status |
Get production order status |
| PUT |
/api/v1/production/orders/{id}/status |
Update production order status |
| GET |
/api/v1/production/produced |
Get all produced projects |
| GET |
/api/v1/production/produced/orphaned |
Get orphaned produced projects (completed items on cancelled orders) |
| GET |
/api/v1/production/produced/{id} |
Get produced project by ID |
| PUT |
/api/v1/production/produced/{id} |
Mark produced project as completed |
| PUT |
/api/v1/production/produced/{id}/reassign |
Reassign a completed produced project to a different order |
| GET |
/api/v1/production/sources |
Get all order sources |
| POST |
/api/v1/production/sources |
Create new order source |
| POST |
/api/v1/production/sources/batch |
Get multiple order sources by name |
| GET |
/api/v1/production/sources/{name} |
Get order source by name |
| PUT |
/api/v1/production/sources/{name} |
Edit order source |
| DELETE |
/api/v1/production/sources/{name} |
Delete order source |
Changelog
| Method |
Path |
Description |
| GET |
/api/v1/changelog |
Get recent changelog entries |
| GET |
/api/v1/changelog/since/{timestamp} |
Get changelog entries since a timestamp |
Status
| Method |
Path |
Description |
| GET |
/api/v1/status/workers |
Get current state of all background worker threads |
Health Check
| Method |
Path |
Description |
| GET |
/server/health_check |
Server health check |