FORGE

FORGE Professional API v1

API Reference

The FORGE Professional API is the only programmatic entry point to FORGE. Requests are authenticated with an organization API key, checked against your entitlement and scopes, metered, and then served either from stored published FORGE data or by queueing a computation. The FORGE model itself is never exposed and is never reachable directly.

Manage your organization and keys in the developer console.

Base path and authentication

/api/public/v1/forge-api/<endpoint>

curl "https://<your-forge-host>/api/public/v1/forge-api/rankings?season=2026&week=1" \
  -H "Authorization: Bearer forge_live_EXAMPLEKEY0000000000000000000000"

# equivalent header form
  -H "x-forge-api-key: forge_live_EXAMPLEKEY0000000000000000000000"

Keys are shown once at creation and stored only as a hash. Example keys on this page are placeholders and are not valid. Browser sign-in sessions cannot authenticate API requests, and API keys cannot be used to sign in.

Stored data vs metered compute

Reads of published FORGE output are cheap request units. Fresh projections and full-season simulations run the FORGE engine, are queued through the platform compute controls, and consume compute units. Compute output is your organization's development output: it is never Official FORGE output and never changes anything shown on public pages.

  • data_request — Stored data request
  • projection_compute — Season projection computation
  • season_simulation_compute — Full-season simulation computation

Scopes

  • data:read — Published rankings, teams, games and projections
  • analytics:read — Stored team, position-group and player analytics
  • archive:read — Stored historical archive reads
  • compute:submit — Queue a projection or simulation computation
  • compute:read — Read your organization's computation status and results
  • usage:read — Read your organization's API usage and allowances

Endpoints

MethodPathScopeMeterStatus
GET
/health
Gateway health and API version.
——Available
GET
/docs
Machine-readable endpoint catalogue and scopes.
——Available
GET
/usage
Your organization's current allowances and usage.
usage:read—Available
GET
/rankings
Published FORGE rankings. Optional season, week.
data:readdata_requestAvailable
GET
/teams
Published team directory with current rank and record.
data:readdata_requestAvailable
GET
/games
Published games with FORGE projections. Optional season, week.
data:readdata_requestAvailable
GET
/analytics/teams/{abbreviation}
Stored team analytics for a published run.
analytics:readdata_requestAvailable
GET
/analytics/teams/{abbreviation}/position-groups
Stored position-group analytics.
analytics:readdata_requestAvailable
GET
/analytics/players/{playerId}
Stored player analytics by canonical player id.
analytics:readdata_requestAvailable
GET
/archive/games
Stored historical projections. Filter by season, week.
archive:readdata_requestAvailable
POST
/compute/jobs
Queue a season projection or full-season simulation from stored FORGE state.
Metered as projection_compute or season_simulation_compute depending on action. Development output only — never Official.
compute:submitprojection_computeAvailable
GET
/compute/jobs/{jobId}
Status of one of your organization's computations.
compute:read—Available
GET
/compute/jobs/{jobId}/result
Rendered result of a completed computation.
compute:read—Available
GET
/compute/capabilities
Which scenario override kinds the FORGE engine currently advertises (scenario_overrides.v1).
Read from the stored engine handshake; never contacts the engine. Override kinds not listed here are refused.
compute:read—Available
GET
/compute/eligible-games
Future, unplayed games that may carry a forced_game_outcome override. Optional projection_week.
compute:readdata_requestAvailable
GET
/compute/rosters/{teamId}
Roster (canonical player ids) for one team at the current FORGE state, for player_availability overrides.
compute:readdata_requestAvailable
POST
/compute/what-if
Queue a scenario with typed scenario_overrides.v1 overrides (forced_game_outcome, player_availability).
Capability-gated: each override kind must be advertised by the engine handshake or the request is refused before any allowance is used. Scenario output only — never Official.
compute:submitprojection_computeAvailable

Example responses

{
  "api_version": "v1",
  "data": [ { "team": "KC", "forge_rank": 1, "forge_rating": 0.0 } ],
  "meta": { "meter": "data_request", "units": 1 }
}

{
  "api_version": "v1",
  "error": { "code": "quota_exceeded", "message": "Monthly allowance exhausted." }
}

Successful responses carry x-forge-quota-limit, x-forge-quota-remaining and x-forge-meter headers.

Errors

  • 401 unauthorized
  • 403 forbidden
  • 403 insufficient_scope
  • 429 rate_limited
  • 429 quota_exceeded
  • 404 not_found
  • 409 conflict
  • 400 invalid_request
  • 501 unsupported
  • 503 unavailable
  • 500 internal_error

Platform safeguards

These are operational defaults, not prices and not contractual allowances. They are configurable per organization.

TierStored data requestSeason projection computationFull-season simulation computation
professional50,000 / month · 120 / minute100 / month · 5 / minute20 / month · 1 / minute
enterprise500,000 / month · 600 / minute1,000 / month · 20 / minute200 / month · 5 / minute

Usage rights

API access defaults to internal use only. Redistribution, resale and derived commercial products are not granted by default and must be agreed separately. Your organization's current permissions are shown in the developer console.

  • internal_use — Internal use
  • commercial_use — Commercial use
  • redistribution — Redistribution of FORGE output
  • derived_products — Derived products built on FORGE output