> ## 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. # Spec lookup > A "spec" is a PSA-only identifier of a catalog entry for a card. This endpoint resolves a spec to the card it refers to and returns the resolved `grader`/`spec_id` followed by the card's identity. For acquiring population data from a Spec ID — use [`Get population for a spec`](/api-reference/specs/get-population-for-a-spec). If the spec is known but its card mapping is still being built, you'll get a `202` — retry shortly. ## OpenAPI ````yaml /openapi.yaml get /v1/specs/{grader}/{spec_id} 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/specs/{grader}/{spec_id}: get: tags: - Specs summary: Spec lookup description: > A "spec" is a PSA-only identifier of a catalog entry for a card. This endpoint resolves a spec to the card it refers to and returns the resolved `grader`/`spec_id` followed by the card's identity. For acquiring population data from a Spec ID — use [`Get population for a spec`](/api-reference/specs/get-population-for-a-spec). If the spec is known but its card mapping is still being built, you'll get a `202` — retry shortly. operationId: getSpec parameters: - name: grader in: path required: true description: Only `psa` is supported for spec lookups. schema: type: string enum: - psa example: psa - name: spec_id in: path required: true description: The PSA Spec ID schema: type: string example: '299576' - $ref: '#/components/parameters/ParsedDescriptionFlag' responses: '200': description: The card the spec maps to (led by the resolved `grader`/`spec_id`). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Spec' meta: $ref: '#/components/schemas/Meta' example: data: description: 1986 Fleer Michael Jordan Base 57 universal_gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242 gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242 is_universal_match: true gemrate_url: >- https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242 grader: psa spec_id: '299576' meta: request_id: local '202': description: >- The spec is known but its card mapping is still being built — retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: processing message: Still linking this spec to a card; retry shortly. meta: request_id: req_abc123 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: No card maps to the given spec. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: card_not_found message: No card maps to the given spec. meta: request_id: req_abc123 '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: parameters: ParsedDescriptionFlag: name: parsed_description in: query required: false description: > When `true`, adds a `parsed_description` object that breaks the card's `description` into its catalog components for each grader (category, year, set_name, name, card_number, parallel, subset). Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean schemas: Spec: description: > A spec resolved to its card. At the top level, it carries identity information for the card. (normalized) `grader`/`spec_id` that resolved — mirroring the cert shape. allOf: - $ref: '#/components/schemas/CardIdentity' - type: object properties: grader: type: string enum: - psa description: Only `psa` is supported for spec lookups. example: psa spec_id: type: string required: - grader - spec_id 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 CardIdentity: type: object description: > A card's identity (the GemRate entity), without population. `description` is the human-readable name; pass `?parsed_description=true` for its components. properties: description: type: string universal_gemrate_id: type: string nullable: true description: >- The universal card id; always present, `null` if the card is not universally matched. gemrate_id: type: string is_universal_match: type: boolean description: >- Whether the card is universally matched (equivalent to `universal_gemrate_id` being non-null). gemrate_url: type: string description: >- Link to the card's page on gemrate.com, built from `universal_gemrate_id` (falling back to `gemrate_id`). parsed_description: allOf: - $ref: '#/components/schemas/ParsedDescription' description: Present only with `?parsed_description=true`. required: - description - universal_gemrate_id - gemrate_id - is_universal_match - gemrate_url 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 ParsedDescription: type: object description: > A card's `description` broken into its catalog components. Returned only when `?parsed_description=true`. properties: category: type: string nullable: true year: type: string nullable: true set_name: type: string nullable: true name: type: string nullable: true card_number: type: string nullable: true parallel: type: string nullable: true subset: type: string nullable: true responses: BadRequest: description: Your request was malformed or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_grader message: Unknown grader 'foo'. meta: request_id: req_abc123 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 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 ````