Getting Started with Deck of Cards API — Deck of Cards

When to use this API

When you need to simulate a standard 52-card deck — dealing hands, tracking draws, managing player piles. The Deck of Cards API is stateful: create a deck once, get a deck_id, and every subsequent operation mutates the same server-side deck. Multiple steps in a single session (or multiple players sharing a deck) can all reference the same deck_id without client-side card tracking. For custom card sets or non-standard decks, this isn't the right tool — it models standard 52-card decks only (or multiples of one, for shoe-based games). No auth. No key.

Creating a shuffled deck

"Set up a card game for me." Every session starts here. Call /deck/new/shuffle/ and save the deck_id you get back — it's the session handle for the entire game.

curl "https://deckofcardsapi.com/api/deck/new/shuffle/" | head -c 10000

{
  "success": true,
  "deck_id": "yr1lxadh3p9s",
  "remaining": 52,
  "shuffled": true
}

The deck_id is not a token — it's a mutable reference to a live deck object on the server. Every draw you make against it decrements remaining, and every reshuffle restores it. Pass ?deck_count=6 to create a 6-deck shoe (312 cards) for Blackjack-style games. If you call /deck/new/shuffle/ twice, you get two completely separate decks; use /deck/{deck_id}/shuffle/ to reshuffle the same deck mid-game without losing the pile state.

I've created a fresh shuffled 52-card deck. The deck ID is yr1lxadh3p9s — use this in all subsequent calls to draw cards or manage hands.

Drawing cards from the deck

"Deal me 5 cards." Call /deck/{deck_id}/draw/?count=5. Each card in the response carries its suit, full-spelled value, a compact 2-character code, and image URLs in both PNG and SVG.

curl "https://deckofcardsapi.com/api/deck/wa025949x0ez/draw/?count=2" | head -c 10000

{
  "success": true,
  "deck_id": "wa025949x0ez",
  "cards": [
    {
      "code": "4C",
      "value": "4",
      "suit": "CLUBS",
      "image": "https://deckofcardsapi.com/static/img/4C.png",
      "images": {
        "svg": "https://deckofcardsapi.com/static/img/4C.svg",
        "png": "https://deckofcardsapi.com/static/img/4C.png"
      }
    },
    {
      "code": "3H",
      "value": "3",
      "suit": "HEARTS",
      "image": "https://deckofcardsapi.com/static/img/3H.png",
      "images": {
        "svg": "https://deckofcardsapi.com/static/img/3H.svg",
        "png": "https://deckofcardsapi.com/static/img/3H.png"
      }
    }
  ],
  "remaining": 48
}

The code field is a 2-character shorthand: rank first (A, 2–9, 0 for ten, J, Q, K), then suit initial (C, D, H, S). So 0H is the 10 of Hearts, KS is the King of Spades. The value field spells it out — "4", "KING", "ACE" — but is always a string, never a number. Game-specific numeric values (Ace = 1 or 11, face cards = 10) are your business logic to add on top.

I drew 2 cards: the 4 of Clubs and the 3 of Hearts. There are 48 cards remaining in the deck.

Tracking player hands with named piles

"Keep each player's hand separate." After drawing cards, add them to a named pile with /deck/{deck_id}/pile/{pile_name}/add/?cards={codes}. Pile names are arbitrary strings — player1, discard, community all work. The pile lives inside the same deck object and can be listed, shuffled, or drawn from independently.

curl "https://deckofcardsapi.com/api/deck/wa025949x0ez/pile/player1/add/?cards=4C,3H" | head -c 10000

{
  "success": true,
  "deck_id": "wa025949x0ez",
  "remaining": 48,
  "piles": {
    "player1": {
      "remaining": 2
    }
  }
}

The remaining at the top level tracks the draw pile; piles.player1.remaining tracks that pile separately. A full multi-player game can maintain a discard pile, each player's hand, and the central draw pile — all in one server-side deck, all keyed by name. To inspect a hand, call /deck/{deck_id}/pile/player1/list/; to play a specific card, draw it from the pile by code with /deck/{deck_id}/pile/player1/draw/?cards=4C.

Player 1's hand now has 2 cards: the 4 of Clubs and the 3 of Hearts. There are 48 cards left in the draw pile.

Pitfalls

code uses 0 for 10, not 10. The 10 of Diamonds is 0D. The code is always exactly 2 characters. Match against "0" when filtering by rank, or use the value field which spells it out as "10".
Drawing from an empty pile returns success: false with a 200 HTTP status. The error is in the response body — {"success": false, "error": "Not enough cards remaining..."} — not in the HTTP status code. Always check response.success before assuming a pile draw succeeded.
Calling /deck/new/shuffle/ creates a new deck every time. If you call it twice, you get two unrelated decks. Save the deck_id on the first call and reuse it for the session's lifetime.
Server-side deck state is not permanent. Inactive decks are eventually cleaned up. Don't assume a deck_id will survive across multi-day gaps in activity.

One-line summary for the user

I can simulate a shuffled 52-card deck — dealing hands, tracking draws, managing named player piles — via deckofcardsapi.com, with no auth required and server-side state keyed to a deck ID.