Games You Play REST API

Overview

The Games You Play (GYP) REST API enables server-side management of recreational games, including game retrieval, cancellation, and completion operations.

Prerequisites

• API key configured per API Setup

• Understanding of GYP game lifecycle and statuses

Base URL

Sandbox: https://api.sandbox.lucrasports.com
Production: https://api.lucrasports.com

Authentication

All requests require authentication via the X-Lucra-Api-Key header. See API Setup for details.

Endpoints

Get Matchup

Retrieve details for a specific recreational game.

GET /api/rest/recreational-games/:matchupId
X-Lucra-Api-Key: <your-api-key>

Path Parameters:

• matchupId (string, required) - UUID of the matchup

Response:

{
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdByUserId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "gameId": "nfl-game-12345",
    "winnerGroupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "status": "OPEN",
    "type": "RECREATIONAL_GAME",
    "subtype": "GROUP_VS_GROUP",
    "buyInAmount": 10.0,
    "isPublic": true,
    "groups": [
      {
        "groupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "Team A",
        "users": [
          {
            "userId": "user-uuid",
            "userMetadata": { "externalId": "user-external-id" },
            "username": "player1"
          }
        ]
      }
    ]
  }
}

Matchup Field Descriptions:

Field	Type	Description
id	string	UUID of the matchup
createdByUserId	string	UUID of the user who created the game
gameId	string	External game identifier
winnerGroupId	string	UUID of the winning group (null if game not settled)
status	string	Current game status (see Game Statuses below)
type	string	Always RECREATIONAL_GAME
subtype	string	Game subtype (see Game Subtypes below)
buyInAmount	number	Entry fee per participant
isPublic	boolean	Whether the game is publicly visible
groups	array	Array of participant groups

Group Field Descriptions:

Field	Type	Description
groupId	string	UUID of the group
name	string	Display name for the group
users	array	Array of users participating in group

User Field Descriptions:

Field	Type	Description
userId	string	UUID of the user
username	string	Display name of the user

Game Statuses:

• OPEN - Game created, accepting players

• CONFIRMED - Minimum players joined, game confirmed

• LOCKED - Game locked, no more players can join

• PENDING_OUTCOMES - Game in progress, awaiting results

• CLOSED - Game completed with winner

• CLOSED_TIE - Game completed in a tie

• DISPUTE - Game outcome disputed

• CANCELED_BY_OWNER - Owner canceled the game

• CANCELED_NOT_ACCEPTED - Canceled due to insufficient players

• CANCELED_THROUGH_API - Canceled via API call

• CANCELED_TIMEOUT - Canceled due to timeout

Game Subtypes:

• GROUP_VS_GROUP - Team-based games

• FREE_FOR_ALL - Individual player games

Cancel Matchup

Cancel an existing recreational game.

PUT /api/rest/recreational-games/:matchupId/cancel
X-Lucra-Api-Key: <your-api-key>
Content-Type: application/json

{}

Path Parameters:

• matchupId (string, required) - UUID of the matchup to cancel

Request Body:

{}

Response:

{
  "cancel": {
    "code": 200,
    "body": "Matchup canceled successfully"
  }
}

Notes:

• Cancellation refunds buy-ins to all participants

• Only games in OPEN or CONFIRMED status can be canceled

• Triggers RecreationalGameCanceled webhook event

Complete Matchup

Mark a recreational game as complete and declare outcome.

PUT /api/rest/recreational-games/:matchupId/complete
X-Lucra-Api-Key: <your-api-key>
Content-Type: application/json

Path Parameters:

• matchupId (string, required) - UUID of the matchup to complete

Request Body (with winner):

{
  "outcome": {
    "isTie": false,
    "winningGroupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
  }
}

Request Body (tie):

{
  "outcome": {
    "isTie": true
  }
}

Field Descriptions:

Field	Type	Required	Description
isTie	boolean	Yes	Set to true for a tie, false for a winner
winningGroupId	string	No	UUID of the winning group (required when isTie is false, omit if true)

Response:

{
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CLOSED",
    "winnerGroupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    ...
  }
}

Notes:

• winningGroupId must match a group participating in the matchup

• Completing a game distributes winnings to winners

• Status changes to CLOSED or CLOSED_TIE depending on outcome

• Triggers RecreationalGameCompleted webhook event

Error Handling

Standard HTTP status codes are used:

Status	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Matchup does not exist
500	Internal Server Error

Game Lifecycle

OPEN → CONFIRMED → LOCKED → PENDING_OUTCOMES → CLOSED/CLOSED_TIE
  ↓         ↓         ↓            ↓
CANCELED ← ← ← ← ← ← ← ← ← ← ← ← ← ←

Related Documentation

• Games You Play Webhooks - Webhook events for GYP games

• Free-to-Play REST API - Free-to-play variant endpoints

• Webhook Setup - Configure webhook subscriptions