Contests API Endpoints

Overview

Endpoints for managing contests, fantasy leagues, and competitions.

Endpoint Summary

Contest Types

GET /v1/contests/types

Description: Retrieves available contest types.

Response: ContestTypesResponse

{
  "types": [
    {
      "id": 1,
      "name": "Pick'em",
      "description": "Pick winners against the spread",
      "maxParticipants": 100,
      "entryFee": 0
    },
    {
      "id": 2,
      "name": "Fantasy Draft",
      "description": "Draft players and compete",
      "maxParticipants": 12,
      "entryFee": 25
    }
  ]
}

Contest Management

GET /v1/contests

Description: Retrieves all available contests.

Query Parameters:

Response: ContestsResponse

{
  "contests": [
    {
      "id": 12345,
      "name": "NFL Week 13 Pick'em",
      "type": "pick_em",
      "status": "active",
      "createdBy": "user123",
      "participants": 45,
      "maxParticipants": 100,
      "startDate": "2025-11-29",
      "endDate": "2025-12-01",
      "prizePool": 0,
      "isPublic": true
    }
  ]
}

POST /v1/contests

Description: Creates a new contest.

Authentication: Optional (anonymous creates with default user)

Request Body:

{
  "name": "My NFL Contest",
  "type": "pick_em",
  "description": "Weekly NFL picks competition",
  "maxParticipants": 50,
  "isPublic": true,
  "leagueId": 1,
  "startDate": "2025-11-29",
  "endDate": "2025-12-01",
  "rules": {
    "picksPerWeek": 5,
    "spreadRequired": true
  }
}

Response: CreateContestResponse

{
  "id": 12345,
  "name": "My NFL Contest",
  "inviteCode": "ABC123",
  "createdAt": "2025-11-29T12:00:00Z"
}

GET /v1/contests/{contestId}

Description: Retrieves detailed contest information.

Path Parameters:

• contestId (long) - Contest identifier

Response: Contest

{
  "id": 12345,
  "name": "NFL Week 13 Pick'em",
  "type": "pick_em",
  "status": "active",
  "description": "Weekly NFL picks competition",
  "createdBy": {
    "id": "user-123",
    "username": "john_doe",
    "avatar": "https://..."
  },
  "participants": [
    {
      "userId": "user-456",
      "username": "jane_doe",
      "rank": 1,
      "points": 45,
      "record": "9-2"
    }
  ],
  "rules": {
    "picksPerWeek": 5,
    "spreadRequired": true
  },
  "leaderboard": [...]
}

PATCH /v1/contests/{contestId}

Description: Updates contest settings.

Authentication: JWT required (must be contest owner)

Path Parameters:

• contestId (long) - Contest identifier

Request Body:

{
  "name": "Updated Contest Name",
  "description": "New description",
  "isPublic": false
}

Response: UpdateContestResponse

DELETE /v1/contests/{contestId}

Description: Deletes a contest.

Authentication: JWT required (must be contest owner)

Path Parameters:

• contestId (long) - Contest identifier

Response: true on success

Contest Participation

POST /v1/contests/{contestId}/join

Description: Joins a contest.

Authentication: JWT required

Path Parameters:

• contestId (long) - Contest to join

Request Body:

{
  "inviteCode": "ABC123"
}

Response: JoinContestResponse

{
  "success": true,
  "contestId": 12345,
  "participantId": 67890,
  "joinedAt": "2025-11-29T12:00:00Z"
}

DELETE /v1/users/contests/{contestId}/memberships

Description: Leaves a contest.

Authentication: JWT required

Path Parameters:

• contestId (long) - Contest to leave

Response: 204 No Content

POST /v1/contests/{contestId}/invitations

Description: Sends contest invitations.

Authentication: JWT required

Path Parameters:

• contestId (long) - Contest ID

Request Body:

{
  "emails": ["friend1@example.com", "friend2@example.com"],
  "message": "Join my NFL contest!"
}

Response: 204 No Content

User Contests

GET /v1/users/contests

Description: Retrieves contests the user is participating in.

Authentication: JWT required

Query Parameters:

Response: ContestsResponse

Fantasy Draft

GET /v1/contests/fantasy/draft/mock/{contestId}

Description: Retrieves fantasy draft contest details.

Path Parameters:

• contestId (long, optional) - Specific contest or all

Response: FantasyDraftMockContestResponse

{
  "id": 12345,
  "name": "NFL Fantasy Draft",
  "draftOrder": [
    {"position": 1, "userId": "user-123", "username": "john_doe"},
    {"position": 2, "userId": "user-456", "username": "jane_doe"}
  ],
  "availablePlayers": [
    {"id": 789, "name": "Patrick Mahomes", "position": "QB", "team": "Chiefs"}
  ],
  "picks": [
    {"round": 1, "pick": 1, "playerId": 789, "userId": "user-123"}
  ],
  "currentPick": {
    "round": 2,
    "pick": 1,
    "userId": "user-456",
    "timeRemaining": 120
  }
}

POST /v1/contests/fantasy/draft/mock/{contestId}

Description: Submits fantasy draft picks.

Path Parameters:

• contestId (long) - Contest ID

Request Body:

{
  "picks": [
    {"playerId": 789, "round": 1},
    {"playerId": 790, "round": 2}
  ]
}

Response: 200 OK

Headers (on warnings):

• X-Warnings: Warning messages

DELETE /v1/contests/fantasy/draft/mock/{contestId}

Description: Deletes a fantasy draft contest.

Authentication: JWT required

Path Parameters:

• contestId (long) - Contest to delete

Response:

{
  "message": "Fantasy draft mock contest deleted successfully",
  "contestId": 12345
}

Examples

Get Active Contests

curl -X GET "https://api.example.com/v1/contests?status=active"

Create a Contest

curl -X POST "https://api.example.com/v1/contests" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Contest",
    "type": "pick_em",
    "maxParticipants": 50
  }'

Join a Contest

curl -X POST "https://api.example.com/v1/contests/12345/join" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"inviteCode": "ABC123"}'

Get User's Contests

curl -X GET "https://api.example.com/v1/users/contests" \
  -H "Authorization: Bearer eyJ..."

Related Endpoints

• User Management - User accounts
• Systems - Betting strategies