Developers

Evolutio API

Read-only toegang tot je eigen collectie, prijzen, marktindexen, deals en AI pre-grades. Authenticatie met een bearer-token; JSON erin, JSON eruit.

Basis-URL

https://evolutiotcg.com/api/v1

Authenticatie

Alleen Gold

Stuur je API-sleutel mee als bearer-token in de Authorization-header. De API is een Gold-functie en volledig read-only.

Authorization: Bearer evo_…

API-sleutel aanmaken

Scopes

Elke sleutel draagt een set read-scopes. Een endpoint dat een ontbrekende scope vereist geeft 403 INSUFFICIENT_SCOPE.

read:profileRead your account and subscription.
read:collectionRead your collection items.
read:cardsRead the Evolutio card catalogue.
read:pricesRead price history and snapshots.
read:marketRead the derived market indexes.
read:dealsRead the public deal feed.
read:gradingRead your AI pre-grade reports.

Rate limits

Elke sleutel mag maximaal 120 verzoeken per minuut doen. De teller geldt globaal over alle servers.

Elke response bevat deze headers:

RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
Retry-After

Foutcodes

Fouten hebben altijd de vorm { error, code }.

Status	Code	Betekenis
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`403`	`TIER_REQUIRED`	The API requires a Gold subscription.
`403`	`INSUFFICIENT_SCOPE`	The key lacks the required scope.
`404`	`NOT_FOUND`	The resource does not exist or is not yours.
`429`	`RATE_LIMITED`	Rate limit exceeded — see the Retry-After header.

Endpoints

GET/api/v1/meread:profileYour account

The account and subscription tier of the API-key owner.

Parameters

Geen parameters

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/me

Voorbeeldrespons

{
  "data": {
    "id": "clr8x2ab00001",
    "name": "Ash",
    "email": "[email protected]",
    "tier": "GOLD",
    "memberSince": "2026-01-15T10:00:00.000Z",
    "collectionItems": 42
  }
}

GET/api/v1/collectionread:collectionYour collection

All collection items of the key owner, newest first.

Parameters

game (query, optioneel) — Filter by game code, e.g. POKEMON, YUGIOH, MTG.
limit (query, optioneel) — Maximum number of results (1–200). Default 50.
offset (query, optioneel) — Number of results to skip (pagination). Default 0.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/collection

Voorbeeldrespons

