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.yamlDocumentation Index
Fetch the complete documentation index at: https://docs.tryhoard.com/llms.txt
Use this file to discover all available pages before exploring further.
Base URL
Authentication
Every request must include your API key in theAuthorization header:
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 |
Product line header
ThePOST /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
ThePOST /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 exceptGET /export/price-updates, which returns text/csv.
Error responses follow this format:
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) |
| 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 |
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.