Valo.Data Editions API

openapi: 3.2.0
info:
  title: Valo.Data Editions API
  summary: 'Trading card catalogue and market prices: Cardmarket, US market, eBay sales, graded prices, populations.'
  description: 'Catalogue and price data for trading card games (Pokémon, One Piece, Yu-Gi-Oh!, Magic, Lorcana and more):

    Cardmarket and US market prices, eBay sold prices, graded prices, PSA/CCC populations and price history. ## Français


    **Authentification.** Chaque requête porte une clé API : `Authorization: Bearer vd_live_…`. Les clés se créent dans

    le portail développeur et ne sont affichées qu''une fois. `vd_test_` et

    `vd_live_` sont une étiquette choisie à la création pour séparer préproduction et production : mêmes données, mêmes

    crédits, mêmes quotas. Une clé peut porter une date d''expiration (`401 api_key_expired`), une liste d''adresses IP ou

    de blocs CIDR autorisés (`403 ip_not_allowed`) et un plafond mensuel de crédits (`429 key_credit_cap_reached`). Le Sandbox

    sert les mêmes prix que les forfaits payants, sans les cotes gradées ni les populations. Les

    identifiants et les liens Cardmarket et marché US (`cardmarket_product_id`, `tcgplayer_product_id`, `cardmarket_url`,

    `tcgplayer_url`) sont inclus à partir de Growth : ils valent `null` en Sandbox et en Starter. **Crédits.** Chaque forfait inclut des crédits mensuels (barème ci-dessous). Les réponses en erreur ne sont jamais

    facturées. Une fois les crédits épuisés, l''API répond `429 quota_exceeded` jusqu''au renouvellement (`resets_at`). Le Sandbox

    lit au plus 250 cartes et produits scellés distincts par mois, toutes routes confondues ; une fiche déjà lue

    reste disponible, une nouvelle au-delà répond `429 catalog_limit_reached`. Il envoie au plus 100 requêtes facturées

    par jour (UTC) : au-delà, `429 daily_limit_reached` jusqu''à minuit UTC (`resets_at`). **Débit.** Les requêtes sont limitées par organisation et par minute selon le forfait : `429 rate_limited`, à rejouer après

    `Retry-After` secondes. **Prix.** Chaque source garde sa devise native, sans conversion. `amount` vaut `null` (jamais `0`) dès que `status`

    n''est pas `available`. `observed_at` est la date d''observation par la source ; `computed_at` celle du dernier calcul. Les ventes eBay sont collectées au mieux (`collection: best_effort`). **Analyses.** Les routes `/data/v1/analysis/*` répondent prêt à afficher : identification d''une carte à partir d''un texte libre, prix recommandé, fiabilité et variations sur 7, 30 et 90 jours, plus fortes hausses et baisses, comparaison, synthèse d''une édition. `recommended` est le prix qu''affiche l''app ValoTCG, toujours en EUR : le marché US y est converti au dernier taux BCE (`fx_rate`), alors que `prices[]` garde la devise native. **Pagination.** Les listes renvoient `next_cursor` ; passez-le en `cursor` pour la page suivante (`page_size` ≤ 100). **Attribution.** Affichez « Données : ValoTCG » à proximité des données affichées. Voir les

    conditions de l''API. ## English


    **Authentication.** Every request carries an API key: `Authorization: Bearer vd_live_…`. Keys are created in the

    developer portal and shown once. `vd_test_` and `vd_live_` are a label

    chosen at creation to separate staging from production: same data, same credits, same quotas. A key may carry an

    expiry date (`401 api_key_expired`), a list of allowed IP addresses or CIDR blocks (`403 ip_not_allowed`) and a

    monthly credit cap (`429 key_credit_cap_reached`). The Sandbox serves the same prices as paid plans, without graded prices

    and populations. Cardmarket and US market ids and links

    (`cardmarket_product_id`, `tcgplayer_product_id`, `cardmarket_url`, `tcgplayer_url`) are included from Growth up:

    they are `null` on Sandbox and Starter. **Credits.** Each plan includes monthly credits (scale below). Error responses are never billed. Once credits are

    exhausted, the API answers `429 quota_exceeded` until renewal (`resets_at`). The Sandbox reads at most 250

    distinct cards and sealed products per month across all routes; an item already read stays available, a new one

    beyond the cap answers `429 catalog_limit_reached`.'
  termsOfService: https://valotcg.com/developers/terms
  contact:
    name: ValoTCG
    url: https://valotcg.com/developers
    email: contact@valotcg.com
  version: 1.0.0
