AICD API

List recent agenda hits (listRecentAgendaHits)

• Public
• Available

No credentials. This endpoint is public.

Parameters

Responses

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Declared error codes

Notes

• A backend query failure is reported as an empty list with HTTP 200, not as an error.
• Both a canonical and a short alias are accepted for each filter; the canonical name wins when both are sent.

Limits and pagination

Rate limit

120 requests per 60 seconds per client IP, counted separately for each public endpoint and keyed on the first X-Forwarded-For entry. The allowance is not shared between public endpoints: exhausting one leaves the others available. If the limiter's own store fails, the request is allowed through rather than refused.

Pagination

None. The result set is capped at three hits.

Retry-After

Sent on 429 only, as whole seconds.

Caching

public, s-maxage=60, stale-while-revalidate=300 on success. Error responses carry no cache directive.

Example request

curl -X GET 'https://aicdapi.com/api/v1/public/agenda-hits'

Read this endpoint as Markdown for an agent.

Get an agenda hit (getAgendaHit)

• Public
• Available

No credentials. This endpoint is public.

Parameters

Responses

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Declared error codes

Notes

• A backend query failure is reported as 404, not 500. Do not read 404 as proof that the record never existed.

Limits and pagination

Rate limit

120 requests per 60 seconds per client IP, counted separately for each public endpoint and keyed on the first X-Forwarded-For entry. The allowance is not shared between public endpoints: exhausting one leaves the others available. If the limiter's own store fails, the request is allowed through rather than refused.

Retry-After

Sent on 429 only, as whole seconds.

Caching

public, s-maxage=60, stale-while-revalidate=300 on success. Error responses carry no cache directive.

Example request

curl -X GET 'https://aicdapi.com/api/v1/public/agenda-hits/{matchId}'

Read this endpoint as Markdown for an agent.

List upcoming agenda hits (listUpcomingAgendaHits)

• Public
• Available

No credentials. This endpoint is public.

Parameters

Responses

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Declared error codes

Notes

• A backend query failure is reported as an empty page with HTTP 200, not as an error.
• Unlike the other public endpoints, this one validates its input before applying this endpoint's IP limit.

Limits and pagination

Rate limit

120 requests per 60 seconds per client IP, counted separately for each public endpoint and keyed on the first X-Forwarded-For entry. The allowance is not shared between public endpoints: exhausting one leaves the others available. If the limiter's own store fails, the request is allowed through rather than refused.

Pagination

Cursor pagination by default, using the meeting time, classification time, and hit id as a keyset seek. A deprecated page parameter switches to offset pagination and is limited to page 100 with a fixed page size of 10. The cursor is not bound to the topic filter.

Retry-After

Sent on 429 only, as whole seconds.

Caching

public, s-maxage=60, stale-while-revalidate=300 on success. Error responses carry no cache directive.

Example request

curl -X GET 'https://aicdapi.com/api/v1/public/upcoming-agenda-hits?topicSlug=zoning'

Read this endpoint as Markdown for an agent.

Get a public body's meeting cadence (getPublicBodyCadence)

• Public
• Available

No credentials. This endpoint is public.

Parameters

Responses

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Declared error codes

Notes

• A backend query failure is reported as null dates with HTTP 200, not as an error.
• Dates are null when unknown; a null date is not a claim that no meeting exists.

Limits and pagination

Rate limit

120 requests per 60 seconds per client IP, counted separately for each public endpoint and keyed on the first X-Forwarded-For entry. The allowance is not shared between public endpoints: exhausting one leaves the others available. If the limiter's own store fails, the request is allowed through rather than refused.

Pagination

None.

Retry-After

Sent on 429 only, as whole seconds.

Caching

public, s-maxage=60, stale-while-revalidate=300 on success. Error responses carry no cache directive.

Example request

curl -X GET 'https://aicdapi.com/api/v1/public/jurisdictions/dallas/bodies/city-council/cadence'

Read this endpoint as Markdown for an agent.

List public source statuses (listPublicSourceStatuses)

• Public
• Available

No credentials. This endpoint is public.

Parameters

Responses

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Declared error codes

Notes

• A backend query failure is reported as status unknown with HTTP 200, not as an error.
• The evidence window is 90 days; a source that has not been checked inside that window reports as unknown.

Limits and pagination

Rate limit

120 requests per 60 seconds per client IP, counted separately for each public endpoint and keyed on the first X-Forwarded-For entry. The allowance is not shared between public endpoints: exhausting one leaves the others available. If the limiter's own store fails, the request is allowed through rather than refused.

