Skip to main content
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 GET /api/cards?search=is:pokemon-center selects the authenticated seller’s Pokémon Center-named singles, including parenthetical “Pokemon Center Exclusive” names or a matching stamped catalog product ID. It excludes the ordinary Pokémon Center Trainer card, sealed products and accessories. The same operator works in pricing-rule queries and composes with cond:NM or price>20. See Advanced search for matching limits and the PriceCharting identity hold for stamped cards. If a stamped card has neither a usable configured reference nor a current price, it is skipped; rule preview and test responses use null target/breakdown prices rather than a zero price.

​
Market evidence freshness

GET /analytics/clearing_coverage reports observed market sales, not a complete monthly total. sales_30d counts units in a sample of the latest 25 product sales, filtered to the card’s condition, printing, language, and last 30 days. Unknown or stale observations return null; zero does not prove no demand. fetched_at is the sales observation time. Listings have independent freshness, so a listings-only refresh cannot raise sales confidence. The recent-sales list shows sampled transactions; sales_30d sums recorded units, so one transaction can contribute more than one unit. Neither surface is a complete monthly sales ledger.

​
Base URL

​
Authentication

Every request must include your API key in the Authorization header:
Get your API key from Settings > Profile (any paid plan). The key is in the Account card at the top of that page.

​
Endpoints

​
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.

​
Pricing explanation

GET /api/v1/pricing/explain/:tcgplayer_id returns the card’s governing pricing rule, diagnostic blockers, and the other live rules that match the seller SKU. The matching_rules array is ordered by priority and contains live permanent base-rule candidates plus active temporary-sale overlays; expired sales are omitted. governing_rule is the winning permanent base. Cap receipt steps identify the formula target, period-start/current reference prices and seller limit. Buyouts and sales evidence never remove an upward cap. A temporary sale applies after the cap. Final Direct minimum and enabled rule-level fee-gap adjustments can raise a capped result; the fee-gap step raises 2.50–2.50–3.24 to $3.25. Use the frozen receipt to explain a past decision; live rules may have changed. The legacy velocity_boost_enabled key now protects recent movers from stale reduction without adding a markup. Nullable per-rule inheritance is unchanged. The typed MCP helper hoard.pricing.explainCard preserves nullable historical_breakdown, including the original ordered steps, inputs and reflects_current_price. Check that flag before using a receipt to explain the current target. Both typed and raw responses use snake_case keys. Receipt availability is separate from cap safety history; an absent receipt does not prove that no cap history exists. Older MCP builds without ahg-o48qt omit the receipt field; use hoard.http.get('/api/v1/pricing/explain/12345'), substituting the seller SKU, as a compatibility fallback. A missing field in an older helper is not evidence that no receipt exists.

​
Pricing change-set transition limits

POST /api/v1/agent/plans accepts pricing.change_set for atomic pricing matrices. If a matrix enables or disables a rule, it supports at most five actions and those transition scopes cannot overlap another pricing action in the same matrix. The API returns transition_matrix_too_large or overlapping_rule_transitions with HTTP 422; split the matrix into separate proposals so every resulting-state price impact is checked against pricing floors before commit.

​
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. The value is case-sensitive and must exactly match one of the product line names returned by POST /heartbeat. Any other value returns 422 with code: "invalid_product_line".

​
Heartbeat response

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

​
Response format

All endpoints return JSON except GET /export/price-updates, which returns text/csv. Error responses follow this format:
The code field is present on all error responses and is intended for programmatic handling.

​
Status codes

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.

​
Smart Actions price reviews

GET /api/recommendations is a dashboard/hosted-MCP endpoint outside /api/v1. It requires a session, seller API key or MCP OAuth mcp:read token. Each card has at most one pending competing price review (depth raise, sales anchor, generic raise, or per-card demand pulse). Liquidation and account suggestions remain separate. The response includes revision (UTC timestamp, six fractional digits) and up to three evidence.competing_signals, preserving why the winning review was prioritized. Expected values are estimates, not ROI. Depth acceptance rechecks current seller eligibility and exact market-cell evidence. market_evidence_changed returns a conflict and leaves the item pending for a fresh review. Generic pricing still queues a new preview; existing locked-raise guards remain. The saved automatic-anchor preference is preserved. Automatic mode changes are auto_applied, separate from human accepted events. Dashboard exposure uses session-only POST /api/recommendations/shown, at most 20 {id, revision} observations. A shown event means at least half the individual actionable row was visible in a foreground tab. It is idempotent per revision. GETs, badges and collapsed groups do not count. Delivery is best-effort; missing exposure is unknown. Shown, accepted, auto-applied and expired counts do not establish conversion or causal value. The preregistered intelligence study and its holdouts/logging definitions are unchanged. GET /api/v1/pricing/explain/{tcgplayer_id} can return a frozen historical_breakdown from final sync repricing when attribution logging was enabled. It retains the original calculation and market inputs after settings change. reflects_current_price distinguishes a historical target from the live price. Older events and flag-off reprices do not gain retroactive receipts. Market gate receipts include listings/sales/market observation timestamps; aggressive_price is null when the market reference was stale at the decision. Partial collections do not renew that reference. New collectors leave missing sales-history prices unknown rather than substituting live listing medians. Future-dated sales are excluded from observed counts and live sales comps. GET /api/market_depth/holds rechecks receipt observation clocks and the four-hour buyout window before returning actionable price options. Unknown, future or expired evidence yields null options; historical single-card receipts retain what was recorded at the decision. buy_out_detected_at is included. A thin-market hold may remain in place using earlier listing evidence while Hoard requests a fresh check. gate_verdict.condition_listings is the decision-time count, or null when no usable count was recorded. A saved count can remain after its observation clock expires; do not present it as current. The holds endpoint rechecks sales/market clocks for actionable price options; the single-card explanation preserves the historical verdict. When a selected sales anchor cannot pass its evidence checks, the price-source step names the source used and explains why recent sales were not used. Frozen sync receipts retain this reason even after the market evidence changes. Pokémon inventory queries also support v:shadowless, v:"1999-2000" (alias v:"4th print"), v:"No Symbol", v:prerelease, v:staff, v:winner, and game:pokemon_japan v:"No Rarity". These selectors use explicit printing metadata; pricing requires compatible product and printing identity, and missing premium references hold or skip rather than substitute an ordinary reference.