> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elestrals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource model

> How Series, Sets, Printings, Cards, and Creatures relate to one another.

The Elestrals data model has six public resources arranged in two layers: a **game-piece** layer (Card, Creature) and a **physical-printing** layer (Series, Set, Printing). The single most useful thing to internalize early is that a **Card** and a **Printing** are not the same thing.

## The graph

```mermaid theme={"dark"}
graph TD
  Series[Series<br/><code>sr-10</code>]
  Set[Set<br/><code>st-53</code>]
  Printing[Printing<br/><code>cd-1813</code>]
  Card[Card / Entity<br/><code>et-100</code>]
  Creature[Creature<br/><code>el-159</code>]

  Series -->|contains| Set
  Set -->|contains| Printing
  Printing -->|is one printing of| Card
  Card -->|depicts| Creature
  Card -.->|base printing| Printing
```

* **Series** group sets by release era — First Edition, Kickstarter, Organized Play, etc.
* **Sets** are product releases. A booster pack, a starter deck, a specialty box.
* **Printings** are the physical cards you hold. Each printing belongs to exactly one set and is one of (potentially many) printings of a Card.
* **Cards** are the gameplay entities. The thing that has a `class`, `cost`, `attack`, `defense`, and `effects`. The same Card can be reprinted in different sets, with different art, in different rarities — every reprint is a new Printing of the same Card.
* **Creatures** are the underlying lineage: the Pyrotter creature, depicted across multiple Cards (a basic, an evolved form, an alt-art).

## Card vs Printing — the distinction

This is the question every TCG-API integration eventually hits. The short version:

| If you're asking…                                             | You want…                |
| ------------------------------------------------------------- | ------------------------ |
| "What's this card's effect?"                                  | **Card**                 |
| "What's this card's attack stat?"                             | **Card**                 |
| "Is this card banned in Standard format?"                     | **Card**                 |
| "What sets has this card appeared in?"                        | **Card** → its printings |
| "What art is on this physical card I'm holding?"              | **Printing**             |
| "What's the rarity / collector number of this physical card?" | **Printing**             |
| "Is this a holo, reverse holo, or non-foil?"                  | **Printing** → variants  |
| "What's the price?" *(future, partner-tier)*                  | **Printing**             |

A Card has gameplay properties; a Printing has physical-object properties. Effects, costs, and stats live on Cards because they're identical across every printing. Art, rarity, foil treatment, and set membership live on Printings because they're what differentiate one printed copy from another.

## Worked example

Searching for `Pyrotter`:

```
GET /v1/cards?creature_name=pyrotter
```

You get back two Cards: `et-100` (the basic) and `et-128` (the evolution). Both share `creature.id = "el-12"` because they depict the same Pyrotter lineage.

For each Card, you can list its printings:

```
GET /v1/cards/et-100/printings
```

The response includes `cd-1813` (First Edition basic, common rarity) and `cd-2105` (a Kickstarter foil reprint, stellar rare). Same Card, two physical objects.

## Reference convenience: `base_printing_id`

Every Card has a `base_printing_id` pointing at its canonical printing — typically the first non-promo printing. Use this when you need a single representative image or rarity for a Card and don't want to fetch the full printings list.

```json theme={"dark"}
{
  "id": "et-100",
  "name": "Pyrotter",
  "base_printing_id": "cd-1813",
  "...": "..."
}
```

## What you don't get

A few relationships that the underlying database has but the public API deliberately doesn't expose:

* **Variants beyond the rarity tier.** A printing's foil pattern, frame material, and canvas are exposed; print-run size and serialization details typically aren't (except `serialized.population` for serialized cards).
* **Pre-release or unreleased sets.** Sets are filtered by `release_date <= today`. A leaked spoiler or an internal preview won't show up on `/v1/sets`.
* **Pricing.** No price, market value, or population data on any tier today. See [Images](/images) for the future-feature flag on this.

## Where to go next

<CardGroup cols={2}>
  <Card title="Identifiers" icon="hash" href="/identifiers">
    Every ID prefix and what it points at.
  </Card>

  <Card title="Enums" icon="list" href="/enums">
    Every closed-set value: classes, elements, rarities, holo patterns.
  </Card>

  <Card title="Banlists & formats" icon="ban" href="/banlists-and-formats">
    How card legality is encoded.
  </Card>

  <Card title="Rulings" icon="scale-balanced" href="/rulings">
    Official clarifications attached to a Card.
  </Card>
</CardGroup>