Skip to main content

​
Get Started in 5 Minutes

This quickstart guide will walk you through creating your first Blackjack game, playing moves, and checking the results. By the end, you’ll have a complete understanding of the game flow.
Before you begin, make sure you have the API running. See the Installation guide if you haven’t set it up yet.

​
Step 1: Start the API

If you’re using Docker Compose (recommended): 
docker compose up -d
The API will be available at http://localhost:8080. Verify it’s running by accessing the Swagger UI: 
http://localhost:8080/swagger-ui.html

​
Step 2: Create a New Game

Create your first Blackjack game by sending a POST request to /game/new: 
curl -X POST http://localhost:8080/game/new \
  -H "Content-Type: application/json" \
  -d '{"playerName": "Alice"}'
Response: 
{
  "gameId": "507f1f77bcf86cd799439011",
  "playerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS"
}
Save the gameId - you’ll need it for all subsequent requests. The playerId is also created if this is your first game.

​
Step 3: Check Your Initial Hand

Retrieve the game state to see your cards and the dealer’s visible card: 
curl http://localhost:8080/game/507f1f77bcf86cd799439011
Response: 
{
  "gameId": "507f1f77bcf86cd799439011",
  "playerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "IN_PROGRESS",
  "playerCards": [
    {"rank": "KING", "suit": "HEARTS"},
    {"rank": "SEVEN", "suit": "DIAMONDS"}
  ],
  "playerScore": 17,
  "dealerCards": [
    {"rank": "NINE", "suit": "CLUBS"}
  ],
  "dealerScore": 9
}
During active gameplay (IN_PROGRESS), only one of the dealer’s cards is visible. The dealer’s second card and full score remain hidden until the game ends.

​
Step 4: Play Your Move

Based on your hand, decide whether to HIT (draw another card) or STAND (end your turn).

​
Option A: HIT (Draw Another Card)

curl -X POST http://localhost:8080/game/507f1f77bcf86cd799439011/play \
  -H "Content-Type: application/json" \
  -d '{"action": "HIT"}'
Response if you don’t bust: 
{
  "gameId": "507f1f77bcf86cd799439011",
  "status": "IN_PROGRESS",
  "playerCards": [
    {"rank": "KING", "suit": "HEARTS"},
    {"rank": "SEVEN", "suit": "DIAMONDS"},
    {"rank": "THREE", "suit": "SPADES"}
  ],
  "playerScore": 20,
  "dealerCards": [
    {"rank": "NINE", "suit": "CLUBS"}
  ],
  "dealerScore": 9
}
You can continue to HIT as long as your score is under 21 and the game status is IN_PROGRESS.
If you HIT and your score exceeds 21, you bust and lose immediately. The game status changes to PLAYER_BUST.

​
Option B: STAND (End Your Turn)

When you’re satisfied with your hand, STAND to let the dealer play: 
curl -X POST http://localhost:8080/game/507f1f77bcf86cd799439011/play \
  -H "Content-Type: application/json" \
  -d '{"action": "STAND"}'
Response after STAND: 
{
  "gameId": "507f1f77bcf86cd799439011",
  "status": "PLAYER_WINS",
  "playerCards": [
    {"rank": "KING", "suit": "HEARTS"},
    {"rank": "SEVEN", "suit": "DIAMONDS"},
    {"rank": "THREE", "suit": "SPADES"}
  ],
  "playerScore": 20,
  "dealerCards": [
    {"rank": "NINE", "suit": "CLUBS"},
    {"rank": "SEVEN", "suit": "HEARTS"},
    {"rank": "FIVE", "suit": "DIAMONDS"}
  ],
  "dealerScore": 21
}
After you STAND:
  1. The dealer reveals their hidden card
  2. The dealer automatically plays (hits until 17 or higher)
  3. The game determines the winner

​
Step 5: Check the Rankings

View the leaderboard to see all player rankings: 
curl http://localhost:8080/ranking
Response: 
[
  {
    "position": 1,
    "playerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Alice",
    "wins": 1,
    "losses": 0,
    "score": 1
  }
]
The ranking is sorted by score (wins - losses) in descending order.

​
Game Outcomes

After the game ends, the status will be one of:
StatusDescription
PLAYER_WINSYour score is higher than the dealer’s without busting
DEALER_WINSThe dealer’s score is higher, or you busted
PUSHBoth you and the dealer have the same score (tie)
BLACKJACK_PLAYERYou got 21 with exactly 2 cards (natural blackjack)
BLACKJACK_DEALERThe dealer got 21 with exactly 2 cards
Natural blackjacks (21 with 2 cards) are detected immediately when the game is created. The game ends automatically if either player or dealer has a natural blackjack.

​
Next Steps

Now that you’ve played your first game, explore more features:

Game Operations

Learn about all game operations and advanced gameplay

API Reference

Explore all available endpoints and data models

Architecture

Understand the hexagonal architecture and reactive patterns

Deploy to Production

Deploy your own instance using Docker

​
Troubleshooting

Make sure the API is running:
docker compose ps
Check the logs:
docker compose logs api
Verify you’re using the correct gameId from the create game response. Game IDs are case-sensitive.
This error occurs when you try to play a move on a game that has already ended. Create a new game to continue playing.
Check your request body:
  • Player name must not be blank and max 30 characters
  • Action must be either “HIT” or “STAND” (case-sensitive)
For interactive API exploration, use the Swagger UI at http://localhost:8080/swagger-ui.html where you can test all endpoints directly in your browser.

Build docs developers (and LLMs) love

Get started for freeTalk to us