servers:
- url: https://api.valotcg.com
  description: Production
- url: https://api.preprod.valotcg.com
  description: Preproduction
tags:
- name: Editions
  description: Sets and expansions of a game.
paths:
  /data/v1/editions:
    get:
      tags:
      - Editions
      summary: List editions of a game (1 credit)
      operationId: search_editions_data_v1_editions_get
      security:
      - ApiKey: []
      parameters:
      - name: game
        in: query
        required: true
        schema:
          type: string
          description: Game slug from GET /data/v1/games.
          title: Game
        description: Game slug from GET /data/v1/games.
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 2
            maxLength: 80
          - type: 'null'
          description: Part of the edition name (accents and case ignored) or of its set code (separators ignored), e.g. `flammes`, `SV06`, `eb05`.
          title: Q
        description: Part of the edition name (accents and case ignored) or of its set code (separators ignored), e.g. `flammes`, `SV06`, `eb05`.
      - name: language
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - fr
            - en
            - ja
            - zh
            - de
            - es
            - it
            - pt
            type: string
          - type: 'null'
          title: Language
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Page Size
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page_EditionSummary_'
        '401':
          description: '`invalid_api_key`, `api_key_expired`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`insufficient_scope`, `subscription_inactive`, `plan_feature_unavailable`, `ip_not_allowed`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '`game_not_found`, `card_not_found`, `sealed_not_found`, `edition_not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: '`invalid_request`, `invalid_cursor`, `range_exceeds_plan`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '`rate_limited` (see `Retry-After`), `quota_exceeded`, `key_credit_cap_reached` (key credit cap), `catalog_limit_reached` or `daily_limit_reached` (Sandbox)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: '`quota_unavailable`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Page_EditionSummary_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/EditionSummary'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor for the next page; `null` on the last page.
      type: object
      required:
      - items
      title: Page[EditionSummary]
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Stable snake_case error code, e.g. `card_not_found`, `quota_exceeded`.
        message:
          type: string
          title: Message
          description: Human readable explanation.
        request_id:
          type: string
          title: Request Id
          description: Identifier of the request, also returned in the `X-Request-Id` header.
        docs_url:
          type: string
          title: Docs Url
          description: Documentation of this error code.
      additionalProperties: true
      type: object
      required:
      - code
      - message
      - request_id
      - docs_url
      title: ErrorDetail
    EditionSummary:
      properties:
        edition_id:
          type: integer
          title: Edition Id
          description: Edition id, usable as `edition_id` filter on cards and sealed products.
        game:
          type: string
          title: Game
        name:
          type: string
          title: Name
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
          description: Publisher set code, e.g. `SV06`, `OP-01`.
        language:
          type: string
          enum:
          - fr
          - en
          - ja
          - zh
          - de
          - es
          - it
          - pt
          title: Language
        series:
          anyOf:
          - type: string
          - type: 'null'
          title: Series
          description: Series or block of the edition.
        release_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Release Date
        card_count:
          type: integer
          title: Card Count
          description: Cards of this edition available through the API.
        logo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Logo Url
        symbol_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Symbol Url
      type: object
      required:
      - edition_id
      - game
      - name
      - language
      - card_count
      title: EditionSummary
  securitySchemes:
    ApiKey:
      type: http
      description: '`Authorization: Bearer vd_live_…` (or `vd_test_…`). Keys are shown once at creation.'
      scheme: bearer