API Overview

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

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 (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 — manage binders, shoeboxes, and con stacks.
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:

{"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

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.

​Base URL

​Authentication

​Endpoints

​AI assistant endpoints

​Product line header

​Heartbeat response

​Response format

​Status codes

Base URL

Authentication

Endpoints

AI assistant endpoints

Product line header

Heartbeat response

Response format

Status codes