Reference · GraphQL

POST /v1/graphql

GraphQL API

Query the live, typed gateway at one endpoint. This reference describes the exposed schema directly, so you can build requests without relying on introspection.

Endpoint

POST https://api.archivist.dev/v1/graphql

Authentication and request shape

Every request requires an Authorization: Bearer <token> header. Keep the token in a server-side environment variable or secret manager. Do not put it in browser JavaScript, a mobile app, a public repository, or a NEXT_PUBLIC_* variable.

Send JSON with a required string query and optional variables and operationName properties.

request body···

{
  "query": "query { members { items { member_id } } }",
  "variables": {},
  "operationName": "Members"
}

Typed query surface

The root fields below are the complete exposed query surface. Pass each field its named input object as input; all five return a paged result.

bills

input: BillsInput

optional input

congress: Int: Congress number to match.
type: String: Bill type such as hr or s.
q: String: Text search across the bill record.
cursor: String: Opaque cursor from a previous page.
limit: Int: Page size from 1 to 100; defaults to 25.

members

input: MembersInput

optional input

state: String: Two-letter state or territory code, such as CA.
chamber: String: house or senate.
congress: Int: Congress number in which the member served.
cursor: String: Opaque cursor from a previous page.
limit: Int: Page size from 1 to 100; defaults to 25.

regulatoryFilings

input: RegulatoryFilingsInput

optional input

agency_id: String: Exact agency identifier.
agency_name: String: Case-insensitive agency-name match.
type: RegulatoryFilingType: RULE, PROPOSED_RULE, NOTICE, or PRESIDENTIAL_DOCUMENT.
filing_year: Int: Calendar year of the filing.
filing_period: RegulatoryFilingPeriod: Q1, Q2, Q3, Q4, or AMENDMENT.
rIN: String: Exact Regulation Identifier Number.
docket_id: String: Docket identifier contained by the filing.
cursor: String: Opaque cursor from a previous page.
limit: Int: Page size from 1 to 100; defaults to 25.

federalBudgets

input: FederalBudgetsInput!

required input

dataset: FederalBudgetDataset!: APPROPRIATIONS or OUTLAYS.
congress: Int: Congress number to match.
fiscal_year: Int: Fiscal year to match.
month: String: OUTLAYS only; YYYY-MM.
agency: String: Case-insensitive agency-name match.
bureau_code: String: APPROPRIATIONS only; bureau code.
account: String: Case-insensitive account-title match.
cursor: String: Opaque cursor from a previous page.
limit: Int: Page size from 1 to 100; defaults to 25.

The dataset field is required. Use bureau_code with APPROPRIATIONS and month with OUTLAYS.

lobbyingDisclosures

input: LobbyingDisclosuresInput

optional input

registrant_name: String: Case-insensitive registrant-name match.
registrant_id: String: Exact registrant identifier.
client_name: String: Case-insensitive client-name match.
client_id: String: Exact client identifier.
lobbyist_name: String: Case-insensitive lobbyist-name match.
filing_year: Int: Calendar year of the filing.
filing_period: LobbyingFilingPeriod: Q1, Q2, Q3, Q4, or AMENDMENT.
issue_area: String: Issue code contained by the filing.
agency_acted_on: String: Agency contained by the filing.
cursor: String: Opaque cursor from a previous page.
limit: Int: Page size from 1 to 100; defaults to 25.

Cursor pagination

Every root query uses the same pagination inputs: cursor: String is an opaque value, and limit: Int accepts 1–100 and defaults to 25. The page response returns nextCursor; when it is non-null, pass that exact value as the next request’s cursor. A final page returns null.

pagination variables···

{
  "input": {
    "limit": 25,
    "cursor": "opaque-cursor-from-the-previous-response"
  }
}

Response envelopes

A successful request is HTTP 200 with a top-level data object. The selected root field contains items and nullable nextCursor.

successful response···

{
  "data": {
    "members": {
      "items": [],
      "nextCursor": null
    }
  }
}

GraphQL execution errors can accompany partial data, or make it null, in a top-level errors array. Read both keys when handling a 200 response.

Bills result

