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

# API Overview

> Hoard API reference — powers Hoard Desktop and Hoard Agent, and is available for custom integrations.

The Hoard API powers Hoard Desktop and Hoard Agent and is available for custom integrations. All endpoints use Bearer token authentication with your API key.

Full spec available at [openapi.yaml](https://www.tryhoard.com/openapi.yaml)

## Base URL

```
https://www.tryhoard.com/api/v1
```

## Authentication

Every request must include your API key in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key from [Settings > Account](https://www.tryhoard.com/settings) (any paid plan).

## Endpoints

| Method | Path                                | Purpose                                                       |
| ------ | ----------------------------------- | ------------------------------------------------------------- |
| POST   | `/heartbeat`                        | Agent keep-alive signal                                       |
| GET    | `/sync/pending`                     | Check if a sync should run                                    |
| POST   | `/sync`                             | Upload inventory CSV (gzipped)                                |
| POST   | `/sync/cancel`                      | Release sync lock on failure                                  |
| GET    | `/export/price-updates`             | Download repricing CSV                                        |
| GET    | `/status`                           | Current sync status                                           |
| POST   | `/orders`                           | Upload order data                                             |
| POST   | `/order_feedbacks`                  | Upload seller feedback ratings                                |
| POST   | `/sales_report`                     | Upload sales report                                           |
| GET    | `/sales_report/gaps`                | Get months missing data                                       |
| POST   | `/repricing_events`                 | Record a price import event                                   |
| POST   | `/sync/log`                         | Upload sync cycle step log                                    |
| POST   | `/sync/debug`                       | Upload debug screenshot on failure                            |
| POST   | `/tasks/claim`                      | Claim queued agent work such as order refreshes and backfills |
| PATCH  | `/tasks/:id`                        | Complete or fail a claimed agent task                         |
| POST   | `/workflow/heal`                    | Request a workflow selector repair                            |
| POST   | `/workflow/corrections`             | Confirm a successful selector repair                          |
| POST   | `/workflow/corrections/:id/failure` | Report a cached repair that failed retry                      |
| GET    | `/desktop/update`                   | Check for desktop app update                                  |

## AI assistant endpoints

Beyond the agent surface above, a set of read/write endpoints (mounted at
`/api/...`, not `/api/v1/...`) are exposed to AI assistants over Bearer auth and
the hosted MCP. See:

* [Card lists](/api-reference/lists) — manage binders, shoeboxes, and con stacks.
* [Discovery](/api-reference/discovery) — find which sellers across the consented network have a card in stock, with prices and an affiliate buy link.

## Product line header

The `POST /sync` endpoint accepts an `X-Product-Line` header to specify which product line the inventory belongs to (e.g., `magic`, `pokemon`). This tells the server which product line the uploaded CSV is for, so it can process each game's inventory separately.

## Heartbeat response

The `POST /heartbeat` response includes fields the local Hoard install uses to stay current:

| Field              | Description                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `product_lines`    | Array of product lines enabled for this account (e.g., `[{"name": "magic", "category_id": 1}]`) |
| `update_available` | Whether a newer Hoard version is available                                                      |
| `force_update`     | Whether the local install must update before continuing                                         |
| `latest_version`   | Latest available version string (only when update\_available is true)                           |
| `download_url`     | URL to download the new Hoard binary (only when update\_available is true)                      |
| `signature`        | Ed25519 signature for verifying the download                                                    |
| `sha256`           | SHA-256 checksum for verifying the download                                                     |

## Response format

All endpoints return JSON except `GET /export/price-updates`, which returns `text/csv`.

Error responses follow this format:

```json theme={null}
{"error": "description of what went wrong", "code": "machine_readable_code"}
```

The `code` field is present on all error responses and is intended for programmatic handling.

## Status codes

| Code | Meaning                                                                              |
| ---- | ------------------------------------------------------------------------------------ |
| 200  | Success                                                                              |
| 201  | Created (resource saved)                                                             |
| 202  | Accepted (queued for async processing)                                               |
| 400  | Request body isn't valid JSON (`code: "bad_request"`)                                |
| 401  | Invalid or missing API key (`code: "unauthorized"`)                                  |
| 403  | Account suspended (`code: "account_suspended"`)                                      |
| 409  | Conflict (e.g., no sync in progress to cancel)                                       |
| 413  | Payload too large — global 10 MB cap on all API routes (`code: "payload_too_large"`) |
| 422  | Validation error                                                                     |
| 429  | Rate limit exceeded (`code: "rate_limited"`, check `Retry-After` header)             |
| 500  | Server error                                                                         |

<Note>
  This API powers Hoard Desktop and Hoard Agent and is also available for custom integrations. Hoard handles all API communication automatically during sync cycles. You can call these endpoints directly to build tooling, scripts, or alternative clients.
</Note>