# Deck of Cards API

> A free service that keeps a deck of playing cards for you. Open a fresh deck - one or several shuffled together, with or without the Jokers, or just the cards you name - then shuffle it, draw from it, sort what you drew into named piles for hands and discards, and put cards back when the round is over. Every card comes with its name, suit, rank and colour and a picture of its face, so a workflow can deal a hand into a message, pick a card of the day, or play out a round of Blackjack between steps. No account or API key required.

App · Gaming · 9 actions. Web page: https://docs.lodol.com/docs/integrations/deck-of-cards

## Actions

### Add cards to a pile

Put cards that have been drawn into a named pile - a player's hand, a discard pile, the dealer's up-cards. Name a pile that does not exist yet and it is created. Chain the codes from a draw, or type them. Cards can be moved from pile to pile the same way. Piles only work on a single deck. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text, required): The id of the deck, as returned by 'Create a deck' or by a draw. Chain it from that step.
- Pile name (`pile_name`, text, required): The pile's name: letters, digits and underscores, e.g. 'hand', 'discard' or 'player_1'. A pile is created the first time a card is added to it.
- Cards (`cards`, text, required): The codes of the cards to add, separated by commas, e.g. 'AS,2S'. The cards must already have been drawn from the deck. The 'codes' list from a draw can be chained here as it is.

**Outputs**

- `added_codes` (list): The codes that were added, in order.
- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `pile_name` (text): The pile this step acted on.
- `pile_remaining` (number): How many cards the pile holds after this step.
- `piles` (object): Every pile on this deck and how many cards each holds, by pile name.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.

**Example output**

```json
{
  "added_codes": [
    "AS",
    "2S"
  ],
  "deck_id": "3p40paa87x90",
  "pile_name": "discard",
  "pile_remaining": 2,
  "piles": {
    "discard": 2
  },
  "remaining": 12
}
```

### Create a deck

Open a new deck of playing cards and get back its id, which every later step uses to draw from it, shuffle it and sort it into piles. Shuffled by default. Ask for several decks at once for a Blackjack shoe, add the two Jokers, or name just the cards you want for a partial deck. The service keeps the deck for two weeks after it was last used. No account or API key required.

**Inputs**

- Shuffle the deck (`shuffled`, true/false): On by default. Turn it off for a deck in factory order: Ace to King of Spades, then Diamonds, Clubs and Hearts. Default: `true`.
- Number of decks (`deck_count`, number): How many decks to shuffle together, from 1 to 20. Blackjack is usually dealt from six. Piles only work on a single deck. From 1 to 20. Default: `1`.
- Include Jokers (`jokers_enabled`, true/false): Off by default. Turn it on to add the two Jokers, making 54 cards a deck. Default: `false`.
- Only these cards (`cards`, text): Optional. Card codes separated by commas to make a partial deck of just those cards, e.g. 'AS,2S,KS,AD,2D,KD' for the aces, twos and kings of two suits. A code is a value (A, 2-9, 0 for a ten, J, Q or K) and a suit (S, D, C or H). Leave blank for a full deck.

**Outputs**

- `card_codes` (list): The codes a partial deck was made from, in the order given. Empty for a full deck.
- `deck_count` (number): How many decks were shuffled together.
- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `jokers_included` (true/false): True when the two Jokers are in.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.
- `shuffled` (true/false): True when the deck is shuffled, false when it is in order.

**Example output**

```json
{
  "card_codes": [],
  "deck_count": 1,
  "deck_id": "3p40paa87x90",
  "jokers_included": false,
  "remaining": 52,
  "shuffled": true
}
```

### Draw cards

Draw one or more cards off the top of a deck. Each card comes with its code, name, suit, rank, colour and a picture of its face, and the names come joined into one line ready for a message. Leave the deck id blank to open a fresh shuffled deck and draw from it in the same step. If the deck runs out the cards that were left are drawn and the shortfall is reported, so a game can decide what to do next. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text): Optional. The deck to draw from, chained from 'Create a deck'. Leave blank to draw from a brand new shuffled deck, whose id comes back in the result so later steps can keep drawing from it.
- Number of cards (`count`, number): How many cards to draw. One by default. From 1 to 1080. Default: `1`.

**Outputs**

