Create a list

​

Creates a new, empty list for the given game.

The new list takes its currency from your account settings. Add cards to it with POST /v1/lists/{listId}/items.

Send an Idempotency-Key header to make retries safe — a repeated key returns the first response instead of creating a second list.

Requires the lists:write scope.

Body
required
application/json
  • game
    Type: string
    min length:  
    1
    required

    The game the list is for, given as a slug, e.g. pokemon. Every card in the list must belong to this game.

  • name
    Type: string
    min length:  
    1
    required

    The list's name.

  • status
    Type: string enum
    required

    What the list is for: forSale, toComplete, or hold.

    values
    • forSale

      Cards you're offering for sale.

    • toComplete

      Cards you're working to complete, such as a want list or a deck in progress.

    • hold

      Cards you're keeping aside.

  • description
    Type: string

    A free-text note on the list.

  • isPublic
    Type: boolean

    true to let anyone with the link view the list, false to keep it private. Defaults to true.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/lists
curl https://public-api.cardnexus.com/v1/lists \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "",
  "game": "",
  "status": "toComplete",
  "description": "",
  "isPublic": true
}'

{
  "id": "6512a0b4e1d2c3f4a5b6c7d8",
  "name": "Modern deck — missing pieces",
  "game": "mtg",
  "status": "toComplete",
  "description": "Cards I still need for the Modern burn deck.",
  "bannerUrl": "https://ik.imagekit.io/cardnexus/production/mtg/mh2-137-front.png",
  "completionPercentage": 64,
  "itemCount": 2,
  "totalQuantity": 5,
  "isPublic": false,
  "currency": "USD",
  "defaultMinCondition": "NM",
  "defaultLanguage": "en",
  "createdAt": "2026-03-11T09:15:00.000Z",
  "updatedAt": "2026-06-28T14:02:47.000Z",
  "items": [
    {
      "id": "665f3a2b1c8d4e9f7a6b5c4d",
      "productId": 71044,
      "name": "Lightning Bolt",
      "nameSlug": "lightning-bolt",
      "expansion": "Modern Horizons 2",
      "finish": "Standard",
      "language": "en",
      "minCondition": "LP",
      "quantity": 4,
      "quantityFulfilled": 3,
      "wantPrice": 1.75,
      "sellPrice": null
    },
    {
      "id": "665f3a2b1c8d4e9f7a6b5c4e",
      "productId": 50212,
      "name": "Ragavan, Nimble Pilferer",
      "nameSlug": "ragavan-nimble-pilferer",
      "expansion": "Modern Horizons 2",
      "finish": "Foil",
      "language": "en",
      "minCondition": "NM",
      "quantity": 1,
      "quantityFulfilled": 0,
      "wantPrice": 60,
      "sellPrice": null
    }
  ]
}

List created.