# API and data guide

Canonical: https://aicdapi.com/help/api-and-data
Content version: 2026-09-15.1
Reviewed: 2026-09-15
Reviewed against source commit: a6e88209e0c64247031416f27f11b050e0333088
Owner: AICD API

Use public coverage, authenticated snapshots, changes, and source links without overstating the data.

## 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.

### Links

- [Coverage](/api/v1/public/coverage)
- [Source status](/api/v1/public/source-status)

## 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.

### Read feed health

```bash
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 shape

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