# Mints developer API

Mints v1 is a read-only developer beta with its own published catalog, stable
identifiers, exact Pokémon/card associations, and a developer portal at
`/developers`. Its public dataset is separate from the website's mixed-source
catalog. No API request falls back to restricted provider data.

The initial publication uses explicitly MIT-licensed factual TCGdex metadata for
Pokémon international/English and Japanese cards and sets. Mints adds its own
identity, curation, and publication layer while preserving input attribution.
This does not relabel third-party data as original. Mints-authored product
relationships and other independently verified curation can be published as
separate datasets with explicit provenance and a chosen license.

Images, prices, copied descriptions/rules, and private collector data are
excluded. Products and Riftbound return `503 source_not_cleared` until a cleared
dataset for that scope is explicitly published. The source review and its
evidence are in [DEVELOPER_API_SOURCES.md](DEVELOPER_API_SOURCES.md).

## Start building

Visit `/developers` to read examples, manage keys, inspect usage, and try requests.
Beta key creation requires a registered, invited Mints account (admin or tester).
Anonymous guest sessions cannot create keys. A key is shown once; store it
privately. Raw credentials are never stored in the database or browser storage.

```bash
curl --get "$MINTS_BASE_URL/api/v1/cards" \
  --header "Authorization: Bearer $MINTS_API_KEY" \
  --data-urlencode 'game=pokemon' \
  --data-urlencode 'edition=intl' \
  --data-urlencode 'q=Pikachu' \
  --data-urlencode 'limit=36'

curl "$MINTS_BASE_URL/api/v1/pokemon/25/cards?edition=intl&limit=36" \
  --header "Authorization: Bearer $MINTS_API_KEY"
```

Resolve API paths against your deployment origin. Keep keys server-side or in a
trusted local application; a key embedded in a public webpage is visible to its
visitors. Tokens are accepted only in `Authorization: Bearer <key>`.

Public resources without authentication:

- `GET /api/v1`: discovery.
- `GET /api/v1/openapi.json`: OpenAPI 3.1 contract and field schemas.
- `GET /api/v1/docs`: this guide as Markdown.
- `GET /api/v1/licenses/tcgdex`: complete upstream MIT notice. Preserve the
  copyright and permission notice when using substantial portions of that data.

## Catalog resources

- `GET /api/v1/cards` and `GET /api/v1/cards/{id}`.
- `GET /api/v1/sets` and `GET /api/v1/sets/{id}`.
- `GET /api/v1/products` and `GET /api/v1/products/{id}`.
- `GET /api/v1/pokemon/{id}/cards`: exact recorded National Pokédex associations;
  supports `edition`, `limit`, and `cursor` only. Unknown associations are not
  invented through name matching. A species with no recorded cards returns an
  empty result, not a completeness guarantee.

General list parameters:

| Parameter | Meaning |
| --- | --- |
| `game` | `pokemon` (default) or `riftbound`. Availability depends on a published dataset. |
| `edition` | Pokémon: `intl` (default) or `jp`. Riftbound: `en` (default) or `zh`. |
| `q` | Full-text search of the printed name, at most 80 characters, ordered by relevance. Use Japanese names for Japanese cards. |
| `set` | Cards only: the set `sourceId`, such as `base1`, optionally combined with `q`. |
| `limit` | Integer 1–72; default 36. |
| `cursor` | Opaque continuation returned by the previous response. |

Lists use descending indexed release-date order; a set's cards use ascending
collector-number order. Unknown/duplicate parameters and invalid scopes return
`400` instead of silent normalization. Details accept no query parameters.
Public IDs use `game:edition:sourceId`, such as `pokemon:intl:base1-58`. They do
not expose database IDs and survive reimports that preserve the source key.

List responses contain an array in `data`, `pagination` with `limit`, `hasMore`,
and `nextCursor`, and `meta` with `version`, `generatedAt`, and `sources`.
Details contain one object in `data` and omit `pagination`. OpenAPI defines the
explicit field allowlists; embedded set metadata also excludes prices/images.

`meta.generatedAt` is response time. Each source includes retrieval/sync time,
nullable upstream update time, license, license/evidence reference, attribution,
nullable upstream revision, and snapshot SHA-256. TCGdex's live GraphQL response
has no guaranteed Git revision, so `sourceRevision` is honestly `null`; the
license evidence is pinned separately. Unknown set dates are `null`.

Retain resource, scope, and filters when continuing with a cursor. `limit` may
change. Continue until `nextCursor` is `null`, even after a short or empty page.
A dataset publication can invalidate existing cursors: restart after a `400`.
Readers see the complete active revision; incomplete imports are never visible.

## Keys, quotas, and usage

Beta policy permits three active keys per developer: a live integration, CI,
and a rotation slot. All of an account's keys share a requests-per-minute
budget, initially 60. Creating or rotating keys cannot multiply it. At the
72-record page limit this allows at most 4,320 returned records/minute/account;
it is a pilot policy, not a measured capacity guarantee. Removing an invitation
or revoking a key disables its next catalog call. Revocation takes precedence
over any legacy environment registry entry with the same hash.

Window state persists in Convex across instances/deployments. Windows start with
the first admitted call and last 60 seconds. Calls that reach admission consume
quota even if their cursor/resource is invalid or their scope is not published.
Local parameter rejection and unauthenticated `OPTIONS` do not consume it.

Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, Unix-second
`X-RateLimit-Reset`, and `Mints-API-Version: v1`. `429` adds `Retry-After` seconds.
`Server-Timing: catalog` measures the gateway's backend catalog/admission round
trip; it excludes the later timing-accounting write and client network time.

