> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gemrate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Programmatic access to graded trading-card data.

The GemRate API gives you programmatic access to graded trading-card data: look up
a specific **certificate**, get a card's **population** and its **history**, resolve
a grader **spec** to a card, and download bulk **catalogs**.

## Base URL

All routes live under the `/v1` version prefix:

```
https://api.gemrate.com/v1
```

Reads are `GET` requests over HTTPS. The contract evolves additive-only within `v1`.

## Authentication

Send your API key in the `x-api-key` header on every request:

```bash theme={null}
curl https://api.gemrate.com/v1/cards/<gemrate_id>/population \
  -H "x-api-key: YOUR_API_KEY"
```

* Missing or invalid key → `401`.
* Valid key without access to a resource → `403`.

## Response envelope

Every success is `{ "data": …, "meta": { "request_id": … } }`; lists put pagination
in `meta.pagination`. Errors carry a stable, machine-readable `code`:

```json theme={null}
{
  "error": { "code": "cert_not_found", "message": "…", "details": {} },
  "meta": { "request_id": "req_abc123" }
}
```

## Grades & labels

Population and grade data is reported under each grader's own **label keys**
(`{grader}_{grade}`, e.g. `psa_10`, `beckett_9_5`, `cgc_10_perfect`).

## Resources

<CardGroup cols={2}>
  <Card title="Certs" icon="id-card" href="/api-reference/certs/cert-lookup">
    A specific graded copy — `GET /v1/certs/{grader}/{cert}` (+ `/images`).
  </Card>

  <Card title="Cards" icon="layer-group" href="/api-reference/cards/get-population-for-a-card">
    The card itself + population — `GET /v1/cards/{gemrate_id}` (+ `/history`).
  </Card>

  <Card title="Specs" icon="magnifying-glass" href="/api-reference/specs/spec-lookup">
    A grader's catalog entry — `GET /v1/specs/{grader}/{spec_id}`.
  </Card>

  <Card title="Catalogs" icon="file-csv" href="/api-reference/catalogs/download-a-catalog">
    Bulk CSV download — `GET /v1/catalogs/{catalog}`.
  </Card>
</CardGroup>