bills returns BillsPage! with items: [Bill!]! and nextCursor: String. An exclamation mark means non-null; a type without it may be null.

Use bill(id: ID!): Bill to resolve one normalized bill by its table identifier. The field is nullable, so an unknown identifier returns bill: null without a GraphQL execution error.

single bill query···

query Bill($id: ID!) {
  bill(id: $id) {
    id
    congress
    type
    number
    officialTitle
    introducedDate
    memberName
    memberBioguideId
    memberByCongressKey
    committeeNames
    sourceUrl
    lastSyncedAt
  }
}

Field	Type	Meaning
id	ID!	Stable bill identifier.
congress	Int!	Congress number.
type	String!	Bill type, for example hr or s.
number	Int!	Bill number within its type and Congress.
officialTitle	String!	Official bill title.
introducedDate	String	Nullable ISO date/time for introduction.
memberName	String	Nullable sponsor/member display name.
memberBioguideId	String	Nullable sponsor Bioguide identifier.
memberByCongressKey	String	Nullable per-Congress sponsor key.
committeeNames	String!	Committee names recorded on the bill.
sourceUrl	String	Nullable upstream source URL.
lastSyncedAt	String!	ISO date/time of the last mirror sync.

Members result

members returns MembersPage! with items: [Member!]! and nextCursor: String.

Field	Type	Meaning
member_id	ID!	Stable member identifier.
bioguide_id	ID!	Bioguide identifier; currently the same stable key.
name	String!	Member display name.
state	String	Nullable represented state or territory.
terms	[MemberTerm!]!	Non-null list of the member’s recorded terms.

MemberTerm

Field	Type	Meaning
congress	Int!	Congress number for the term.
chamber	String!	House or Senate chamber.
party	String	Nullable party recorded for the term.

Errors and status codes

HTTP	Envelope	Meaning
401 / 403	{ "error": "..." }	Missing, invalid, revoked, or suspended credentials; authentication and access failures.
429	{ "error": "Rate limit exceeded" }	Rate limited. Read the Retry-After header and retry after that many seconds.
400	{ "errors": [{ "message": "..." }] }	Malformed request JSON, a missing string query, or invalid variables/operationName.
200	{ "data": ..., "errors": [...] }	GraphQL execution or validation errors can accompany partial data or a null data value.
500	{ "error": "Internal Server Error" }	Unexpected server failure.

Runnable examples

These server-side curl requests include representative filters and pagination variables. Set ARCHIVIST_KEY in your shell first; the bearer token never needs to appear in the query document.

Bills

curl · bills···

curl 'https://api.archivist.dev/v1/graphql' \
  -H "Authorization: Bearer $ARCHIVIST_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "query": "query Bills($input: BillsInput) {\n  bills(input: $input) {\n    items {\n      id\n      congress\n      type\n      number\n      officialTitle\n      introducedDate\n      memberName\n      memberBioguideId\n      committeeNames\n      sourceUrl\n    }\n    nextCursor\n  }\n}",
  "variables": {
    "input": { "congress": 118, "type": "hr", "q": "records", "limit": 25 }
  }
}
JSON

response · bills···

{
  "data": {
    "bills": {
      "items": [{ "id": "118-hr-1", "officialTitle": "...", "number": 1 }],
      "nextCursor": "opaque-cursor"
    }
  }
}

Members

curl · members···

curl 'https://api.archivist.dev/v1/graphql' \
  -H "Authorization: Bearer $ARCHIVIST_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "query": "query Members($input: MembersInput) {\n  members(input: $input) {\n    items {\n      member_id\n      bioguide_id\n      name\n      state\n      terms {\n        congress\n        chamber\n        party\n      }\n    }\n    nextCursor\n  }\n}",
  "variables": {
    "input": { "state": "CA", "chamber": "house", "congress": 118, "limit": 25 }
  }
}
JSON

response · members···

{
  "data": {
    "members": {
      "items": [{
        "member_id": "P000197",
        "bioguide_id": "P000197",
        "name": "...",
        "state": "CA",
        "terms": [{ "congress": 118, "chamber": "house", "party": "..." }]
      }],
      "nextCursor": null
    }
  }
}