GraphQL warehouse API

Hodoflow's GraphQL surface has one application-data job: read warehouse records through factQuery. It is mounted at POST /api/graphql, requires api_read, and addresses a data model by slug as a logical table. Its mapped fields are the columns and each Fact.data object is one row.

Configuration and observability remain on JSON:API. GraphQL exposes no mutations. The schema currently exposes no subscription fields, so there is no public subscription capability to build against.

Before your first query

Unlike the JSON:API quickstart, factQuery needs product state:

1. create a data model and its fields in Warehouse;
2. run a workflow that persists at least one mapped record if you want a populated result;
3. obtain the model's slug through JSON:API or the application; and
4. authenticate with an active service account carrying api_read.

Follow Run your first warehouse query for the exact requests and checkpoints.

Query modes

latest is the default and returns one current row per entity. Rows without an entity ID are excluded because no entity identity exists to collapse.

timeline returns historical versions inside a time window. When omitted, until defaults to now and since defaults to 90 days before it. A requested span wider than 366 days is clamped to 366 days. Explicit bounds also apply in latest mode as normal filters.

See factQuery arguments and results for every argument and response field.

Pagination and cost

Offset pagination defaults to 50 rows and rejects a limit above 250. Pass a limit explicitly anyway. The useful limit can be lower because complexity is based on page size and selected fields.

Default configurable guards are:

Filters are a JSON array encoded inside a GraphQL string, at most 20 entries. Use query variables rather than hand-escaping it inline. Continue with Filters, pagination, and limits.

Authentication and errors

Send Authorization: Bearer $TOKEN and Content-Type: application/json. factQuery requires api_read and the run-as member's active workspace access. The health liveness field is public and is the only exception.

Parsed GraphQL failures can return HTTP 200 with an errors array. Invalid tokens and rate limits happen at the transport layer and use non-200 API error responses. Always inspect both status and GraphQL errors.

Machine reference

• factQuery browser reference
• GraphQL SDL
• SDL usage guide
• x-api-version returns the date-based GraphQL schema identity

The application may expose GraphiQL in development, but integrations must not depend on a production playground.