{"openapi":"3.1.0","info":{"title":"Deck of Cards API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/cards-api","description":"oanor gateway"}],"tags":[{"name":"Cards"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/deck":{"get":{"operationId":"get_v1_deck","tags":["Cards"],"summary":"Create a new shuffled deck","description":"","parameters":[{"name":"count","in":"query","required":false,"description":"Number of decks (1-20, default 1)","schema":{"type":"string"},"example":"1"},{"name":"jokers","in":"query","required":false,"description":"true to include jokers","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/draw":{"get":{"operationId":"get_v1_draw","tags":["Cards"],"summary":"Draw cards","description":"","parameters":[{"name":"count","in":"query","required":false,"description":"How many cards to draw (1-200, default 1)","schema":{"type":"string"},"example":"5"},{"name":"deck_id","in":"query","required":false,"description":"Draw from this deck; omit for a brand-new deck","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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":"2026-05-31T14:57:46.303Z","request_id":"6ce63238-8e31-42cc-8c4a-135483393b67"},"status":"ok","message":"Cards drawn","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/shuffle":{"get":{"operationId":"get_v1_shuffle","tags":["Cards"],"summary":"Reshuffle a deck","description":"","parameters":[{"name":"deck_id","in":"query","required":false,"description":"Deck to reshuffle; omit for a fresh shuffled deck","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Suits, values & card-code format","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":295,"monthly_call_quota":75000,"rps_limit":10,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":895,"monthly_call_quota":400000,"rps_limit":25,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":2395,"monthly_call_quota":2000000,"rps_limit":60,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/cards-api"}