Skip to main content
POST
/
game
/
{id}
/
play
Play Move
curl --request POST \
  --url https://api.example.com/game/{id}/play \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "<string>"
}
'
{
  "200": {},
  "400": {},
  "404": {},
  "409": {},
  "gameId": "<string>",
  "playerId": "<string>",
  "status": "<string>",
  "playerScore": 123,
  "dealerScore": 123,
  "playerCards": [
    {
      "rank": "<string>",
      "suit": "<string>",
      "hidden": true
    }
  ],
  "dealerCards": [
    {
      "rank": "<string>",
      "suit": "<string>",
      "hidden": true
    }
  ]
}

​
Request

Plays a move (HIT or STAND) in an existing game and returns the updated game state. If the game ends as a result of this move, player ranking statistics are automatically updated.

​
Path Parameters

​
id
string
required
The unique identifier of the game

​
Body Parameters

​
action
string
required
The move to play. Must be one of:
  • HIT - Request another card
  • STAND - Keep current hand and end turn

​
Request Example

{
  "action": "HIT"
}

​
cURL Examples

Hit: 
curl -X POST http://localhost:8080/game/550e8400-e29b-41d4-a716-446655440000/play \
  -H "Content-Type: application/json" \
  -d '{
    "action": "HIT"
  }'
Stand: 
curl -X POST http://localhost:8080/game/550e8400-e29b-41d4-a716-446655440000/play \
  -H "Content-Type: application/json" \
  -d '{
    "action": "STAND"
  }'

​
Response

Returns the updated game state after the move is applied.
​
gameId
string
Unique identifier for the game
​
playerId
string
Unique identifier for the player
​
status
string
Updated game status. Possible values:
  • IN_PROGRESS - Game continues
  • PLAYER_WIN - Player won
  • DEALER_WIN - Dealer won
  • TIE - Game ended in a tie
​
playerScore
integer
Updated score of the player’s hand
​
dealerScore
integer
Updated score of the dealer’s hand
​
playerCards
array
Updated array of player’s cards
​
dealerCards
array
Updated array of dealer’s cards

​
Response Example (After HIT - Still In Progress)

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "IN_PROGRESS",
  "playerScore": 18,
  "dealerScore": 10,
  "playerCards": [
    {
      "rank": "NINE",
      "suit": "HEARTS",
      "hidden": false
    },
    {
      "rank": "SEVEN",
      "suit": "DIAMONDS",
      "hidden": false
    },
    {
      "rank": "TWO",
      "suit": "CLUBS",
      "hidden": false
    }
  ],
  "dealerCards": [
    {
      "rank": "TEN",
      "suit": "CLUBS",
      "hidden": false
    },
    {
      "rank": null,
      "suit": null,
      "hidden": true
    }
  ]
}

​
Response Example (After STAND - Game Ends)

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "PLAYER_WIN",
  "playerScore": 19,
  "dealerScore": 17,
  "playerCards": [
    {
      "rank": "KING",
      "suit": "HEARTS",
      "hidden": false
    },
    {
      "rank": "NINE",
      "suit": "DIAMONDS",
      "hidden": false
    }
  ],
  "dealerCards": [
    {
      "rank": "TEN",
      "suit": "CLUBS",
      "hidden": false
    },
    {
      "rank": "SEVEN",
      "suit": "SPADES",
      "hidden": false
    }
  ]
}

​
Response Example (Player Busts)

{
  "gameId": "550e8400-e29b-41d4-a716-446655440000",
  "playerId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "DEALER_WIN",
  "playerScore": 23,
  "dealerScore": 10,
  "playerCards": [
    {
      "rank": "KING",
      "suit": "HEARTS",
      "hidden": false
    },
    {
      "rank": "NINE",
      "suit": "DIAMONDS",
      "hidden": false
    },
    {
      "rank": "FOUR",
      "suit": "CLUBS",
      "hidden": false
    }
  ],
  "dealerCards": [
    {
      "rank": "TEN",
      "suit": "CLUBS",
      "hidden": false
    },
    {
      "rank": "ACE",
      "suit": "SPADES",
      "hidden": false
    }
  ]
}

​
Status Codes

​
200
OK
Move successfully applied and game state returned
​
400
Bad Request
Validation error - action is missing or invalid
​
404
Not Found
Game with the specified ID does not exist
​
409
Conflict
Invalid move - game is not in progress (already finished)

​
Game Logic

​
HIT Action

  • Adds one card to the player’s hand
  • If player’s score exceeds 21, player busts and dealer wins
  • If player’s score is 21 or less, game continues and player can make another move

​
STAND Action

  • Player keeps current hand
  • Dealer reveals hidden card and plays according to house rules
  • Dealer must hit until reaching 17 or higher
  • Game ends with winner determination

​
Winning Conditions

  • Player Win: Player’s score is higher than dealer’s without exceeding 21, or dealer busts
  • Dealer Win: Dealer’s score is higher than player’s without exceeding 21, or player busts
  • Tie: Both player and dealer have the same score

​
Notes

  • Player ranking statistics are automatically updated when a game ends
  • Once a game ends, no further moves can be played on that game
  • All dealer cards are revealed once the game ends

Build docs developers (and LLMs) love

Get started for freeTalk to us