API Reference

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"

Replace <your-forge-host> with the host where your FORGE API route is deployed. The example host is a template, not a verified production API hostname. The path shown above is copy-ready once it is joined to that host. No secret is embedded in these examples.

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

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.

News

News reads use the same data:read scope and data_request meter as other stored reads, so existing Professional keys work without change. Results are ordered newest first and paginated with an opaque cursor.

GET /api/public/v1/forge-api/news?limit=25&category=injury
GET /api/public/v1/forge-api/news?published_after=2026-09-01T00:00:00Z&source=espn_nfl
GET /api/public/v1/forge-api/news?cursor=<meta.next_cursor>
GET /api/public/v1/forge-api/teams/KC/news
GET /api/public/v1/forge-api/players/<canonical-player-id>/news

curl "https://<your-forge-host>/api/public/v1/forge-api/teams/KC/news?limit=10" \
  -H "Authorization: Bearer forge_live_EXAMPLEKEY0000000000000000000000"

Query parameters: limit (default 25, maximum 100), cursor, published_after (ISO-8601, since accepted), source and category. Malformed values return 400 invalid_request; an unknown team or player returns 404 not_found.

{
  "api_version": "v1",
  "data": {
    "news": [
      {
        "id": "0f7c…",
        "headline": "Chiefs list starting tackle as limited",
        "source": "espn_nfl",
        "source_name": "ESPN",
        "url": "https://www.espn.com/nfl/story/_/id/…",
        "published_at": "2026-09-08T14:32:00.000Z",
        "category": "injury",
        "teams": ["KC"],
        "players": [{ "player_id": "…", "full_name": "…" }]
      }
    ],
    "meta": { "count": 1, "limit": 25, "next_cursor": null, "attribution": "…" }
  }
}

Attribution and content rights: FORGE returns editorial metadata — headline, source, the publisher's own link, publish time, FORGE category and FORGE team/player associations. Article text is never returned and never republished; third-party article content remains owned by its publisher. Use of this metadata is governed by your FORGE API plan, which does not grant feed redistribution, syndication or publisher content rights.

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.

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