> ## 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.

# Search (Simple)

> <Warning>**Beta.** This endpoint is not fully stable and may change.</Warning>

Full-text search across cards, ordered by relevance. This is the same search that powers gemrate.com, so a query returns the same cards in the same order here as it does on the site.


Results are one entry per card — never one per grading company — and carry the card's cross-grader totals. Follow `gemrate_id` to [`GET /v1/cards/{gemrate_id}/population`](/api-reference/cards/get-population-for-a-card) for the per-grade breakdown.

<Note>If your queries come from a catalog or a grader website in a known field order, [`GET /v1/cards/search/structured`](/api-reference/cards/search-structured) returns matches grouped by grading company instead.</Note>




## OpenAPI

````yaml /openapi.yaml get /v1/cards/search/simple
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/cards/search/simple:
    get:
      tags:
        - Cards
      summary: Search (Simple)
      description: >
        <Warning>**Beta.** This endpoint is not fully stable and may
        change.</Warning>


        Full-text search across cards, ordered by relevance. This is the same
        search that powers gemrate.com, so a query returns the same cards in the
        same order here as it does on the site.



        Results are one entry per card — never one per grading company — and
        carry the card's cross-grader totals. Follow `gemrate_id` to [`GET
        /v1/cards/{gemrate_id}/population`](/api-reference/cards/get-population-for-a-card)
        for the per-grade breakdown.


        <Note>If your queries come from a catalog or a grader website in a known
        field order, [`GET
        /v1/cards/search/structured`](/api-reference/cards/search-structured)
        returns matches grouped by grading company instead.</Note>
      operationId: searchCardsSimple
      parameters:
        - name: query
          in: query
          required: true
          description: >
            The search text — a player, set, year, parallel, card number, or any
            combination. Must be 1–200 characters.
          schema:
            type: string
            maxLength: 200
            example: 1986 fleer jordan
        - name: page
          in: query
          required: false
          description: >
            Which page of results to return, 1-based. Pages are always 10 cards
            — there is no page-size parameter, so the next 10 results are the
            next call. Capped at page 10 (100 cards deep); beyond that, narrow
            the query.
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 1
      responses:
        '200':
          description: One page of matching cards, most relevant first (possibly empty).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SimpleSearchResults'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  query: 1986 fleer jordan
                  page: 1
                  page_size: 10
                  has_more: true
                  results:
                    - description: 1986 Fleer Michael Jordan 57
                      universal_gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242
                      gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242
                      is_universal_match: true
                      gemrate_url: >-
                        https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242
                      parsed_description:
                        category: Basketball
                        year: '1986'
                        set_name: Fleer
                        name: Michael Jordan
                        card_number: '57'
                        parallel: null
                        subset: null
                      total_population: 30810
                      gem_total: 340
                      gem_rate: 0.011035
                meta:
                  request_id: req_abc123
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    SimpleSearchResults:
      type: object
      description: >
        A simple-search response: the query echoed back next to its matches, so
        a stored or logged payload says what it was an answer to.
      properties:
        query:
          type: string
          description: The `query` you sent, minus surrounding whitespace.
        page:
          type: integer
          description: The page this response covers (1-based).
        page_size:
          type: integer
          description: Cards per page. Fixed at 10 — not caller-controlled.
        has_more:
          type: boolean
          description: >
            Whether another page exists. `false` on the last page of results,
            and on page 10, which is as deep as paging goes.
        results:
          type: array
          description: Matching cards, most relevant first. Empty when nothing matched.
          items:
            $ref: '#/components/schemas/SimpleSearchResult'
      required:
        - query
        - page
        - page_size
        - has_more
        - results
    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
    SimpleSearchResult:
      type: object
      description: >
        One matching card. Carries the same identity fields as every other card
        response, plus its cross-grader population totals — the numbers you need
        to pick the right card out of a result list. `parsed_description` is
        always included here (unlike the card endpoints, where it is opt-in),
        because search results are usually rendered as a list of components.


        There is no per-grade breakdown: fetch [`GET
        /v1/cards/{gemrate_id}/population`](/api-reference/cards/get-population-for-a-card)
        for that. Its `population_data.total`/`gem_total`/`gem_rate` are
        computed the same way as the fields here, so the two endpoints always
        agree.
      allOf:
        - $ref: '#/components/schemas/CardIdentity'
        - type: object
          properties:
            parsed_description:
              $ref: '#/components/schemas/ParsedDescription'
            total_population:
              type: integer
              description: Total graded copies of this card across every grading company.
            gem_total:
              type: integer
              description: Copies graded at each company's gem tier or better.
            gem_rate:
              type: number
              format: float
              description: >-
                `gem_total / total_population`, as a fraction (0–1); `0.0` when
                the card has no population.
          required:
            - parsed_description
            - total_population
            - gem_total
            - gem_rate
    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
    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
    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:
    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

````