Pagination

None. The covered set is fixed.

Retry-After

Sent on 429 only, as whole seconds.

Caching

public, s-maxage=60, stale-while-revalidate=300 on success. Error responses carry no cache directive.

Example request

curl -X GET 'https://aicdapi.com/api/v1/public/source-status'

Read this endpoint as Markdown for an agent.

List DFW civic-data research coverage (listDfwResearchCoverage)

• Public
• Available

No credentials. This endpoint is public.

Parameters

Responses

{
  "data": [
    {
      "kind": "city",
      "researchId": "city:4801240",
      "jurisdictionSlug": "addison",
      "name": "Addison",
      "active": true,
      "municipalityType": "town",
      "censusPlaceGeoid": "4801240",
      "counties": [
        "Dallas"
      ],
      "regionCounties": [
        "Dallas"
      ],
      "primaryRegionCounty": "Dallas",
      "censusStatus": {
        "functionalStatus": "A",
        "placeClass": "C1",
        "vintage": "2026-01-01"
      },
      "sourceUrls": {
        "official": "https://addisontexas.net/",
        "openData": "https://the-town-of-addison-gis-directory-addisontx.hub.arcgis.com/",
        "websiteDiscovery": null,
        "roster": "https://geospatial.nctcog.org/map/rest/services/Boundaries/Boundaries/MapServer/6",
        "censusStatus": "https://tigerweb.geo.census.gov/tigerwebmain/Files/acs26/tigerweb_acs26_incplace_tx.html",
        "countyMembership": "https://geospatial.nctcog.org/map/rest/services/RDC/POP_ESTIMATES_REAL_RATES_BY_CITY/MapServer/1"
      },
      "rosterLimits": {
        "boundaryYear": "2024",
        "boundarySource": "City",
        "directoryListed": true,
        "websiteVerification": "NCTCOG index link; live site ownership not confirmed.",
        "verificationNotes": []
      },
      "families": [
        {
          "familyId": "city.permits",
          "status": "P",
          "evidenceScope": "source_discovery_only",
          "checkedDate": "2026-09-09",
          "sourceUrl": "https://developmentservices.addisontx.gov/Data-Reports",
          "method": "Official source or report index identified",
          "evidence": "Official reports index names monthly commercial building permits.",
          "constraints": "Bulk access, refresh cadence and reuse terms still need a connector proof.",
          "alternatives": []
        }
      ]
    }
  ],
  "meta": {
    "catalogVersion": "2026-09-09.f006aca03096",
    "researchDate": "2026-09-09",
    "ingestionVerified": false,
    "statusDefinitions": {
      "M": "A public machine-readable query, sample, or count succeeded.",
      "D": "A public record or document was opened and read.",
      "P": "An official source or portal was found, but record extraction was not proved.",
      "R": "Access, terms, account, payment, or reuse restrictions need resolution.",
      "U": "No source was proved in this research pass; this does not mean the data is unavailable.",
      "N": "The family or named subtype is explicitly not applicable for this jurisdiction."
    },
    "scope": {
      "name": "NCTCOG 16-county region",
      "counties": [
        "Collin",
        "Dallas",
        "Denton",
        "Ellis",
        "Erath",
        "Hood",
        "Hunt",
        "Johnson",
        "Kaufman",
        "Navarro",
        "Palo Pinto",
        "Parker",
        "Rockwall",
        "Somervell",
        "Tarrant",
        "Wise"
      ],
      "rosterCheckedDate": "2026-09-08",
      "censusStatusVintage": "2026-01-01",
      "method": "Dated NCTCOG and Census roster cross-check.",
      "caveat": "This is a dated research baseline, not a live ingestion claim."
    },
    "pagination": {
      "limit": 20,
      "returned": 1,
      "nextCursor": null
    }
  }
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  }
}

Declared error codes

Notes

• Unknown query keys and repeated query keys are rejected rather than ignored.

Limits and pagination

Rate limit

120 requests per 60 seconds per client IP, counted separately for each public endpoint and keyed on the first X-Forwarded-For entry. The allowance is not shared between public endpoints: exhausting one leaves the others available. If the limiter's own store fails, the request is allowed through rather than refused.

Pagination

Offset cursor pagination, 1 to 20 items per page with a default of 20. The cursor is invalidated by any filter change and by a new catalog version.

Retry-After

Sent on 429 only, as whole seconds.

Caching

public, s-maxage=60, stale-while-revalidate=300 on success. Error responses carry no cache directive.

Example request

