API Overview

The OpenBoxes REST API provides programmatic access to your supply chain data hosted on OpenBoxes Lift. Use it to integrate with ERPs, build custom dashboards, automate workflows, and synchronize inventory across systems.

Base URL

All API requests are scoped to your tenant subdomain:

https://{subdomain}.openboxes.cloud/openboxes/api

For example, if your instance is acme.openboxes.cloud, your base URL is:

https://acme.openboxes.cloud/openboxes/api

Request Format

The API accepts and returns JSON. Include the following headers with every request:

Header Value Required
Content-Type application/json Yes (POST/PUT)
Accept application/json Recommended
Cookie JSESSIONID=... Yes (after login)

Response Format

Successful responses return JSON with an HTTP 200 status. Most list endpoints return an array of objects:

{
  "data": [
    { "id": "abc123", "name": "Ibuprofen 200mg" },
    { "id": "def456", "name": "Paracetamol 500mg" }
  ]
}

Single-resource endpoints return the object directly:

{
  "data": {
    "id": "abc123",
    "name": "Ibuprofen 200mg",
    "productCode": "IBU200"
  }
}

Error Responses

When a request fails, the API returns an appropriate HTTP status code with error details:

{
  "errorCode": 400,
  "errorMessage": "Validation failed",
  "errors": [
    { "field": "name", "message": "Property [name] cannot be null" }
  ]
}

Common error codes:

Status Code Meaning
302 Session expired -- redirecting to login page
400 Bad request -- missing or invalid parameters
401 Unauthorized -- invalid or missing session
403 Forbidden -- insufficient permissions
404 Not found -- resource does not exist
429 Rate limit exceeded
500 Internal server error

Note: Some endpoints return a 302 redirect to the login page instead of a 401 when the session is invalid. Always check for redirect responses and re-authenticate when encountered.

Pagination

List endpoints support pagination via query parameters:

Parameter Type Default Description
offset integer 0 Number of records to skip
max integer all Maximum number of records to return

Example -- fetch products 21 through 30:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/products?offset=20&max=10"

Known Limitation: Pagination behavior is inconsistent across some endpoints. The /api/locations endpoint ignores the max parameter and always returns all results. Test pagination behavior for each endpoint you use.

API Versioning

The current API does not use explicit version numbers in the URL path. All endpoints are accessed under /openboxes/api/. Breaking changes are communicated via release notes and the Lift platform changelog.

Rate Limiting

All API requests are subject to rate limits based on your Lift subscription tier:

Tier Requests per Hour
Shared 1,000
Dedicated 25,000
Enterprise Custom

Rate limit status is returned in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1700000000

When you exceed the limit, the API returns HTTP 429 Too Many Requests. See the Rate Limits page for best practices.

Content Types

The API works exclusively with JSON. XML or form-encoded requests are not supported on API endpoints. Always set:

Content-Type: application/json

Next Steps