# API

<figure><img src="/files/JyueyATk5C0847NUI08W" alt=""><figcaption></figcaption></figure>

***

## **API Reference**

For detailed endpoint documentation, please visit: <https://rest.boxhero.io/docs/api>

***

## Endpoint

All API requests should be directed to the following base URL:\ <mark style="color:blue;"><https://rest.boxhero-app.com></mark>

## **Authentication**

All API requests must include an **Authorization** **header** with a **Bearer** **token**:

```
Authorization: Bearer {API_TOKEN}
```

To obtain an API token:

1. Log into your BoxHero account on the Desktop (Web).
2. Navigate to <mark style="color:blue;">`Settings`</mark> > <mark style="color:blue;">`Integrations`</mark>.
3. Generate a new API token.

## **Making Requests**

Here's a sample API request to retrieve products.

```bash
curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'
```

## Rate Limits

To ensure system stability, we impose the following rate limits:

* 5 queries per second for each endpoint.

Once you are rate limited, you will see an error message with the following:

* `X-Ratelimit-Limit` - Maximum queries per minute
* `X-Ratelimit-Remaining` - Remaining queries
* `X-Ratelimit-Reset` - Time (in seconds) remaining until query count reset

***

## Responses

### Success

Responses with HTTP status codes in the 200 range indicate successful API processing.

### Error

Status codes in the 400 or 500 range indicate API request failures:

* 400 range: Client-side error from information provided with the request (e.g., missing required parameters).
* 500 range: Server-side error.

**Example Error Response:**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Authentication token is invalid. Please provide a valid token.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

* **id :** A unique ID to identify the error.
* **type :** A code in the form of a URL that identifies the type of error.
* **title :** Provide the contents of the error in human-readable form.
* **correlation\_id :** Points to the ID of the request associated with the error.
* **others :** Additional fields may be included to provide additional information, such as "*given*" in the example.

### Common Error Types

<table><thead><tr><th width="252">Type</th><th>Description</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Requested resource not found (e.g., item with a specific ID does not exist).</td></tr><tr><td>/errors/invalid-request</td><td>Invalid parameters in request.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Requested query cannot be processed in current team mode (e.g., using the <em>location</em> lookup API in <em>Basic Mode</em>).</td></tr><tr><td>/errors/tokens/required</td><td>Missing API token.</td></tr><tr><td>/errors/tokens/invalid</td><td>Invalid API token (e.g., API token has expired).</td></tr><tr><td>/errors/too-many-requests</td><td>Exceeded the rate limit.</td></tr><tr><td>/errors/unhandled</td><td>Unresolved server-side error.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Reached usage limit. Plan upgrade required.</td></tr></tbody></table>

## Pagination

For endpoints returning large datasets (e.g., item lists, transaction lists), the list view API limits the number of items returned in a single request through pagination. We use cursor-based pagination:

{% hint style="info" %}
To determine if pagination is required, check whether pagination-related parameters are present in the request body of the endpoint in the API documentation.
{% endhint %}

#### **Pagination Parameters**

* `has_more` : A boolean that indicates whether more data exists beyond the current page.
* `cursor` : Provides the cursor value for retrieving the next page.

#### **Retrieving the Next Page**

* Check if `has_more` is `true`. It means there’s another page available.
* If `true`, send another request including `cursor={received cursor value}` in the parameters. This will return the subsequent data.
* Repeat until `has_more` is `false` to retrieve the full list.

***

## Support and Feedback

If you encounter issues or need additional API functionality, please contact our [support team](https://docs-en.boxhero.io/etc/contact). We welcome your feedback for API improvements and new feature requests.

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/integrations/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.