API Reference

This document provides an overview of the three-service sportsbook architecture and links to detailed API documentation for each service.

Base URL

All endpoints are relative to the base URL. The full URL structure follows the pattern:

{your-base-url}/v1/{endpoint}

Architecture Overview

This API documentation covers endpoints from three services in a sportsbook architecture: Feedbird (program-engine), Betbird (betting-engine), and Databird (account-management).

System Architecture

System Components

Frontend Application

The frontend application is responsible for:

• Polling program endpoints from Databird (not directly from Feedbird)
• Displaying sports events, markets, odds, and navigation data
• Sending bet placement POST requests to Databird (which proxies to Betbird)
• Sending account management POST requests directly to Databird

Important: The frontend only communicates with Databird. There is no direct communication between the frontend and Feedbird or Betbird.

Feedbird (Program Engine)

Feedbird generates program/feed data and pushes it to Databird via webhooks:

• Pushes updates for live events, hour events, recommended events, navigation tree, top competitions, and top combos
• Also exposes direct GET endpoints for other consumers (not used by the frontend)
• Focuses exclusively on:
  • Sports data, events, markets, and odds generation
  • Navigation and program structure
  • Real-time and scheduled event information

Feedbird pushes data updates to Databird webhook endpoints, which then aggregates and serves this data to the frontend.

Betbird (Betting Engine)

Betbird provides bet placement APIs:

• Virtual ticket creation and management (/v1/betplacement/virtualTicket/{id})
• Virtual ticket updates with market picks (/v1/betplacement/virtualTicketMarketPicksWithBetBuilder/{id})

Betbird focuses on:

• Bet construction and validation logic
• Virtual ticket management
• Betting calculations

Note: Betbird does NOT handle:

• User authentication or registration
• Deposits or withdrawals
• Transaction processing
• Pre-bet validation checks (balance, limits, etc.)

Databird (Account Management)

Databird serves as the central gateway for the frontend:

• Receives webhooks from Feedbird and aggregates program data
• Provides program endpoints (GET requests) to the frontend:
  • Live events (/v1/program/events/live)
  • Hour events (/v1/program/events/hourEvents/{hour})
  • Recommended events (/v1/program/recommendedEvents)
  • Navigation tree (/v1/program/navigationTree/all)
  • Top competitions (/v1/program/top-competitions)
  • Top combos (/v1/program/top-combos)
• Handles all account management operations:
  • User authentication and registration
  • Deposit and withdrawal operations
  • Transaction processing and history
  • Pre-bet checks (balance verification, betting limits, account status)
• Proxies bet placement requests to Betbird after validation

Databird acts as the single point of contact for the frontend, aggregating data from Feedbird via webhooks and proxying requests to Betbird when needed.

Request Flow Patterns

Program Data Flow (Webhook-Based)

1. Feedbird pushes program data updates to Databird webhook endpoints
2. Databird receives and aggregates the data
3. Frontend polls program endpoints from Databird to retrieve events, markets, odds, and navigation data

The frontend does not communicate directly with Feedbird - all program data is accessed through Databird.

Bet Placement Requests (POST)

Bet placement requests flow through Databird:

1. Frontend sends POST request to Databird
2. Databird performs:
   • Authentication verification
   • Pre-bet checks (balance, limits, account status)
   • Transaction validation
3. If validation passes, Databird proxies the request to Betbird
4. Betbird processes the bet placement logic
5. Response flows back: Betbird → Databird → Frontend

Account Management Requests (POST)

Account management operations (deposits, withdrawals, authentication) are handled directly by Databird.

Data Flow Diagram

Separation of Concerns

This three-service architecture ensures clear separation of concerns: Feedbird generates and pushes sports data via webhooks, Betbird handles betting logic, and Databird serves as the central gateway, aggregating data and handling all user-facing operations and financial transactions.

API Documentation