Collections
List Collections
/api/v1/collectionsReturns a paginated list of the user's card collections.
| Parameter | Required | Description |
|---|---|---|
limit | No | Number of results (1-100, default 20) |
cursor | No | Cursor from previous response for pagination |
{
"data": [
{
"id": "550e8400-...",
"name": "My Collection",
"card_count": 1247,
"created_at": "2026-02-10T08:00:00Z"
}
],
"meta": {
"request_id": "req_xyz",
"timestamp": "2026-03-31T14:22:00Z",
"has_more": false,
"next_cursor": null
}
}Get Collection
/api/v1/collections/{id}Returns a collection with a page of its cards. Follow next_cursor until has_more is false to read the whole collection. card_count is the total for the collection, not the page. Cards are ordered by oracle_id, which is stable across pages; sort client-side if you need them alphabetical.
| Parameter | Required | Description |
|---|---|---|
limit | No | Cards per page (1-500, default 100) |
cursor | No | next_cursor from the previous response. A malformed cursor returns 400 invalid_cursor rather than silently restarting at the first page. |
color | No | Comma-separated colours: W, U, B, R, G, or C for colourless. Values are OR-ed, so color=W,U returns cards playable with white or blue available. C matches cards with no colour and cannot be expressed by listing the other five. |
color_match | No | identity (default) matches colour identity, which is what Commander legality uses. colors matches the card's own casting colours. They differ: a land with a coloured ability has no casting colour but does have a colour identity. Sending color_match without color returns 400. |
type | No | Comma-separated card types: artifact, battle, creature, enchantment, instant, kindred, land, planeswalker, sorcery. Values are OR-ed. Matches the FRONT face and the types only, so a Saga that transforms into a creature is an enchantment, not a creature, and an Aura that enchants a creature is not one either. Subtypes are not accepted; type=wizard returns 400. |
An unrecognised filter value returns 400 invalid_filter naming the field and listing what is supported, rather than being ignored. A silently dropped value would return a page that quietly answered a different question. card_count is always the whole collection and does not shrink when a filter is applied, so meta.filters echoes back what was actually filtered.
{
"data": {
"id": "550e8400-...",
"name": "My Collection",
"card_count": 1247,
"created_at": "2026-02-10T08:00:00Z",
"cards": [
{
"oracle_id": "a1b2c3d4-...",
"name": "Sol Ring",
"mana_cost": "{1}",
"type_line": "Artifact",
"colors": [],
"color_identity": [],
"quantity": 3
}
]
},
"meta": {
"request_id": "req_xyz",
"timestamp": "2026-03-31T14:22:00Z",
"has_more": true,
"next_cursor": "6c1c4c1a-9c39-4b4e-9f8f-2f6f1a0d5b21",
"filters": { "color": ["G"], "color_match": "identity", "type": ["creature"] }
}
}Create Collection
/api/v1/collectionsCreates a new collection, optionally with cards. Respects your plan's collection limit.
{
"name": "Gestic Import - March 2026",
"cards": [
{ "name": "Sol Ring", "quantity": 3 },
{ "name": "Command Tower", "quantity": 1 },
{ "oracle_id": "a1b2c3d4-...", "quantity": 2 }
]
}{
"collection_id": "550e8400-...",
"collection_name": "Gestic Import - March 2026",
"added": 2,
"updated": 1,
"errors": [],
"capacity": { "used": 1250, "limit": 20000, "remaining": 18750 }
}Cards can be identified by name or oracle_id. Maximum 500 cards per request. If a card already exists in the collection, its quantity is incremented (additive). If the collection name is omitted, a default name is generated.
Import Cards
/api/v1/collections/{id}/cardsAdds cards to an existing collection. If a card already exists, its quantity is incremented (upsert). Respects your plan's card capacity limit. Cards that exceed the limit are skipped.
{
"cards": [
{ "name": "Lightning Bolt", "quantity": 4 },
{ "name": "Nonexistent Card", "quantity": 1 }
]
}{
"collection_id": "550e8400-...",
"added": 1,
"updated": 0,
"errors": [
{ "index": 1, "name": "Nonexistent Card", "reason": "not_found" }
],
"capacity": { "used": 1251, "limit": 20000, "remaining": 18749 }
}Error reasons: not_found (card name not recognized), capacity_limit (plan limit reached), invalid_quantity (qty must be 1-1000), missing_identifier (no name or oracle_id provided), name_too_long (over 200 characters).