The portal shows lifetime admitted requests, non-rate-limit errors, blocked
requests, and mean catalog duration over recorded gateway samples. Direct
Convex calls have no gateway duration, so they do not enter that average.
One-use timing receipts prevent replayed samples from double-counting; completed
receipts are deleted, and abandoned receipts expire after one day. Request logs
record resource, status, record count, and duration without tokens, query text,
account details, or request bodies. Inspect Convex execution metrics for actual
database reads/bytes and Vercel logs for gateway behavior before raising budgets.

JSON responses and credential-management responses use `Cache-Control: no-store`.
Catalog endpoints allow cross-origin reads without cookies. Key management is
session-authenticated and same-origin only; bearer credentials cannot manage keys.
Supported catalog methods are `GET`, `HEAD`, and `OPTIONS`; HEAD consumes the
same quota as GET.

## Errors

Errors use `{ "error": { "code": "...", "message": "..." } }`.

| HTTP | Codes | Next step |
| --- | --- | --- |
| 400 | `invalid_request` | Correct parameters or restart pagination. |
| 401 | `unauthorized` | Check the bearer key, invitation, or revocation state. |
| 404 | `not_found` | Check resource and complete public ID within a published scope. |
| 429 | `rate_limited` | Respect `Retry-After`. |
| 503 | `source_not_cleared` | No cleared dataset is published for this scope; check `/developers`. |
| 503 | `not_configured`, `unavailable` | Contact the operator for policy/configuration failures; retry transient failures. |

## Operator release and dataset publication

Ship schema additions first, then the backend/API/portal. Mints uses Vercel
project `prj_I0aWAKEmaoRGGYhX0U75ElrMJjrV`; production Convex is
`wonderful-kiwi-581`, development is `shiny-finch-975`. Verify targets before
deployment. The production build deploys Convex with its production credential
and sets `NEXT_PUBLIC_CONVEX_URL`; `NEXT_PUBLIC_CONVEX_SITE_URL` must match.

`scripts/deploy/vercel-build.mts` refuses production credentials for previews and
pins production deploy credentials to `wonderful-kiwi-581`. Without a preview
deploy key, previews build against the explicitly configured development backend
without deploying it. They are shared-development previews, not isolated Convex
databases; account sign-in still depends on that backend's trusted-origin policy.
The build derives the matching auth-site URL from the actual backend URL. Never
copy a production deploy key into the Preview environment to make a build pass.

New keys use only database hashes. `MINTS_API_ACCESS` defaults to `invite`;
`public` deliberately opens key creation to registered accounts. Optional
`MINTS_API_REQUESTS_PER_MINUTE` overrides 60. Invalid policy values fail closed.
The older `MINTS_API_KEYS` hash registry remains compatible for existing manual
keys, with independent per-key limits; migrate integrations to portal keys for
owner-scoped usage and quotas. Do not place raw keys in that registry.

The reproducible licensed import is:

```bash
pnpm exec tsx scripts/api/import-tcgdex.mts --deployment dev --dry-run
pnpm exec tsx scripts/api/import-tcgdex.mts --deployment dev --snapshot <printed-snapshot-path>
pnpm exec tsx scripts/api/import-tcgdex.mts --deployment prod --snapshot <same-snapshot-path>
```

The importer fetches only selected facts in one bulk request, verifies and
preserves the pinned MIT notice, saves a hashed snapshot under ignored `.cache`,
and publishes sets before cards. It requires an explicit target and clears an
inherited deploy key so named CLI targets cannot accidentally resolve to dev.
Each transaction batch is at most 72 records, idempotent, scope-validated, and
strict about fields. The internal `importGroup` controller reduces CLI overhead
by handling up to ten such batches within a 1 MiB argument budget.
`publicCatalog.begin/importBatch/importGroup/publish/abort` are internal only.
Publication verifies expected card/association counts before replacing a pointer.
Retained old revisions may be removed later through deliberate maintenance.

Current source caveats: Japanese rarity is omitted because that GraphQL field
breaks hundreds of otherwise valid records; four noninteger Pokédex associations
are omitted without rounding. Two conflicting Japanese set IDs are corrected
from pinned upstream filenames. All source card/set records are retained. Full
details and evidence are in the source review.

Original Mints records require an explicit provenance/attribution manifest and
an intentionally chosen publication license. A `source` label alone is never
clearance, and the importer never republishes existing private mixed-source rows.
The supported original-dataset manifest currently requires an explicit CC0
declaration; do not use it for owned curation without deliberately choosing that
release. Existing licensed imports remain attributed MIT data.

## Verification

```bash
pnpm exec vitest run convex/publicCatalog.test.ts convex/developerApi.test.ts convex/developerKeys.test.ts src/lib/developer-api/http.test.ts src/lib/developer-api/management.test.ts
pnpm exec tsc --noEmit
pnpm lint
pnpm build
```

Tests cover publication completeness/provenance, private-data exclusion, exact
associations, search beyond 200 results, cursor isolation, authentication,
revocation, shared quotas, ownership, one-time credentials, timing replay/overflow,
CORS, and HTTP-to-real-backend integration. A release also needs live list,
detail, search, pagination, association, and revocation checks against its named
deployment; fixture tests alone do not establish upstream index readiness.
