> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buylo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Everything you need to start integrating with the Buylo API.

## Overview

The Buylo API gives you programmatic access to your retail management platform. Use it to register products, manage RFID tag assignments, sync inventory, and integrate Buylo into your existing systems and workflows.

The API is built around standard HTTP conventions and returns JSON responses. It is designed to be predictable and easy to integrate — whether you are connecting a WMS, an ERP, or building a custom automation.

**Base URL**

```
https://api.buylo.app/
```

### What you can do with the API

* Register and update products in your Buylo
* Assign and manage RFID tags linked to specific products
* Query inventory state and tag read history
* Trigger and monitor antenna hooks and RFID events
* Sync data with external ERP or WMS systems

***

## Authentication

All API requests must be authenticated using an API token. Tokens are generated and managed from the Buylo administration panel under **Settings → API Tokens**. There is no OAuth flow — authentication is straightforward Bearer token auth.

### Generating a token

1. Log in to your Buylo administration account.
2. Navigate to **Settings → API Tokens**.
3. Click **Generate new token** and give it a descriptive name (e.g. `Production ERP`, `Staging test`).
4. Copy the token immediately — it will not be shown again.
5. Set an expiration date and store the token securely.

### Using your token

Include the token in the `Authorization` header of every request:

```http theme={null}
GET /v1/products HTTP/1.1
Host: api.buylo.app
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

### Token lifecycle

* Tokens are scoped to your tenant — they cannot access data from other organizations.
* Each token has a configurable expiration date. Expired tokens are rejected immediately.
* You can create multiple tokens for different systems or environments.
* Revoke a token at any time from the admin panel. Revocation takes effect instantly.
* If you delete a token, any system still using it will receive a `401 Unauthorized` response. Make sure to update all dependent systems before deleting.

<Tip>
  Never commit API tokens to source control. Use environment variables or a secrets manager. Create separate tokens for production, staging, and development environments, and name them clearly so you can identify which system is using each one.
</Tip>

***

## Errors

The Buylo API uses standard HTTP status codes. Errors always return a JSON body with a human-readable `message` to help you debug quickly.

### Error response format

```json theme={null}
{
  "message": "<string>"
}
```

### Status codes

| Status | Code               | Description                                          |
| ------ | ------------------ | ---------------------------------------------------- |
| `200`  | `ok`               | Request was successful.                              |
| `400`  | `validation_error` | Missing or invalid request parameters.               |
| `401`  | `unauthorized`     | API token is missing, invalid, or expired.           |
| `403`  | `forbidden`        | Token does not have permission for this resource.    |
| `404`  | `not_found`        | The requested resource does not exist.               |
| `409`  | `conflict`         | Resource already exists (e.g. tag already assigned). |
| `422`  | `unprocessable`    | Request is well-formed but cannot be processed.      |
| `500`  | `server_error`     | Something went wrong on our end. Try again later.    |

### Recommended error handling

* Always check the HTTP status code before parsing the response body.
* On `401` errors, verify your token has not expired in the admin panel.
* On `409` conflicts for tag assignment, unassign the existing tag first.
* On `5xx` errors, implement exponential backoff with a retry limit of 3 attempts.
* Log the full error response body — the `message` field often pinpoints the exact issue.