Valo.Data Usage API

openapi: 3.2.0
info:
  title: Valo.Data Usage 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: Usage
  description: Credits used in the current month. Free; accepts an API key.
paths:
  /developer/v1/usage:
    get:
      tags:
      - Usage
      summary: Credits, scans or questions used in the current window (0 credit)
      operationId: get_usage_developer_v1_usage_get
      security:
      - ApiKey: []
      parameters:
      - name: product
        in: query
        required: false
        schema:
          enum:
          - data
          - vision
          - ia
          type: string
          description: '`data` (credits), `vision` (scans) or `ia` (questions).'
          default: data
          title: Product
        description: '`data` (credits), `vision` (scans) or `ia` (questions).'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: '`invalid_api_key`, `api_key_expired` or `not_authenticated`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`subscription_inactive`, `ip_not_allowed`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '`organization_not_found`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: '`invalid_request`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '`rate_limited`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DailyUsage:
      properties:
        date:
          type: string
          format: date
          title: Date
        credits:
          type: integer
          title: Credits
          description: Credits billed that day (UTC).
        requests:
          type: integer
          title: Requests
          description: Metered requests, errors included.
        errors:
          type: integer
          title: Errors
          description: Responses with a status of 400 or more.
      type: object
      required:
      - date
      - credits
      - requests
      - errors
      title: DailyUsage
    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
    Overage:
      properties:
        enabled:
          type: boolean
          title: Enabled
          description: Paid overage is not available during the beta.
          default: false
      type: object
      title: Overage
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
      - error
      title: ErrorResponse
    UsageResponse:
      properties:
        product:
          type: string
          enum:
          - data
          - vision
          - ia
          title: Product
          description: '`data` (credits), `vision` (scans) or `ia` (questions).'
        plan_id:
          type: string
          title: Plan Id
        status:
          type: string
          title: Status
          description: Subscription status.
        period_start:
          type: string
          format: date
          title: Period Start
          description: 'Start of the current monthly credit window (trial: its start).'
        period_end:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Period End
          description: End (exclusive) of the current monthly credit window; `null` for the trial.
        resets_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Resets At
          description: When the credits renew; `null` for the trial (never).
        credits_included:
          type: integer
          title: Credits Included
        credits_used:
          type: integer
          title: Credits Used
        credits_remaining:
          type: integer
          title: Credits Remaining
        rate_limit_per_minute:
          type: integer
          title: Rate Limit Per Minute
        overage:
          $ref: '#/components/schemas/Overage'
        daily:
          items:
            $ref: '#/components/schemas/DailyUsage'
          type: array
          title: Daily
          description: Last 30 days (UTC), oldest first, days without traffic at 0.
      type: object
      required:
      - product
      - plan_id
      - status
      - period_start
      - period_end
      - resets_at
      - credits_included
      - credits_used
      - credits_remaining
      - rate_limit_per_minute
      - daily
      title: UsageResponse
  securitySchemes:
    ApiKey:
      type: http
      description: '`Authorization: Bearer vd_live_…` (or `vd_test_…`). Keys are shown once at creation.'
      scheme: bearer