{
  "data": [
    {
      "id": "cit_abc",
      "condition": "NM",
      "quantity": 1,
      "purchasePriceEur": 12.5,
      "addedAt": "2026-06-01T09:00:00.000Z",
      "card": {
        "id": "card_charizard_base4",
        "game": "POKEMON",
        "name": "Charizard",
        "set": "Base Set",
        "number": "4",
        "rarity": "Rare Holo"
      }
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0
  }
}

GET/api/v1/collection/{id}read:collectionOne collection item

A single collection item owned by the key owner. 404 if it is not yours.

Parameters

id (pad, verplicht) — Resource id.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/collection/cit_abc

Voorbeeldrespons

{
  "data": {
    "id": "cit_abc",
    "condition": "NM",
    "quantity": 1,
    "purchasePriceEur": 12.5,
    "addedAt": "2026-06-01T09:00:00.000Z",
    "card": {
      "id": "card_charizard_base4",
      "game": "POKEMON",
      "name": "Charizard",
      "set": "Base Set",
      "number": "4",
      "rarity": "Rare Holo"
    }
  }
}

GET/api/v1/cardsread:cardsCard catalogue

The Evolutio card catalogue (own catalogue — never scraped listings).

Parameters

game (query, optioneel) — Filter by game code.
q (query, optioneel) — Case-insensitive substring match on the card name.
limit (query, optioneel) — Maximum number of results (1–200). Default 50.
offset (query, optioneel) — Number of results to skip (pagination). Default 0.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/cards

Voorbeeldrespons

{
  "data": [
    {
      "id": "card_charizard_base4",
      "name": "Charizard",
      "game": "POKEMON",
      "set": "Base Set"
    }
  ],
  "pagination": {
    "total": 1200,
    "limit": 50,
    "offset": 0
  }
}

GET/api/v1/cards/{id}read:cardsCard detail

Card metadata plus the current derived market price and trend. The providerSource label reads "aggregated" when the underlying feed is licensed for aggregation only.

Parameters

id (pad, verplicht) — Resource id.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/cards/card_charizard_base4

Voorbeeldrespons

{
  "data": {
    "id": "card_charizard_base4",
    "name": "Charizard",
    "game": "POKEMON",
    "set": "Base Set",
    "setCode": "BS",
    "number": "4",
    "rarity": "Rare Holo",
    "imageUrl": "https://images.pokemontcg.io/base1/4.png",
    "priceEur": 320.5,
    "change7dPct": 2.4,
    "change30dPct": -1.1,
    "providerSource": "mock"
  }
}

GET/api/v1/cards/{id}/pricesread:pricesCard price history

Derived price history and the most recent snapshots for a catalogue card. LICENSING: per-source snapshots only include sources Evolutio may redistribute — aggregation-only feeds (e.g. JustTCG) are folded into the derived history and never exposed as raw per-source data points; a provider label backed by such a feed reads "aggregated".

Parameters

id (pad, verplicht) — Resource id.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/cards/card_charizard_base4/prices

Voorbeeldrespons

{
  "data": {
    "cardId": "card_charizard_base4",
    "currency": "EUR",
    "history": [
      {
        "date": "2026-07-01",
        "priceEur": 310
      }
    ],
    "snapshots": [
      {
        "capturedAt": "2026-07-11T00:00:00.000Z",
        "source": "mock",
        "priceEur": 320.5
      }
    ],
    "providerSource": "mock"
  }
}

GET/api/v1/pricesread:pricesPrices of owned cards

The latest market price per card you own. Optionally scoped to one owned card. LICENSING: only redistributable sources are returned per-source; aggregation-only feeds (e.g. JustTCG) never appear here and only contribute to derived values.

Parameters

cardId (query, optioneel) — Restrict to a single owned card.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/prices

Voorbeeldrespons

{
  "data": [
    {
      "cardId": "card_charizard_base4",
      "priceEur": 320.5,
      "currency": "EUR",
      "source": "mock",
      "capturedAt": "2026-07-11T00:00:00.000Z"
    }
  ]
}

GET/api/v1/market-indexread:marketMarket indexes

The derived Evolutio market indexes (base 100), market sentiment and the strongest movers by 7-day change. Absolute per-card prices are intentionally excluded. The providerSource label reads "aggregated" when the underlying feed is licensed for aggregation only.

Parameters

Geen parameters

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/market-index

Voorbeeldrespons

{
  "data": {
    "indexes": [
      {
        "code": "POKE100",
        "name": "Pokémon 100",
        "blurb": "Top Pokémon singles, equally weighted.",
        "current": 112.4,
        "deltaByPeriod": {
          "7": 1.2,
          "30": 3.4,
          "90": -2.1
        },
        "cardCount": 100
      }
    ],
    "sentiment": {
      "score": 62,
      "label": "greed"
    },
    "movers": {
      "risers": [
        {
          "cardId": "card_charizard_base4",
          "name": "Charizard",
          "game": "POKEMON",
          "setName": "Base Set",
          "rarity": "Rare Holo",
          "change7dPct": 4.8,
          "imageUrl": "https://images.pokemontcg.io/base1/4.png"
        }
      ],
      "fallers": []
    },
    "totalCards": 1200,
    "providerSource": "mock"
  }
}

GET/api/v1/dealsread:dealsDeal feed (currently demo data)

The current deal feed. HONESTY: as long as the Evolutio marketplace has no real listings, every offer in this feed is SYNTHETIC sample data (deterministic demo marketplace around our own market trend, source `mock_marketplace`) — not a live market observation. Demo entries carry `demo: true` per item, and the response carries a top-level `demo: true` as soon as the feed contains any demo entry. Do not base purchasing decisions on demo entries. Returns 404 when the feature flag `deal_alerts` is disabled. Privacy (AVG): the DTO deliberately contains no seller identity — `source` is a platform label, never a person.

Parameters

limit (query, optioneel) — Maximum number of results (1–100). Default 50.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/deals

Voorbeeldrespons

{
  "data": [
    {
      "id": "mock-card_charizard_base4-2026-07-12-0",
      "cardId": "card_charizard_base4",
      "cardName": "Charizard",
      "game": "POKEMON",
      "setName": "Base Set",
      "rarity": "Rare Holo",
      "productType": "single",
      "priceEur": 280,
      "trendEur": 320.5,
      "pctBelowMarket": 12.6,
      "reliability": 0.8,
      "score": 10.1,
      "source": "mock_marketplace",
      "url": "/markt/kaart/card_charizard_base4",
      "foundAt": "2026-07-12T08:00:00.000Z",
      "demo": true
    }
  ],
  "demo": true,
  "pagination": {
    "total": 8,
    "limit": 50,
    "offset": 0
  }
}

GET/api/v1/gradingread:gradingYour AI pre-grade reports

Your AI pre-grade reports. LEGAL: each report carries the full probability distribution per grade AND the fixed disclaimer — this is an indication, never a guaranteed grade.

Parameters

limit (query, optioneel) — Maximum number of results (1–50). Default 10.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/grading

Voorbeeldrespons

{
  "data": [
    {
      "id": "gr_abc",
      "cardId": "card_charizard_base4",
      "cardName": "Charizard",
      "subscores": {
        "centering": 8.5,
        "corners": 9,
        "edges": 8.5,
        "surface": 9,
        "whitening": 8
      },
      "gradeDistribution": {
        "8": 0.2,
        "9": 0.5,
        "10": 0.3
      },
      "predictedGrade": 9,
      "confidence": 0.72,
      "provider": "mock",
      "disclaimer": "Deze AI pre-grading is een indicatie, geen garantie. Alleen officiële graders (zoals PSA, BGS of CGC) geven een definitieve grade; de uiteindelijke beoordeling kan afwijken.",
      "createdAt": "2026-07-10T12:00:00.000Z"
    }
  ]
}

GET/api/v1/grading/{id}read:gradingOne AI pre-grade report

A single AI pre-grade report you own (404 if not yours). Includes the probability distribution + disclaimer, never a guaranteed grade.

Parameters

id (pad, verplicht) — Resource id.

Voorbeeld (cURL)

curl -H "Authorization: Bearer evo_…" \
  https://evolutiotcg.com/api/v1/grading/gr_abc

Voorbeeldrespons

{
  "data": {
    "id": "gr_abc",
    "cardId": "card_charizard_base4",
    "cardName": "Charizard",
    "subscores": {
      "centering": 8.5,
      "corners": 9,
      "edges": 8.5,
      "surface": 9,
      "whitening": 8
    },
    "gradeDistribution": {
      "8": 0.2,
      "9": 0.5,
      "10": 0.3
    },
    "predictedGrade": 9,
    "confidence": 0.72,
    "provider": "mock",
    "disclaimer": "Deze AI pre-grading is een indicatie, geen garantie. Alleen officiële graders (zoals PSA, BGS of CGC) geven een definitieve grade; de uiteindelijke beoordeling kan afwijken.",
    "createdAt": "2026-07-10T12:00:00.000Z"
  }
}

OpenAPI-specificatie

De volledige machine-leesbare specificatie (OpenAPI 3.1) van deze API.

Open openapi.json