- `cards` (list): The cards, in the order they came.
- `cards_text` (text): The cards' names as one line, e.g. 'Ace of Spades, 10 of Hearts'. Ready to put in a message.
- `codes` (list): The cards' codes, in the same order. Chain this straight into a step that takes cards, such as 'Add cards to a pile'.
- `count` (number): How many cards are in the list.
- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `drew_all` (true/false): True when every card asked for was drawn. False when the stack ran out first: the cards that could be drawn were, and this is the field to branch on.
- `first` (object): The first card in the list, for the step that only wanted one. Null when there are none.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.
- `requested_count` (number): How many cards this step asked for.
- `shortfall` (number): How many of the cards asked for could not be drawn. 0 when they all came.

**Example output**

```json
{
  "cards": [
    {
      "code": "6H",
      "color": "red",
      "image": "https://deckofcardsapi.com/static/img/6H.png",
      "image_svg": "https://deckofcardsapi.com/static/img/6H.svg",
      "name": "6 of Hearts",
      "rank": 6,
      "suit": "HEARTS",
      "value": "6"
    },
    {
      "code": "5S",
      "color": "black",
      "image": "https://deckofcardsapi.com/static/img/5S.png",
      "image_svg": "https://deckofcardsapi.com/static/img/5S.svg",
      "name": "5 of Spades",
      "rank": 5,
      "suit": "SPADES",
      "value": "5"
    }
  ],
  "cards_text": "6 of Hearts, 5 of Spades",
  "codes": [
    "6H",
    "5S"
  ],
  "count": 2,
  "deck_id": "kxozasf3edqu",
  "drew_all": true,
  "first": {
    "code": "6H",
    "color": "red",
    "image": "https://deckofcardsapi.com/static/img/6H.png",
    "image_svg": "https://deckofcardsapi.com/static/img/6H.svg",
    "name": "6 of Hearts",
    "rank": 6,
    "suit": "HEARTS",
    "value": "6"
  },
  "remaining": 50,
  "requested_count": 2,
  "shortfall": 0
}
```

### Draw cards from a pile

Take cards out of a pile: some number off the top, off the bottom or at random, or the particular cards you name. The cards come back with their details and leave the pile, ready to be added to another one. If the pile has fewer cards than asked for, the ones it has are drawn and the shortfall is reported. Piles only work on a single deck. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text, required): The id of the deck, as returned by 'Create a deck' or by a draw. Chain it from that step.
- Pile name (`pile_name`, text, required): The pile's name: letters, digits and underscores, e.g. 'hand', 'discard' or 'player_1'. A pile is created the first time a card is added to it.
- Number of cards (`count`, number): How many cards to draw from the pile. One by default. Ignored when particular cards are named below. From 1 to 1080. Default: `1`.
- Draw from (`position`, text): Where in the pile to draw from. The top by default, which is the last card added; the bottom is the first card added; random picks anywhere. One of: `top`, `bottom`, `random`. Default: `top`.
- Particular cards (`cards`, text): Optional. The codes of particular cards to take from the pile, separated by commas, e.g. 'AS,2S'. When given, the number and the position above are not used.

**Outputs**

- `cards` (list): The cards, in the order they came.
- `cards_text` (text): The cards' names as one line, e.g. 'Ace of Spades, 10 of Hearts'. Ready to put in a message.
- `codes` (list): The cards' codes, in the same order. Chain this straight into a step that takes cards, such as 'Add cards to a pile'.
- `count` (number): How many cards are in the list.
- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `drew_all` (true/false): True when every card asked for was drawn. False when the stack ran out first: the cards that could be drawn were, and this is the field to branch on.
- `first` (object): The first card in the list, for the step that only wanted one. Null when there are none.
- `pile_name` (text): The pile this step acted on.
- `pile_remaining` (number): How many cards the pile holds after this step.
- `piles` (object): Every pile on this deck and how many cards each holds, by pile name.
- `position` (text): Where the cards were drawn from: 'top', 'bottom' or 'random'. Null when particular cards were named.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.
- `requested_count` (number): How many cards this step asked for.
- `shortfall` (number): How many of the cards asked for could not be drawn. 0 when they all came.

**Example output**

```json
{
  "cards": [
    {
      "code": "AS",
      "color": "black",
      "image": "https://deckofcardsapi.com/static/img/AS.png",
      "image_svg": "https://deckofcardsapi.com/static/img/AS.svg",
      "name": "Ace of Spades",
      "rank": 1,
      "suit": "SPADES",
      "value": "ACE"
    }
  ],
  "cards_text": "Ace of Spades",
  "codes": [
    "AS"
  ],
  "count": 1,
  "deck_id": "3p40paa87x90",
  "drew_all": true,
  "first": {
    "code": "AS",
    "color": "black",
    "image": "https://deckofcardsapi.com/static/img/AS.png",
    "image_svg": "https://deckofcardsapi.com/static/img/AS.svg",
    "name": "Ace of Spades",
    "rank": 1,
    "suit": "SPADES",
    "value": "ACE"
  },
  "pile_name": "discard",
  "pile_remaining": 1,
  "piles": {
    "discard": 1
  },
  "position": "top",
  "remaining": 12,
  "requested_count": 1,
  "shortfall": 0
}
```

### List the cards in a pile

See which cards a pile holds, in order, without moving any of them - what is in a player's hand, or what has been discarded so far. Comes back with every card's details, the codes as a list and the names as one line. Piles only work on a single deck. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text, required): The id of the deck, as returned by 'Create a deck' or by a draw. Chain it from that step.
- Pile name (`pile_name`, text, required): The pile's name: letters, digits and underscores, e.g. 'hand', 'discard' or 'player_1'. A pile is created the first time a card is added to it.

**Outputs**

- `cards` (list): The cards in the pile, top first.
- `cards_text` (text): The cards' names as one line, e.g. 'Ace of Spades, 10 of Hearts'. Ready to put in a message.
- `codes` (list): The cards' codes, in the same order. Chain this straight into a step that takes cards, such as 'Add cards to a pile'.
- `count` (number): How many cards are in the list.
- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `first` (object): The first card in the list, for the step that only wanted one. Null when there are none.
- `pile_name` (text): The pile this step acted on.
- `pile_remaining` (number): How many cards the pile holds after this step.
- `piles` (object): Every pile on this deck and how many cards each holds, by pile name.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.

**Example output**

```json
{
  "cards": [
    {
      "code": "KH",
      "color": "red",
      "image": "https://deckofcardsapi.com/static/img/KH.png",
      "image_svg": "https://deckofcardsapi.com/static/img/KH.svg",
      "name": "King of Hearts",
      "rank": 13,
      "suit": "HEARTS",
      "value": "KING"
    },
    {
      "code": "AS",
      "color": "black",
      "image": "https://deckofcardsapi.com/static/img/AS.png",
      "image_svg": "https://deckofcardsapi.com/static/img/AS.svg",
      "name": "Ace of Spades",
      "rank": 1,
      "suit": "SPADES",
      "value": "ACE"
    }
  ],
  "cards_text": "King of Hearts, Ace of Spades",
  "codes": [
    "KH",
    "AS"
  ],
  "count": 2,
  "deck_id": "d5x0uw65g416",
  "first": {
    "code": "KH",
    "color": "red",
    "image": "https://deckofcardsapi.com/static/img/KH.png",
    "image_svg": "https://deckofcardsapi.com/static/img/KH.svg",
    "name": "King of Hearts",
    "rank": 13,
    "suit": "HEARTS",
    "value": "KING"
  },
  "pile_name": "player2",
  "pile_remaining": 2,
  "piles": {
    "player1": 3,
    "player2": 2
  },
  "remaining": 42
}
```

### Look up a card

Turn a card code such as 'AS' or '0H' into the card's name, suit, rank, colour and the addresses of its pictures, plus the picture of the back of a card for anything shown face down. Nothing is drawn and no deck is needed: this is for showing a card whose code you already have. No account or API key required.

**Inputs**

- Card code (`code`, text, required): The card's code: a value (A, 2-9, 0 for a ten, J, Q or K) and a suit (S, D, C or H), e.g. 'AS', '0H' or 'KD'. 'X1' and 'X2' are the Jokers. '10H' is read as '0H'.

**Outputs**

