The REST API v1

The versioned /api/v1/* surface is FedGrade's durable programmatic contract: a consistent JSON envelope, scoped API keys, a provenance block on every data object, and a machine-readable OpenAPI 3.1 spec. It is the same data and the same provenance discipline as the MCP server, over plain HTTP. The full reference is at /docs/api/v1; this is the orientation. The API requires an Enterprise+ key.

The endpoints

v1 is read-oriented — seven GET reads and one POST:

The envelope

Every response is one of two shapes — switch on ok:

• Success: { ok: true, data: {…}, meta: { api_version, endpoint, pagination } }
• Error: { ok: false, error: { code, message, required_scope? }, meta: {…} }

Authentication and scopes

Send your key as a Bearer token: Authorization: Bearer fg_live_…. Issue keys at /settings/api-keys (see API keys), granting the scopes each key needs. Each endpoint enforces exactly one scope; a request whose key lacks it gets 403 forbidden_scope even when the tier and rate budget are fine. The * wildcard satisfies any check, and legacy pre-v1 scopes (read:brief, read:search, read:forecast, read:network) alias forward automatically.

Provenance on every object

Every data object carries a provenance block: a grade (verified / source-cited / modeled / insufficient-evidence) and a citations[] array. The same discipline that runs through the whole platform applies to the API — nothing comes back ungraded or uncited.

Pagination

Collection endpoints take page (1-indexed) and page_size, and return a pagination block in meta with total, total_pages, and has_more.

The spec

The machine-readable OpenAPI 3.1 spec is served auth-free at GET /api/v1/openapi.json. Point a client generator at it to scaffold a typed client. See also the API overview and the MCP server for the agent transport over the same data.