curl -X GET 'https://aicdapi.com/api/v1/public/coverage'

Read this endpoint as Markdown for an agent.

Read the current state of up to 100 records (readCivicRecords)

• API key
• Limited availability
• scope civic:read

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Request body (required)

{
  "requests": [
    {
      "resource": "agenda_items",
      "ids": [
        "5c2f0d18-0b1a-4a3f-9f1e-2b7c9a4d6e01"
      ]
    }
  ]
}

Responses

Declared error codes

Notes

• Requires a customer API key: Authorization: Bearer aicd_.... A Clerk browser session is not accepted on this path.

Limits and pagination

Rate limit

Counted against the per-account minute and burst allowances. A paid subscription uses its plan's own limits, which the public usage limits help lists and the account console shows. An account with no paid plan is limited by the stored account defaults, which the account console also shows. A separate account-wide abuse limit also applies to recognized subscription keys, counted separately for usable keys and for revoked or expired ones, so a compromised key you rotate does not reduce the new key's capacity. It is charged before a denial is decided and is not charged against your paid quota.

Retry-After

Sent on 429 only, as whole seconds.

Caching

no-store. Account-scoped responses are never cached by a shared cache.

Example request

curl -X POST 'https://aicdapi.com/api/v1/data/batch' \
  -H "Authorization: Bearer $AICD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"requests":[{"resource":"agenda_items","ids":["5c2f0d18-0b1a-4a3f-9f1e-2b7c9a4d6e01"]}]}'

Read this endpoint as Markdown for an agent.

Read durable committed changes (readCivicChanges)

• API key
• Limited availability
• scope civic:read

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Parameters

Responses

Declared error codes

Notes

• Requires a customer API key: Authorization: Bearer aicd_.... A Clerk browser session is not accepted on this path.

Limits and pagination

Rate limit

Counted against the per-account minute and burst allowances. A paid subscription uses its plan's own limits, which the public usage limits help lists and the account console shows. An account with no paid plan is limited by the stored account defaults, which the account console also shows. A separate account-wide abuse limit also applies to recognized subscription keys, counted separately for usable keys and for revoked or expired ones, so a compromised key you rotate does not reduce the new key's capacity. It is charged before a denial is decided and is not charged against your paid quota.

Pagination

Opaque cursor pagination. Send the previous response's meta.nextCursor back as cursor. A cursor minted with a resource filter stays bound to it.

Retry-After

Sent on 429 only, as whole seconds.

Caching

no-store. Account-scoped responses are never cached by a shared cache.

Example request

curl -X GET 'https://aicdapi.com/api/v1/data/changes' \
  -H "Authorization: Bearer $AICD_API_KEY"

Read this endpoint as Markdown for an agent.

Read current source and pipeline health (readCivicHealth)

• API key
• Limited availability
• scope civic:read

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Responses

Declared error codes

Notes

• Requires a customer API key: Authorization: Bearer aicd_.... A Clerk browser session is not accepted on this path.
• A missing health result is reported as status: "unavailable" with HTTP 200, not as an error.

Limits and pagination

Rate limit

Counted against the per-account minute and burst allowances. A paid subscription uses its plan's own limits, which the public usage limits help lists and the account console shows. An account with no paid plan is limited by the stored account defaults, which the account console also shows. A separate account-wide abuse limit also applies to recognized subscription keys, counted separately for usable keys and for revoked or expired ones, so a compromised key you rotate does not reduce the new key's capacity. It is charged before a denial is decided and is not charged against your paid quota.

Retry-After

Sent on 429 only, as whole seconds.

Caching

no-store. Account-scoped responses are never cached by a shared cache.

Example request

curl -X GET 'https://aicdapi.com/api/v1/data/health' \
  -H "Authorization: Bearer $AICD_API_KEY"

Read this endpoint as Markdown for an agent.

Create a seven-day frozen civic export (createCivicSnapshot)

• API key
• Limited availability
• scope civic:export

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Responses

Declared error codes

Notes

• Requires a customer API key: Authorization: Bearer aicd_.... A Clerk browser session is not accepted on this path.
• The response carries no body on the request side; any request body is ignored.

Limits and pagination

Rate limit

Counted against the minute, burst, and hourly export allowances on your account. Snapshot creation consumes the export allowance; reading a snapshot back does not.

Retry-After

Sent on 429 only, as whole seconds. The export allowance resets at the end of the current hour.

Caching

no-store. Account-scoped responses are never cached by a shared cache.

Example request

