Vendors API Endpoints

Overview

Endpoints for managing data providers, vendors, and external service integrations.

Endpoint Summary

Endpoint Method Auth Description
/v1/data-providers GET None Get all data providers
/v1/data-providers/{providerId} GET None Get provider details
/v1/data-providers/{providerId}/sports GET None Get provider sports
/v1/data-providers/{providerId}/leagues GET None Get provider leagues
/v1/vendors GET Admin Get all vendors
/v1/vendors POST Admin Create vendor
/v1/vendors/{vendorId} GET Admin Get vendor details
/v1/vendors/{vendorId} PUT Admin Update vendor
/v1/vendors/{vendorId} DELETE Admin Delete vendor
/v1/vendors/{vendorId}/status PATCH Admin Update vendor status
/v1/vendors/{vendorId}/apikeys GET Admin Get vendor API keys
/v1/vendors/{vendorId}/apikeys POST Admin Create vendor API key
/v1/vendors/{vendorId}/apikeys/{keyId} DELETE Admin Delete vendor API key
/v1/vendors/{vendorId}/usage GET Admin Get vendor usage stats

Data Providers

GET /v1/data-providers

Description: Retrieves all available data providers.

Response: DataProvidersResponse

{
  "providers": [
    {
      "id": 1,
      "name": "SportsRadar",
      "code": "SPORTSRADAR",
      "description": "Primary sports data provider",
      "supportedSports": ["football", "basketball", "baseball", "hockey"],
      "features": ["live-odds", "play-by-play", "statistics"],
      "status": "active"
    },
    {
      "id": 2,
      "name": "OddsAPI",
      "code": "ODDSAPI",
      "description": "Odds aggregation service",
      "supportedSports": ["all"],
      "features": ["odds", "lines", "spreads"],
      "status": "active"
    }
  ]
}

GET /v1/data-providers/{providerId}

Description: Retrieves specific data provider details.

Path Parameters:

Response: DataProvider

{
  "id": 1,
  "name": "SportsRadar",
  "code": "SPORTSRADAR",
  "description": "Primary sports data provider",
  "website": "https://sportradar.com",
  "apiDocumentation": "https://developer.sportradar.com",
  "supportedSports": [
    {"id": 1, "name": "Football", "code": "NFL"},
    {"id": 2, "name": "Basketball", "code": "NBA"}
  ],
  "features": {
    "liveOdds": true,
    "playByPlay": true,
    "playerStats": true,
    "teamStats": true,
    "injuries": true,
    "weather": false
  },
  "updateFrequency": {
    "odds": "realtime",
    "scores": "realtime",
    "stats": "hourly"
  },
  "status": "active",
  "lastSync": "2025-11-29T12:00:00Z"
}

GET /v1/data-providers/{providerId}/sports

Description: Retrieves sports supported by a provider.

Path Parameters:

Response:

{
  "providerId": 1,
  "sports": [
    {"id": 1, "name": "Football", "code": "NFL", "active": true},
    {"id": 2, "name": "Basketball", "code": "NBA", "active": true},
    {"id": 3, "name": "Baseball", "code": "MLB", "active": true},
    {"id": 4, "name": "Hockey", "code": "NHL", "active": true}
  ]
}

GET /v1/data-providers/{providerId}/leagues

Description: Retrieves leagues supported by a provider.

Path Parameters:

Query Parameters:

Parameter Type Description
sportId int Filter by sport

Response:

{
  "providerId": 1,
  "leagues": [
    {"id": 1, "name": "NFL", "sportId": 1, "active": true},
    {"id": 2, "name": "NCAAF", "sportId": 1, "active": true},
    {"id": 3, "name": "NBA", "sportId": 2, "active": true},
    {"id": 4, "name": "NCAAB", "sportId": 2, "active": true}
  ]
}

Vendor Management (Admin)

GET /v1/vendors

Description: Retrieves all vendors (admin access).

Authentication: Admin JWT required

Response: VendorsResponse

{
  "vendors": [
    {
      "id": 1,
      "name": "Partner App",
      "email": "contact@partnerapp.com",
      "status": "active",
      "tier": "premium",
      "createdAt": "2024-01-15T00:00:00Z",
      "lastActivity": "2025-11-29T11:30:00Z"
    }
  ],
  "total": 45
}

POST /v1/vendors

Description: Creates a new vendor account.

Authentication: Admin JWT required

Request Body:

{
  "name": "New Partner",
  "email": "contact@newpartner.com",
  "tier": "standard",
  "website": "https://newpartner.com",
  "contactPerson": "John Doe",
  "phone": "+1-555-0123",
  "notes": "Partner for mobile integration",
  "permissions": ["read:games", "read:odds", "read:picks"]
}

Response: CreateVendorResponse

{
  "id": 46,
  "name": "New Partner",
  "status": "pending",
  "apiKey": "vnd_live_abc123...",
  "createdAt": "2025-11-29T12:00:00Z"
}

GET /v1/vendors/{vendorId}

Description: Retrieves vendor details.

Authentication: Admin JWT required

Path Parameters:

Response: Vendor

{
  "id": 1,
  "name": "Partner App",
  "email": "contact@partnerapp.com",
  "status": "active",
  "tier": "premium",
  "website": "https://partnerapp.com",
  "contactPerson": "Jane Smith",
  "phone": "+1-555-0456",
  "permissions": ["read:games", "read:odds", "read:picks", "write:picks"],
  "limits": {
    "requestsPerMinute": 1000,
    "requestsPerDay": 100000
  },
  "createdAt": "2024-01-15T00:00:00Z",
  "lastActivity": "2025-11-29T11:30:00Z"
}

PUT /v1/vendors/{vendorId}

Description: Updates vendor information.

Authentication: Admin JWT required

Path Parameters:

Request Body:

{
  "name": "Updated Partner Name",
  "email": "newemail@partner.com",
  "tier": "premium",
  "permissions": ["read:games", "read:odds", "read:picks", "write:picks"],
  "limits": {
    "requestsPerMinute": 2000,
    "requestsPerDay": 200000
  }
}

Response: UpdateVendorResponse

DELETE /v1/vendors/{vendorId}

Description: Deletes a vendor account.

Authentication: Admin JWT required

Path Parameters:

Response: 204 No Content

PATCH /v1/vendors/{vendorId}/status

Description: Updates vendor status.

Authentication: Admin JWT required

Path Parameters:

Request Body:

{
  "status": "suspended",
  "reason": "Rate limit violations"
}

Status Values:

Response:

{
  "id": 1,
  "status": "suspended",
  "updatedAt": "2025-11-29T12:00:00Z"
}

Vendor API Keys

GET /v1/vendors/{vendorId}/apikeys

Description: Retrieves vendor's API keys.

Authentication: Admin JWT required

Path Parameters:

Response:

{
  "vendorId": 1,
  "keys": [
    {
      "id": 101,
      "name": "Production Key",
      "prefix": "vnd_live_abc...",
      "status": "active",
      "lastUsed": "2025-11-29T11:30:00Z",
      "createdAt": "2024-01-15T00:00:00Z"
    },
    {
      "id": 102,
      "name": "Development Key",
      "prefix": "vnd_test_xyz...",
      "status": "active",
      "lastUsed": "2025-11-28T15:00:00Z",
      "createdAt": "2024-06-01T00:00:00Z"
    }
  ]
}

POST /v1/vendors/{vendorId}/apikeys

Description: Creates a new API key for vendor.

Authentication: Admin JWT required

Path Parameters:

Request Body:

{
  "name": "New Production Key",
  "environment": "live",
  "permissions": ["read:games", "read:odds"]
}

Response:

{
  "id": 103,
  "name": "New Production Key",
  "key": "vnd_live_full_key_visible_once_only",
  "prefix": "vnd_live_ful...",
  "createdAt": "2025-11-29T12:00:00Z"
}

Note: The full API key is only shown once upon creation.

DELETE /v1/vendors/{vendorId}/apikeys/{keyId}

Description: Revokes a vendor API key.

Authentication: Admin JWT required

Path Parameters:

Response: 204 No Content

Vendor Usage Statistics

GET /v1/vendors/{vendorId}/usage

Description: Retrieves vendor API usage statistics.

Authentication: Admin JWT required

Path Parameters:

Query Parameters:

Parameter Type Description
startDate date Start of period (YYYY-MM-DD)
endDate date End of period (YYYY-MM-DD)
granularity string "hour", "day", "week", "month"

Response:

{
  "vendorId": 1,
  "period": {
    "start": "2025-11-01",
    "end": "2025-11-29"
  },
  "summary": {
    "totalRequests": 2450000,
    "successfulRequests": 2445000,
    "failedRequests": 5000,
    "avgResponseTime": 45,
    "peakRequestsPerMinute": 850
  },
  "byEndpoint": [
    {"endpoint": "/v1/games", "requests": 1200000, "avgResponseTime": 42},
    {"endpoint": "/v1/odds", "requests": 800000, "avgResponseTime": 38},
    {"endpoint": "/v1/picks", "requests": 450000, "avgResponseTime": 55}
  ],
  "timeline": [
    {"date": "2025-11-01", "requests": 85000},
    {"date": "2025-11-02", "requests": 92000}
  ]
}

Examples

Get All Data Providers

curl -X GET "https://api.example.com/v1/data-providers"

Get Provider Sports

curl -X GET "https://api.example.com/v1/data-providers/1/sports"

Create Vendor (Admin)

curl -X POST "https://api.example.com/v1/vendors" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Partner",
    "email": "contact@partner.com",
    "tier": "standard"
  }'

Get Vendor Usage Stats (Admin)

curl -X GET "https://api.example.com/v1/vendors/1/usage?startDate=2025-11-01&endDate=2025-11-29" \
  -H "Authorization: Bearer eyJ..."

Create Vendor API Key (Admin)

curl -X POST "https://api.example.com/v1/vendors/1/apikeys" \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key", "environment": "live"}'

Related Endpoints