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/api/v1

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

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

Request Format

The API accepts and returns JSON. Authenticate every request with the X-API-Key header (see Authentication). Include the following headers with every request:

Header Value Required
X-API-Key YOUR_API_KEY Yes
Content-Type application/json Yes (POST/PUT)
Accept application/json Recommended

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
400 Bad request -- missing or invalid parameters
401 Unauthorized -- invalid or missing API key
403 Forbidden -- key not valid for this tenant, or insufficient scope
404 Not found -- resource does not exist
429 Rate limit exceeded
500 Internal server error

Note: A 403 is returned when an API key is used against a subdomain it does not belong to -- keys are scoped to a single tenant. See Authentication.

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 -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products?offset=20&max=10"

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

API Versioning

All endpoints are accessed under the /api/v1/ path prefix on your tenant subdomain. Breaking changes are introduced behind a new version prefix; non-breaking additions 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