Sports Picks API Documentation

Authentication

Authorization: Bearer ph_live_…

Keep the credential on your server and send it in the Authorization header. Never expose a production key in browser code, a mobile bundle, or a public repository.

Endpoints

GET /api/v1/me

Partner and active licence metadata.

GET /api/v1/picks

Qualified upcoming, live, settled, or void intelligence.

GET /api/v1/picks/:id

One licensed pick by opaque identifier.

GET /api/v1/results

Licensed settled results.

GET /api/v1/health

Gateway availability without private data.

Filters and pagination

Filter by sport, league, status, result, from, to, limit, and cursor. Times use ISO 8601 UTC; from is inclusive and to is exclusive. The server caps a page at 200 records.

GET /api/v1/picks?sport=MLB&status=upcoming&limit=50

Continue with page.nextCursor while page.hasMore is true. A null cursor marks the end of the current result set.

Record contract

Event identity

id, sport, league, eventDescription, eventDate, homeTeam, and awayTeam.

Market and selection

marketType, selection, line, odds, oddsFormat, and bookmaker.

Intelligence context

probability, confidenceTier, and licensed reasoning.

Lifecycle and provenance

status, result, settledAt, publishedAt, and attribution.

Optional fields are null or removed when the source record or active entitlement does not include them. Consumers should treat the documented schema—not one sample response—as the contract.

Open the public API field dictionary and JSON Schema for field-by-field types, nullability, examples, and lifecycle invariants.

Lifecycle states

upcoming

The qualified record belongs to a future event.

live

The associated event is in progress.

settled

The record has a final result of win, loss, push, or void.

void

The record is no longer eligible for normal settlement or publication.

Delivery formats and availability

REST API

Pull current licensed records using filters and cursor pagination. The customer and PowerHouse agree the appropriate polling cadence during integration.

JSON and CSV

Use protected file delivery for scheduled editorial, data, and operational handoffs when a direct API is unnecessary.

Partner Portal

Review the active licence, inspect available records, and use entitled export actions without exposing a server credential.

Update handling

Consumers should use publishedAt, status, result, and stable record IDs to reconcile changes. Output remains subject to schedule, market availability, quality gates, and the active licence.

PowerHouse does not publish a universal refresh guarantee because the appropriate cadence depends on the sport, event schedule, customer workflow, and licensed delivery route. Production cadence and service expectations are documented during the pilot and commercial agreement.

Errors and traceability

Invalid filters return 400, missing or invalid credentials return 401, unavailable licence access returns 403, and delivery throttles return 429. Error bodies contain a stable code, a safe message, and a request ID. Successful responses also include a request ID and return private, non-cacheable headers.

{
  "error": {
    "code": "INVALID_FILTERS",
    "message": "One or more filters are invalid",
    "requestId": "req_…"
  }
}