# Collectors Club API

> The official Collectors Club API (current stable version `2026-08-04`, base path `/v1`) for developers and AI agents building on the graded-card marketplace: inventory, certs, listings, packs, and orders.

## Getting started

- [Capability document](https://packs.collectorsclub.com/v1): GET /v1 returns resources, version, docs and spec URLs, and rate limits in one unauthenticated call.
- [OpenAPI spec (JSON)](https://packs.collectorsclub.com/openapi.json): the resolved machine-readable contract; version-pinned copy at https://packs.collectorsclub.com/v1/openapi.json.
- [OpenAPI spec (YAML)](https://packs.collectorsclub.com/openapi.yaml): same contract in YAML.
- [All docs in one file](https://packs.collectorsclub.com/docs/llms-full.txt): every page plus the resolved spec inline. Fetch this for everything in one request.
- [Getting started](https://packs.collectorsclub.com/docs/getting-started.md): Base URL, your first authenticated request, and how test mode works.
- [Versioning](https://packs.collectorsclub.com/docs/versioning.md): How the API is versioned and the field-stability guarantee.
- [Quickstart](https://packs.collectorsclub.com/docs/quickstart.md): From API key to first successful call in under five minutes.
- [Changelog](https://packs.collectorsclub.com/docs/changelog.md): What shipped in each API version.
- [Reference: meta](https://packs.collectorsclub.com/docs/reference/meta.md): Discovery and orientation endpoints. No authentication required;
- [Reference: ping](https://packs.collectorsclub.com/docs/reference/ping.md): Connectivity check for verifying keys and the request stack.

## Guides

- [Sandbox (test mode)](https://packs.collectorsclub.com/docs/sandbox.md): How test-mode keys work and what they can never touch.
- [Pagination, filtering & expansion](https://packs.collectorsclub.com/docs/pagination.md): Cursor pagination, the list envelope, filters, and expand[].
- [Idempotency](https://packs.collectorsclub.com/docs/idempotency.md): Safe retries: the Idempotency-Key header and its 24-hour replay window.
- [Rate limits](https://packs.collectorsclub.com/docs/rate-limits.md): Per-key limits, the RateLimit-* headers, and how to back off.

## Authentication

- [Authentication](https://packs.collectorsclub.com/docs/authentication.md): API key flavors (pk/sk), test vs live mode, scopes, and how to send the key.

## Inventory

- [Reference: inventory](https://packs.collectorsclub.com/docs/reference/inventory.md): Items, reservations, transfers, and the stock-event feed. Stock is
- [Reference: certs](https://packs.collectorsclub.com/docs/reference/certs.md): Grading certificates, served read-through from the AGS sync cache. A

## Marketplace

- [Marketplace sell flow](https://packs.collectorsclub.com/docs/selling.md): Ownership, valuation, the three pricing modes, offers, and settlement.
- [Reference: marketplace](https://packs.collectorsclub.com/docs/reference/marketplace.md): Marketplace listings and the valuation/buyback sell path. A listing is
- [Reference: orders](https://packs.collectorsclub.com/docs/reference/orders.md): Cart → order → payment → fulfillment.

## Packs

- [Provably fair pack openings](https://packs.collectorsclub.com/docs/provably-fair.md): The commit-reveal scheme and a runnable snippet that reproduces any pull.
- [Reference: packs](https://packs.collectorsclub.com/docs/reference/packs.md): Mystery packs with provably fair openings. Odds are public and

## Webhooks

- [Webhooks](https://packs.collectorsclub.com/docs/webhooks.md): Endpoints, the event catalog, signature verification code, retries, and replay.
- [Reference: webhooks](https://packs.collectorsclub.com/docs/reference/webhooks.md): Webhook endpoints and the readable event log. Requires a secret key

## Errors

- [Errors](https://packs.collectorsclub.com/docs/errors.md): The single error envelope, every error type, and how to react to each status.

## Cards

- [Reference: cards](https://packs.collectorsclub.com/docs/reference/cards.md): Catalog card identities (read-only, derived from grading data).

## Locations

- [Reference: locations](https://packs.collectorsclub.com/docs/reference/locations.md): Physical stock locations. Deletes are soft and reversible in the back office.

## Offers

- [Reference: offers](https://packs.collectorsclub.com/docs/reference/offers.md): Buyer offers on listings, with counters and expiry. Lifecycle:
