# Deck of Cards API
> A playing-card deck engine as an API. Create a freshly shuffled deck (one or many decks, with or without jokers), draw cards from it, and reshuffle — with full deck state tracked by a deck id so you can deal hands across multiple calls. Each card comes with its code (e.g. AS, 0H), value, suit and a PNG and SVG image URL, so you can render real cards. Draw cards statelessly from a brand-new deck for quick random picks, or keep a deck_id to build a full game. Ideal for card games and game prototypes, Discord bots, teaching and probability demos, and any app that needs a standard 52-card deck. Built on the Deck of Cards service.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/cards-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 75,000 calls/Mo, 10 req/s
- **Pro** ($9/Mo) — 400,000 calls/Mo, 25 req/s
- **Mega** ($24/Mo) — 2,000,000 calls/Mo, 60 req/s

## Endpoints

### Cards

#### `GET /v1/deck` — Create a new shuffled deck

**Parameters:**
- `count` (query, optional, string) — Number of decks (1-20, default 1) Example: `1`
- `jokers` (query, optional, string) — true to include jokers

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cards-api/v1/deck?count=1"
```

**Response:**
```json
{
    "data": {
        "deck": {
            "note": "Use deck_id with /v1/draw and /v1/shuffle to keep state across calls.",
            "jokers": false,
            "deck_id": "pzsfynm8bcb7",
            "shuffled": true,
            "remaining": 52,
            "deck_count": 1
        }
    },
    "meta": {
        "timestamp": "2026-05-31T14:57:46.098Z",
        "request_id": "1cfec83d-94a2-46f2-9429-91b76ecab33f"
    },
    "status": "ok",
    "message": "Deck created",
    "success": true
}
```

#### `GET /v1/draw` — Draw cards

**Parameters:**
- `count` (query, optional, string) — How many cards to draw (1-200, default 1) Example: `5`
- `deck_id` (query, optional, string) — Draw from this deck; omit for a brand-new deck

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cards-api/v1/draw?count=5"
```

**Response:**
```json
{
    "data": {
        "cards": [
            {
                "svg": "https://deckofcardsapi.com/static/img/0H.svg",
                "code": "0H",
                "suit": "HEARTS",
                "image": "https://deckofcardsapi.com/static/img/0H.png",
                "value": "10"
            },
            {
                "svg": "https://deckofcardsapi.com/static/img/AC.svg",
                "code": "AC",
                "suit": "CLUBS",
                "image": "https://deckofcardsapi.com/static/img/AC.png",
                "value": "ACE"
            },
            {
                "svg": "https://deckofcardsapi.com/static/img/6S.svg",
                "code": "6S",
                "suit": "SPADES",
                "image": "https://deckofcardsapi.com/static/img/6S.png",
                "value": "6"
            },
            {
                "svg": "https://deckofcardsapi.com/static/img/8S.svg",
                "code": "8S",
                "suit": "SPADES",
                "image": "https://deckofcardsapi.com/static/img/8S.png",
                "value": "8"
            },
            {
                "svg": "https://deckofcardsapi.com/static/img/KH.svg",
                "code": "KH",
                "suit": "HEARTS",
                "image": "https://deckofcardsapi.com/static/img/KH.png",
                "value": "KING"
            }
        ],
        "count": 5,
        "deck_id": "omkxczyahuao",
        "remaining": 47
    },
    "meta": {
        "timestamp":
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/shuffle` — Reshuffle a deck

**Parameters:**
- `deck_id` (query, optional, string) — Deck to reshuffle; omit for a fresh shuffled deck

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cards-api/v1/shuffle"
```

**Response:**
```json
{
    "data": {
        "deck": {
            "deck_id": "p3d7vt1lwxo4",
            "shuffled": true,
            "remaining": 52,
            "remaining_only": false
        }
    },
    "meta": {
        "timestamp": "2026-05-31T14:57:46.504Z",
        "request_id": "74b078d1-2d44-4b5e-a206-7d5ad91214fe"
    },
    "status": "ok",
    "message": "Deck shuffled",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Suits, values & card-code format

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cards-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Standard 52-card deck engine (optionally with jokers and multiple decks). /v1/deck = create a shuffled deck (returns a deck_id); /v1/draw = draw cards — from a deck_id, or from a brand-new deck when no deck_id is given (handy for quick random cards); /v1/shuffle = reshuffle a deck. Each card includes its code, value, suit and a PNG + SVG image URL.",
        "suits": [
            "HEARTS",
            "DIAMONDS",
            "CLUBS",
            "SPADES"
        ],
        "source": "Deck of Cards (deckofcardsapi.com)",
        "values": [
            "ACE",
            "2",
            "3",
            "4",
            "5",
            "6",
            "7",
            "8",
            "9",
            "10",
            "JACK",
            "QUEEN",
            "KING"
        ],
        "endpoints": [
            "/v1/deck",
            "/v1/draw",
            "/v1/shuffle",
            "/v1/meta"
        ],
        "code_format": "two characters: value + suit initial, e.g. AS=Ace of Spades, 0H=10 of Hearts, KD=King of Diamonds, X1/X2=Jokers"
    },
    "meta": {
        "timestamp": "2026-05-31T14:57:46.565Z",
        "request_id": "a5c9cb34-c181-4ae3-b85d-46c312e99e4a"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/cards-api
OpenAPI spec: https://www.oanor.com/api/cards-api/openapi.json