curl -X POST 'https://aicdapi.com/api/v1/data/snapshots' \
  -H "Authorization: Bearer $AICD_API_KEY"

Read this endpoint as Markdown for an agent.

Read one resource from a frozen export (readCivicSnapshotPage)

• API key
• Limited availability
• scope civic:export

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Parameters

Responses

Declared error codes

Notes

• Requires a customer API key: Authorization: Bearer aicd_.... A Clerk browser session is not accepted on this path.

Limits and pagination

Rate limit

Counted against the minute and burst allowances on your account. The hourly export allowance is not consumed by this read.

Pagination

Opaque cursor pagination, bound to the snapshot id and the resource in the path.

Retry-After

Sent on 429 only, as whole seconds.

Caching

no-store. Account-scoped responses are never cached by a shared cache.

Example request

curl -X GET 'https://aicdapi.com/api/v1/data/snapshots/{snapshotId}/{resource}' \
  -H "Authorization: Bearer $AICD_API_KEY"

Read this endpoint as Markdown for an agent.

List the live polling subscriptions for this key (listFeedSubscriptions)

• API key
• Limited availability
• scope civic:read

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Responses

{
  "data": {
    "items": [
      {
        "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
        "name": "county-meetings",
        "resource": "meetings",
        "keyId": "9c858901-8a57-4791-81fe-4c455b099bc9",
        "startCursor": "v1.eyJzZXF1ZW5jZSI6MTI4fQ",
        "createdAt": "2026-09-28T12:00:00Z"
      }
    ],
    "activeCount": 3,
    "maxActiveSubscriptions": 10
  }
}

Declared error codes

Notes

• Requires a customer API key: Authorization: Bearer aicd_.... A Clerk browser session is not accepted on this path.
• A subscription created with one key is not listed for another key of the same account: the listed items are scoped to the credential that made the request, while the counts are account-wide.
• Feed subscription caps are per account and count live subscriptions across every key, not budgets: Pro 10 and Ultra 100. They are separate from the per-plan key caps, and the plan's other limits are unchanged. A Pro/Ultra downgrade that leaves the account above its new cap keeps every existing feed and its existing polls working on either eligible tier, while new creation is refused until the account is below the limit. Losing the paid period is refused by the shared paid admission (billing_entitlement_required) and dropping to Builder by the feed tier gate (feed_subscription_plan_required); either way all four of these operations — create, list, poll, and revoke — refuse while every row is retained: nothing is deleted, rebound, or silently released on your behalf.
• A key rotation or revocation never rewrites or deletes a feed, and the binding is exact: a replacement key is not accepted for an existing feed's polls. The replacement key registers its own feed, and may carry a retained cursor position from the old feed onto it while that position is still inside the replay window; once the window has passed, the position is gone and the new feed reconciles from a fresh snapshot like every other feed. Expiry or revocation of a bound key stops that key's polls and frees the account's cap slot without deleting the row; the account's live feed count follows active feeds only.

Limits and pagination

Rate limit

Counted against the per-account minute, burst, and response-byte allowances shared by every key of the account. A subscription carries no budget of its own: subscribing does not add, reserve, or partition paid usage, and the account's admitted-request and byte allowances are what a poll consumes. The account-wide abuse ceiling applies here as it does to the rest of the machine API: it is account-wide, is not charged against the paid quota, and is charged before a revoked, expired, unpaid, or scope-denied rejection is decided.

Retry-After

Sent on 429 only, as whole seconds.

Caching

no-store. Account-scoped responses are never cached by a shared cache.

Example request

curl -X GET 'https://aicdapi.com/api/v1/data/subscriptions' \
  -H "Authorization: Bearer $AICD_API_KEY"

Read this endpoint as Markdown for an agent.

Create a polling subscription over the change feed (createFeedSubscription)

• API key
• Limited availability
• scope civic:read

Customer API key: Authorization: Bearer aicd_.... A browser session does not authenticate this endpoint.

Request body (required)

FeedSubscriptionInput

{
  "name": "county-meetings",
  "resource": "meetings"
}

Responses

{
  "data": {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "name": "county-meetings",
    "resource": "meetings",
    "keyId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "startCursor": "v1.eyJzZXF1ZW5jZSI6MTI4fQ",
    "createdAt": "2026-09-28T12:00:00Z"
  }
}

{
  "data": {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "name": "county-meetings",
    "resource": "meetings",
    "keyId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "startCursor": "v1.eyJzZXF1ZW5jZSI6MTI4fQ",
    "createdAt": "2026-09-28T12:00:00Z"
  }
}