The bidding phase runs clockwise starting from the player immediately left of the dealer. Each player bids independently — bids are not revealed to partners or opponents until all four seats have bid. Bot turns are automatically processed server-side immediately after each human action; you never need to poll while consecutive bot bidders take their turns. The response to your bid already reflects the state after all bot bids have been applied.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Antonelli-Tech-Solutions/spades/llms.txt
Use this file to discover all available pages before exploring further.
POST /api/tables/:tableId/bid
Place a bid during the bidding phase. Valid bid values are the string"nil" (Nil), the string "blind_nil" (Blind Nil — only if eligible), or an integer from 0 to 13.
Required headers: x-session-id, x-player-id
Body
The bid to place. Accepted values:
"nil"— Nil: player commits to taking zero tricks; worth ±50 points."blind_nil"— Blind Nil: player bids before seeing their hand; worth ±100 points. Only allowed when the player’s team is at least 100 points behind the opposing team.0–13— Regular integer bid for that number of tricks.
Bot turns
After the player’s bid is recorded, the server immediately resolves all consecutive bot turns in the bidding order. The response body reflects the game state after all bot bids have been applied. There is no need to poll while bots act.Example — regular bid
Example — Nil bid
Example — Blind Nil bid
Response codes
| Status | Meaning |
|---|---|
200 | Bid accepted. Body: updated player view (see Game State). Bot turns auto-advanced before response. |
400 | Invalid bid value, or player attempted Blind Nil without meeting the 100-point eligibility requirement. |
401 | Missing or invalid session. |
403 | Player is not seated at this table. |
404 | Table not found. |
409 | It is not this player’s turn to bid, or the game is not in the bidding phase. |
POST /api/tables/:tableId/reveal-hand
Reveals the player’s hand so they can inspect their cards before deciding whether to bid Blind Nil. This endpoint is only valid for players who are eligible for Blind Nil (their team is at least 100 points behind the opposing team and they have not yet bid). Callingreveal-hand forfeits Blind Nil eligibility — after revealing, the player must place a regular bid ("nil" or 0–13) instead.
Required headers: x-session-id, x-player-id
No request body is required.
Example
Response codes
| Status | Meaning |
|---|---|
200 | Hand revealed. Body: updated player view with myHand now populated and blindNilEligible: false. |
400 | Player is not eligible to use reveal-hand (team is not 100+ points behind). |
401 | Missing or invalid session. |
403 | Player is not seated at this table. |
404 | Table not found. |
409 | Bid already placed, or game is not in the bidding phase. |
POST /api/tables/:tableId/blind-nil-exchange
Submits cards for the two-step Blind Nil card exchange. After all four players have bid and at least one bid is Blind Nil, the game transitions to theblind_nil_exchange phase before play begins. The exchange proceeds in two steps:
- Step 1 (
blind_to_partner): The Blind Nil player sends 2 cards from their hand to their partner. - Step 2 (
partner_to_blind): The partner sends 2 different cards from their own hand back to the Blind Nil player.
blindNilExchange.step in the game state.
Required headers: x-session-id, x-player-id
Body
An array of exactly 2 card objects to transfer. Cards must exist in the submitting player’s current hand. Each card is an object with
suit (e.g. "spades") and rank (e.g. "A", "10"). See Card representation for the full encoding reference.Bot partner
If the partner seat is occupied by a bot, the server automatically processes the partner’s exchange step (Step 2) immediately after the human Blind Nil player completes Step 1. The response reflects the state after the bot partner has responded.Example
Response codes
| Status | Meaning |
|---|---|
200 | Exchange step accepted. Body: updated player view. If the partner is a bot, Step 2 is auto-processed before the response. |
400 | Wrong number of cards (must be exactly 2), one or more cards are not in the player’s hand, or invalid card format. |
401 | Missing or invalid session. |
403 | Player is not seated at this table. |
404 | Table not found. |
409 | It is not this player’s step in the exchange, or the game is not in the blind_nil_exchange phase. |
Bidding flow
The following steps describe the full bidding sequence for a 4-player game from deal through the start of play.Hand is dealt
The server deals 13 cards to each seat and sets
phase: "bidding". The first bidder is the player immediately left of the dealer (clockwise). On hand 1, North deals, so East bids first.Blind Nil check
Before bidding, any player whose team is at least 100 points behind the opposing team receives
blindNilEligible: true in their state view and does not receive myHand. They must either call POST /reveal-hand (to see their hand and forfeit Blind Nil) or bid "blind_nil" without looking.Players bid in turn
Each player calls
POST /bid with their chosen value when currentBidderSeat matches their seat. The server advances currentBidderSeat clockwise after each valid bid. Bot seats are resolved automatically — the next human player’s response already reflects all intervening bot bids.Blind Nil exchange (if applicable)
If any player bid Blind Nil (
"blind_nil"), the game moves to phase: "blind_nil_exchange". The Blind Nil player calls POST /blind-nil-exchange with 2 cards to send to their partner (Step 1). Their partner then calls the same endpoint with 2 cards to return (Step 2). If the partner is a bot, Step 2 is auto-processed. If both partners bid Blind Nil, each pair completes their exchange sequentially.