API Documentation

curl -X GET "https://realtimesportsapi.com/api/v1/sports" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "20",
      "name": "Football",
      "slug": "football",
      "displayName": "Football"
    },
    {
      "id": "40",
      "name": "Basketball",
      "slug": "basketball",
      "displayName": "Basketball"
    }
  ]
}

curl -X GET "https://realtimesportsapi.com/api/v1/sports/football/leagues" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "28",
      "name": "National Football League",
      "slug": "nfl",
      "abbreviation": "NFL",
      "currentSeason": 2025
    },
    {
      "id": "35",
      "name": "NCAA Football",
      "slug": "college-football",
      "abbreviation": "NCAA"
    }
  ]
}

curl "https://realtimesportsapi.com/api/v1/sports/baseball/leagues/mlb/athletes?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/baseball/leagues/mlb/athletes/30836" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/seasons?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/baseball/leagues/mlb/seasons/2025" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/live" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "401772982",
      "name": "Buffalo Bills at Denver Broncos",
      "shortName": "BUF @ DEN",
      "date": "2026-01-17T21:30Z",
      "status": {
        "state": "in",
        "period": 3,
        "clock": "10:45"
      },
      "homeTeam": {
        "id": "7",
        "name": "Denver Broncos",
        "abbreviation": "DEN",
        "logo": "/api/images/proxy?url=...",
        "color": "0a2343",
        "score": 21
      },
      "awayTeam": {
        "id": "2",
        "name": "Buffalo Bills",
        "abbreviation": "BUF",
        "score": 17
      },
      "venue": {
        "name": "Empower Field at Mile High",
        "city": "Denver",
        "state": "CO"
      }
    }
  ]
}

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401772982" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401772982/plays?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "40177298265",
      "text": "B.Nix pass to P.Bryant for 12 yards",
      "type": { "id": "24", "text": "Pass Reception" },
      "period": 1,
      "clock": { "displayValue": "14:56" },
      "situation": {
        "down": 1,
        "distance": 10,
        "yardLine": 26,
        "downDistanceText": "1st & 10 at DEN 26"
      },
      "yardsGained": 12,
      "athletes": [
        { "type": "passer", "order": 1 },
        { "type": "receiver", "order": 2 }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "total": 213,
      "totalPages": 9,
      "hasNextPage": true
    }
  }
}

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401772982/penalties" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401772982/odds" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "spread": { "line": -3.5, "home": -110, "away": -110 },
    "moneyline": { "home": -180, "away": 150 },
    "overUnder": { "total": 48.5, "over": -110, "under": -110 },
    "provider": "ESPN",
    "updatedAt": "2026-01-28T20:00:00Z"
  }
}

curl "https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/401772982/odds/history?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Live NFL games with current odds (one request)
const res = await fetch(
  'https://realtimesportsapi.com/api/v1/sports/football/leagues/nfl/events/live?includeOdds=true',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const { data: games } = await res.json();
games.forEach(g => {
  console.log(g.name, g.odds?.spread?.line, g.odds?.overUnder?.total);
});

curl "https://realtimesportsapi.com/api/v1/sports/baseball/leagues/mlb/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://realtimesportsapi.com/api/v1/sports/baseball/leagues/mlb/athletes?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Team logos are proxied
"logo": "https://realtimesportsapi.com/api/images/proxy?url=..."

// Direct image access (no auth required)
<img src="/api/images/proxy?url=..." alt="Team Logo" />

X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 49995
X-RateLimit-Reset: 1642636800000  // Unix timestamp

class RealtimeSportsWebSocket {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.ws = null;
    this.token = null;
  }

  async connect() {
    const res = await fetch('https://realtimesportsapi.com/api/websocket/auth', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' }
    });
    const { data } = await res.json();
    this.ws = new WebSocket(`${data.url}?token=${data.token}`);

    this.ws.onopen = () => {
      this.subscribe('event_score_change', { sport: 'football', league: 'nfl' });
      this.subscribe('event_play', { sport: 'football', league: 'nfl', eventId: '401772982' });
    };
    this.ws.onmessage = (e) => {
      const msg = JSON.parse(e.data);
      if (msg.type === 'event_score_change') console.log('Score:', msg.data);
      else if (msg.type === 'event_play') console.log('Play:', msg.data);
      else if (msg.type === 'error') console.error(msg.error);
    };
    this.ws.onclose = () => setTimeout(() => this.connect(), 5000);
  }

  subscribe(eventType, filters = {}, frequency = 'asap') {
    if (this.ws?.readyState === WebSocket.OPEN)
      this.ws.send(JSON.stringify({ type: 'subscribe', event: eventType, filters, frequency }));
  }
  unsubscribe(eventType, filters = {}) {
    if (this.ws?.readyState === WebSocket.OPEN)
      this.ws.send(JSON.stringify({ type: 'unsubscribe', event: eventType, filters }));
  }
  disconnect() { this.ws?.close(); }
}

const client = new RealtimeSportsWebSocket('YOUR_API_KEY');
client.connect();

// Express.js webhook endpoint example
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Your webhook secret (from webhook creation)
const WEBHOOK_SECRET = 'your-webhook-secret';

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  const provided = signature.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(provided)
  );
}

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const eventType = req.headers['x-webhook-event'];
  
  // Verify signature
  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  const { event, timestamp, data } = req.body;
  
  // Handle different event types
  switch (event) {
    case 'event.live':
      console.log(`Game went live: ${data.name}`);
      // Notify users, update database, etc.
      break;
      
    case 'event.score_change':
      console.log(`Score update: ${data.awayTeam.name} ${data.awayTeam.score} - ${data.homeTeam.score} ${data.homeTeam.name}`);
      // Update scores in your app
      break;
      
    case 'event.status_change':
      console.log(`Status changed: ${data.status.type.name}`);
      // Update game status
      break;
      
    case 'event.play':
      console.log(`New play: ${data.play.text}`);
      // Display play in your app
      break;
      
    case 'event.final':
      console.log(`Game ended: Final score ${data.awayTeam.score} - ${data.homeTeam.score}`);
      // Show final results
      break;
  }
  
  // Always return 200 OK
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});