- `back_image` (text): The address of the picture of the back of a card, for a card shown face down.
- `code` (text): The card's two-character code: a value (A, 2-9, 0 for a ten, J, Q or K) and a suit (S, D, C or H), e.g. 'AS' or '0H'. The Jokers are 'X1' and 'X2'. This is what every other step takes to name a card.
- `color` (text): 'red' for Hearts and Diamonds, 'black' for Spades and Clubs.
- `image` (text): The address of a picture of the card's face, as a PNG.
- `image_svg` (text): The same picture as an SVG, which scales to any size.
- `name` (text): The card as a person says it: 'Ace of Spades', '10 of Hearts', 'Red Joker'. The field to put in a message.
- `rank` (number): The card's value as a number to compare or sort on: Ace is 1, then 2 to 10, Jack 11, Queen 12 and King 13. Null for a Joker.
- `suit` (text): The card's suit: 'SPADES', 'DIAMONDS', 'CLUBS' or 'HEARTS'. A Joker carries 'BLACK' or 'RED' here instead.
- `value` (text): The card's value as the service names it: 'ACE', '2' to '10', 'JACK', 'QUEEN', 'KING' or 'JOKER'.

**Example output**

```json
{
  "back_image": "https://deckofcardsapi.com/static/img/back.png",
  "code": "AS",
  "color": "black",
  "image": "https://deckofcardsapi.com/static/img/AS.png",
  "image_svg": "https://deckofcardsapi.com/static/img/AS.svg",
  "name": "Ace of Spades",
  "rank": 1,
  "suit": "SPADES",
  "value": "ACE"
}
```

### Return cards to the deck

Put cards back into the deck so they can be drawn again: everything that has been drawn, the whole of one pile, or just the cards you name. The way to end a round without opening a new deck. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text, required): The id of the deck, as returned by 'Create a deck' or by a draw. Chain it from that step.
- Pile name (`pile_name`, text): Optional. Name a pile to return its cards to the deck. Leave blank to return the cards that were drawn and never put in a pile.
- Particular cards (`cards`, text): Optional. The codes of particular cards to return, separated by commas, e.g. 'AS,2S'. Leave blank to return all of them.

**Outputs**

- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `pile_name` (text): The pile the cards came back from. Null when they came from the drawn cards.
- `piles` (object): Every pile on this deck and how many cards each holds, by pile name.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.
- `returned_codes` (list): The particular codes that were asked to be returned. Empty when everything was.

**Example output**

```json
{
  "deck_id": "3p40paa87x90",
  "pile_name": "discard",
  "piles": {
    "discard": 0
  },
  "remaining": 52,
  "returned_codes": []
}
```

### Shuffle a deck

Shuffle a deck you already have rather than opening a new one, keeping its id. By default every card goes back into the deck and the whole thing is shuffled. Choose to shuffle only the remaining cards and anything already drawn or sitting in a pile stays where it is. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text, required): The id of the deck, as returned by 'Create a deck' or by a draw. Chain it from that step.
- Only the remaining cards (`remaining_only`, true/false): Off by default, which puts every card back and shuffles the full deck. Turn it on to shuffle only the cards still in the stack, leaving drawn cards and piles alone. Default: `false`.

**Outputs**

- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.
- `remaining_only` (true/false): True when only the cards still in the stack were shuffled.
- `shuffled` (true/false): True when the deck is shuffled, false when it is in order.

**Example output**

```json
{
  "deck_id": "3p40paa87x90",
  "remaining": 52,
  "remaining_only": false,
  "shuffled": true
}
```

### Shuffle a pile

Shuffle the cards in one pile, leaving the deck and every other pile as they are - the way to turn a discard pile back into a draw pile. Piles only work on a single deck. No account or API key required.

**Inputs**

- Deck id (`deck_id`, text, required): The id of the deck, as returned by 'Create a deck' or by a draw. Chain it from that step.
- Pile name (`pile_name`, text, required): The pile's name: letters, digits and underscores, e.g. 'hand', 'discard' or 'player_1'. A pile is created the first time a card is added to it.

**Outputs**

- `deck_id` (text): The deck's id. Pass it to every later step that acts on this deck.
- `pile_name` (text): The pile this step acted on.
- `pile_remaining` (number): How many cards the pile holds after this step.
- `piles` (object): Every pile on this deck and how many cards each holds, by pile name.
- `remaining` (number): How many cards are still in the deck's main stack, not yet drawn.

**Example output**

```json
{
  "deck_id": "3p40paa87x90",
  "pile_name": "discard",
  "pile_remaining": 2,
  "piles": {
    "discard": 2
  },
  "remaining": 12
}
```