Data Models
This page describes the data models used by the Trading Card API.
Card​
A trading card resource following JSON:API specification
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "cards" | Resource type |
| id | string (uuid) | No | "123e4567-e89b-12d3-a456-426614174000" | Unique identifier |
| attributes | object | No | ||
| attributes.name | string | No | "Michael Jordan" | Auto-generated card name |
| attributes.number | string | No | "23" | Card number within the set |
| attributes.serial_number | string | Yes | "001/100" | Serial number for limited cards |
| attributes.image_uuid | string (uuid) | Yes | "550e8400-e29b-41d4-a716-446655440000" | UUID reference for card image |
| attributes.title | string | Yes | "Rookie Card" | Special title or designation |
| attributes.notes | string | Yes | Additional notes about the card | |
| attributes.has_player | boolean | No | true | True if the card has an associated player or player/team. Always present on card responses; computed in bulk only by the set checklist endpoint. On other endpoints the flag is not computed and defaults to false, so outside the set checklist endpoint a value of false means "not computed" rather than "no player relationship" — do not rely on it being authoritative there. |
| attributes.has_team | boolean | No | true | True if the card has an associated team or player/team. Always present on card responses; computed in bulk only by the set checklist endpoint. On other endpoints the flag is not computed and defaults to false, so outside the set checklist endpoint a value of false means "not computed" rather than "no team relationship" — do not rely on it being authoritative there. |
| attributes.created_at | string (date-time) | No | Creation timestamp | |
| attributes.updated_at | string (date-time) | No | Last update timestamp | |
| attributes.url | string (uri) | No | API URL for this card resource | |
| relationships | object | No | ||
| relationships.set | object | No | ||
| relationships.set.data | object | No | ||
| relationships.set.data.type | string | No | "sets" | |
| relationships.set.data.id | string (uuid) | No | ||
| relationships.oncard | object | No | ||
| relationships.oncard.data | array of object | No | ||
| relationships.oncard.data[].type | string | No | ||
| relationships.oncard.data[].id | string (uuid) | No | ||
| relationships.attributes | object | No | ||
| relationships.attributes.data | array of object | No | ||
| relationships.attributes.data[].type | string | No | "attributes" | |
| relationships.attributes.data[].id | string (uuid) | No | ||
| relationships.images | object | No | ||
| relationships.images.data | array of object | No | ||
| relationships.images.data[].type | string | No | "card_images" | |
| relationships.images.data[].id | string (uuid) | No |
Set​
A trading card set resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "sets" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "1989 Topps Baseball" | |
| attributes.title | string | Yes | "Series 1" | |
| attributes.description | string | Yes | ||
| attributes.card_count | integer | Yes | 792 | |
| attributes.current_card_count | integer | No | 792 | |
| attributes.is_parallel | boolean | No | false | |
| attributes.is_insert | boolean | No | false | |
| attributes.is_autograph | boolean | No | false | |
| attributes.is_relic | boolean | No | false | |
| attributes.is_variation | boolean | No | false | Indicates a variation set with same card numbering but different visual treatment |
| attributes.serial | integer | Yes | 250 | |
| attributes.number_prefix | string | Yes | ||
| attributes.parent_set | string (uuid) | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No | ||
| relationships | object | No | Related resources. The genre, manufacturer, brand, and year relationships replace the previously flat FK attributes and are only populated when explicitly requested via ?include=genre,manufacturer,brand,year. | |
| relationships.sources | object | No | ||
| relationships.sources.data | array of object | No | ||
| relationships.sources.data[].type | string | No | "set_sources" | |
| relationships.sources.data[].id | string (uuid) | No | ||
| relationships.genre | object | No | Included with ?include=genre. | |
| relationships.genre.data | object | Yes | ||
| relationships.genre.data.type | string | No | "genres" | |
| relationships.genre.data.id | string (uuid) | No | ||
| relationships.manufacturer | object | No | Included with ?include=manufacturer. | |
| relationships.manufacturer.data | object | Yes | ||
| relationships.manufacturer.data.type | string | No | "manufacturers" | |
| relationships.manufacturer.data.id | string (uuid) | No | ||
| relationships.brand | object | No | Included with ?include=brand. | |
| relationships.brand.data | object | Yes | ||
| relationships.brand.data.type | string | No | "brands" | |
| relationships.brand.data.id | string (uuid) | No | ||
| relationships.year | object | No | Included with ?include=year. | |
| relationships.year.data | object | Yes | ||
| relationships.year.data.type | string | No | "years" | |
| relationships.year.data.id | string (uuid) | No |
Player​
A player resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "players" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "Michael Jordan" | |
| attributes.first_name | string | No | "Michael" | |
| attributes.last_name | string | No | "Jordan" | |
| attributes.position | string | Yes | "Shooting Guard" | |
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
Team​
A team resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "teams" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "Chicago Bulls" | |
| attributes.city | string | Yes | "Chicago" | |
| attributes.abbreviation | string | Yes | "CHI" | |
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
PaginationLinks​
JSON:API pagination links
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| first | string (uri) | Yes | ||
| last | string (uri) | Yes | ||
| prev | string (uri) | Yes | ||
| next | string (uri) | Yes |
PaginationMeta​
JSON:API pagination metadata
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| current_page | integer | No | 1 | |
| from | integer | No | 1 | |
| to | integer | No | 25 | |
| per_page | integer | No | 25 | |
| total | integer | No | 100 | |
| last_page | integer | No | 4 |
ListingScopeMeta​
Names the row scope a listing applied, so a scoped total is not misread as a count of the whole catalog.
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| applied | string | No | "root_sets_only" | Identifier of the scope the listing applied. |
| description | string | No | "Only sets without a parent are listed, so parallels, inserts, autograph subsets and variations are omitted. This is a default scope, not a limit on your account. Add ?scope=all to list every set, or ?parent_id=\{id\} to list one set's children." | Human-readable explanation of the applied scope, including how to widen it. |
ErrorResponse​
JSON:API error response format
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| errors | array of object | No | ||
| errors[].id | string | No | Unique error identifier | |
| errors[].status | string | No | HTTP status code | |
| errors[].code | string | No | Application-specific error code | |
| errors[].title | string | No | Short error summary | |
| errors[].detail | string | No | Detailed error description | |
| errors[].source | object | No | ||
| errors[].source.pointer | string | No | JSON pointer to error source | |
| errors[].source.parameter | string | No | Parameter causing the error |
Attribute​
An attribute definition resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "attributes" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.attribute | string | No | "Autograph" | |
| attributes.name | string | No | "Autograph" | |
| attributes.description | string | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
Brand​
A brand resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "brands" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "Topps" | |
| attributes.description | string | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
Manufacturer​
A manufacturer resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "manufacturers" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "Topps Company" | |
| attributes.description | string | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
Year​
A year resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "years" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.year | string | No | "1989" | |
| attributes.description | string | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
Genre​
A genre resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "genres" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "Baseball" | |
| attributes.description | string | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
ObjectAttribute​
An object attribute instance resource linking an attribute to a specific object
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "object-attributes" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.attribute_id | string (uuid) | No | ||
| attributes.attribute_value | string | No | "Authenticated" | |
| attributes.object_type | string | No | "App\\Models\\Card" | |
| attributes.object_id | string (uuid) | No | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
PlayerTeam​
A player-team relationship resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "playerteams" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.name | string | No | "Michael Jordan - Chicago Bulls" | |
| attributes.player_id | string (uuid) | No | ||
| attributes.team_id | string (uuid) | No | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
SetSource​
A set source tracking resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "set_sources" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.source_url | string (url) | No | "https://example.com/checklist" | |
| attributes.source_name | string | Yes | "CardboardConnection" | |
| attributes.source_type | string | No | "checklist" | |
| attributes.verified_at | string (date-time) | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No | ||
| attributes.url | string (uri) | No |
SetTodo​
A workflow step todo resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "set_todos" | |
| id | string (uuid) | No | ||
| attributes | object | No | ||
| attributes.step | string | No | "fetch" | Workflow step identifier; see WorkflowStep enum for valid values. |
| attributes.status | string | No | "in_progress" | |
| attributes.sort_order | integer | No | 1 | |
| attributes.started_at | string (date-time) | Yes | ||
| attributes.completed_at | string (date-time) | Yes | ||
| attributes.completed_by | string | Yes | "admin" | |
| attributes.notes | string | Yes | ||
| attributes.created_at | string (date-time) | No | ||
| attributes.updated_at | string (date-time) | No |
AuditLog​
An audit log event resource
Properties​
| Property | Type | Nullable | Example | Description |
|---|---|---|---|---|
| type | string | No | "audit_logs" | |
| id | integer | No | 12345 | |
| attributes | object | No | ||
| attributes.event_type | string | No | "agent_spawned" | |
| attributes.auditable_type | string | Yes | "set" | |
| attributes.auditable_id | string (uuid) | Yes | ||
| attributes.agent_id | string | Yes | "agent-abc-123" | |
| attributes.data | object | Yes | ||
| attributes.created_at | string (date-time) | No |