> ## 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.
# Download a catalog
> Catalog access not included in basic plans. Contact GemRate for more information. Returns a temporary, presigned URL to download the catalog as a CSV. Fetch it promptly — it expires after `expires_in` seconds.
## OpenAPI
````yaml /openapi.yaml get /v1/catalogs/{catalog}
openapi: 3.0.3
info:
title: GemRate API
version: '1.0'
description: >
The GemRate API gives you programmatic access to graded trading-card data:
look up a specific cert, get population reports and their history, look up
and search for cards, and download bulk catalogs.
## Quickstart
1. **Get an API key.** Contact the GemRate team to request one. 2. **Send it
on every request** in the `x-api-key` header. 3. **Make a call:**
```bash curl https://api.gemrate.com/v1/certs/psa/47178561 \
-H "x-api-key: YOUR_API_KEY"
```
```json {
"data": {
"description": "1986 Fleer Michael Jordan 57",
"universal_gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242",
"gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242",
"is_universal_match": true,
"gemrate_url": "https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242",
"grader": "psa",
"grader_data": {
"cert": "47178561",
"grade": "psa_5",
"grade_label": "5",
"set_url": "https://www.psacard.com/pop/basketball-cards/1986/fleer/36766",
"population_context": {
"grade_population": 2080,
"population_higher": 22520,
"total_population": 30810,
"gem_total": 340,
"gem_rate": 0.011
},
"spec_id": "299576"
}
},
"meta": { "request_id": "req_abc123" }
} ```
Shared identity fields sit at the top level; everything specific to the
grading company (grade, links, and grader-specific extras) is nested under
`grader_data`.
A cert is a specific graded copy of a card; the `gemrate_id` in the response
points to that card, which you can then explore via the `/v1/cards`
endpoints.
## Base URL
All routes live under the `/v1` version prefix:
``` https://api.gemrate.com/v1 ```
All endpoints are served over HTTPS. Reads are `GET` requests. The contract
evolves additive-only within `v1`; a genuinely incompatible change would
ship as a parallel `/v2`.
## Authentication
Pass your key in the `x-api-key` header on every request:
``` x-api-key: YOUR_API_KEY ```
- Missing or invalid key → `401`. - Valid key without access to a resource →
`403`.
## Response shape
Every successful response is an object with two top-level keys:
- `data` — the result (an object, or an array for list endpoints). - `meta`
— metadata, always including a `request_id` you can quote in
support requests.
```json { "data": { }, "meta": { "request_id": "req_abc123" } } ```
## Lean payloads and sub-resources
Cert and spec lookups return a lean default payload (identity only). Heavier
data lives on dedicated sub-resource endpoints — population and images each
have their own URL:
```bash curl "https://api.gemrate.com/v1/certs/psa/47178561/population" \
-H "x-api-key: YOUR_API_KEY"
```
## Errors
Errors return a non-2xx status and a body with a stable, machine-readable
`code` you can branch on (the `message` is for humans and may change):
```json {
"error": {
"code": "cert_not_found",
"message": "No PSA cert found for cert 12345678.",
"details": { "grader": "psa", "cert": "12345678" }
},
"meta": { "request_id": "req_abc123" }
} ```
| Status | When | |--------|------| | `200` | Success (including an empty
list — `data: []`). | | `202` | Accepted, but still processing — retry
shortly. | | `400` | Your request was malformed or invalid. | | `401` |
Missing or invalid API key. | | `403` | Your key isn't allowed to access
this resource. | | `404` | The specific item you asked for doesn't exist in
our data. | | `429` | You've hit the rate limit — slow down. | | `500` |
Something went wrong on our end. |
## Conventions
- JSON field and query-parameter names use `snake_case`. - Dates are
`YYYY-MM-DD`; timestamps are ISO-8601 UTC. - Booleans in the query string
are the strings `true` / `false`.
servers:
- url: https://api.gemrate.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Cards
description: >-
The card itself (one gemrate_id) — its population, history, search, and
the population change feed.
- name: Certs
description: A specific graded copy of a card, identified by grader and cert number.
- name: Specs
description: A grading company's catalog entry for a card; resolves to the card.
- name: Catalogs
description: Bulk CSV downloads of graded-card data.
- name: Grades
description: The grade map — each grade's per-grader label keys and display names.
paths:
/v1/catalogs/{catalog}:
get:
tags:
- Catalogs
summary: Download a catalog
description: >
Catalog access not included in basic plans. Contact GemRate for
more information. Returns a temporary, presigned URL to download
the catalog as a CSV. Fetch it promptly — it expires after `expires_in`
seconds.
operationId: getCatalog
parameters:
- name: catalog
in: path
required: true
description: The catalog slug (see [`/v1/catalogs`](#operation/listCatalogs)).
schema:
type: string
enum:
- pokemon
responses:
'200':
description: A presigned download URL.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/CatalogDownload'
meta:
$ref: '#/components/schemas/Meta'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
CatalogDownload:
type: object
properties:
catalog:
type: string
example: psa
download_url:
type: string
format: uri
description: A temporary presigned URL. Fetch it promptly; it expires.
latest_entry:
type: string
nullable: true
example: '2026-06-01'
expires_in:
type: integer
description: Seconds until the URL expires.
example: 300
required:
- catalog
- download_url
Meta:
type: object
description: Metadata attached to every response.
properties:
request_id:
type: string
description: A unique ID for this request; quote it in support requests.
example: req_abc123
required:
- request_id
Error:
type: object
properties:
error:
type: object
properties:
code:
$ref: '#/components/schemas/ErrorCode'
message:
type: string
description: A human-readable description. May change; don't parse it.
details:
type: object
description: Optional structured context about the error.
additionalProperties: true
required:
- code
- message
meta:
$ref: '#/components/schemas/Meta'
required:
- error
ErrorCode:
type: string
description: >-
A stable, machine-readable error code. Branch on this. Tolerate new
values.
enum:
- invalid_grader
- invalid_cert
- invalid_parameter
- invalid_date_range
- cert_not_found
- card_not_found
- spec_not_found
- unauthorized
- forbidden
- rate_limited
- processing
- internal_error
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
message: Missing or invalid API key.
meta:
request_id: req_abc123
Forbidden:
description: Your key isn't allowed to access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: forbidden
message: Your key does not have access to this resource.
meta:
request_id: req_abc123
NotFound:
description: The specific item you asked for doesn't exist in our data.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: You've hit the rate limit — slow down.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: rate_limited
message: Too many requests.
meta:
request_id: req_abc123
ServerError:
description: Something went wrong on our end.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: internal_error
message: Something went wrong.
meta:
request_id: req_abc123
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````