API and data guide

Public research routes

Public coverage and source-status routes do not require a key. Coverage describes dated research evidence and gaps. The public coverage route has a default and maximum page size of 20. Source status reports live health for a featured set of DFW meeting sources. It does not cover every entry in the research catalog.

Authenticated civic data routes

Health keeps lifetime document fetch failures in pipeline.documentDeadLetters. The separate pipeline.actionableDocumentDeadLetters count covers failed documents for meetings today or later in America/Chicago. A current document fetch failure causes degraded status unless it is an oversized-document failure covered by another document from the same source, meeting time, and title. Coverage accepts any readable or OCR document with `document_type` other than `minutes`: agendas, packets, staff reports, attachments, and HTML documents. Unknown document errors remain uncovered and cause degraded status. Historical or covered oversized-document failures remain in the history but do not set status to degraded. Stale sources, current source errors, including unrecognized errors categorized as upstream_failure, and extraction or classification dead letters also set degraded status.

• POST /api/v1/data/snapshots creates a seven-day snapshot and needs civic:export.
• GET /api/v1/data/snapshots/{snapshotId}/{resource} reads one snapshot resource and needs civic:export.
• GET /api/v1/data/changes reads ordered changes and needs civic:read.
• POST /api/v1/data/batch reads up to 100 record IDs across bounded requests and needs civic:read.
• GET /api/v1/data/health reports feed health and needs civic:read.

curl --fail --silent --show-error \
  --header "Authorization: Bearer $AICD_API_KEY" \
  https://aicdapi.com/api/v1/data/health

Authenticated pagination and limits

• Authenticated civic data has a default page size of 100 and a service ceiling of 500. Your account can have a lower limit.
• Use the opaque nextCursor value exactly as returned. Do not edit or decode it to make business decisions.
• A cursor can expire after the replay window. A snapshot can also expire.
• If a response exceeds your account byte limit, request a smaller page.

Time, source evidence, and missing records

• Machine timestamps use ISO 8601. UTC timestamps end in Z. A source or meeting timezone is kept when known.
• A source link is evidence, not a guarantee that the publisher will keep the page unchanged.
• No result does not prove that no government action occurred. Check coverage, spelling, time range, and source publication delay. If the publisher is in the featured meeting-source list, also check its source status.
• Keep AICD API metadata and the government source URL when you store or publish a result.
• The public catalog's M, D, P, R, U, and N codes describe one named subtype only. They do not promise full-family coverage.

Response shape

Successful agent-facing HTTP responses use data and may include meta. Errors use error.code and error.message. Authenticated responses are not stored in shared caches.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid civic data request"
  }
}