Civic Translator API

Explore Civic Translator's public discovery endpoints or request an API key for full, structured meeting and packet summary access.

Quick Start

1. Explore the public endpoints without an API key.
2. Review the OpenAPI specification or test requests in the interactive explorer.
3. Contact Civic Translator for an API key when you need full summaries or protected data access.

curl "https://civic-translator.org/api/v1"

curl "https://civic-translator.org/api/v1/cities?state=iowa"

curl "https://civic-translator.org/api/v1/public-bodies?state=iowa&city=grimes"

curl "https://civic-translator.org/api/v1/summaries-preview?state=iowa&limit=5"

export CIVIC_API_KEY="YOUR_API_KEY"

curl   -H "x-api-key: $CIVIC_API_KEY"   "https://civic-translator.org/api/v1/summaries/search?q=air%20quality%20ventilation&state=iowa&summaryType=packet-summary"

curl "https://65xguylj8b.execute-api.us-east-1.amazonaws.com/infographics/recent?state=iowa&governmentBody=school-boards&limit=6"

Public vs. Protected Endpoints

Base URL

https://civic-translator.org/api/v1

Authentication

Protected endpoints require an API key in the x-api-key request header.

export CIVIC_API_KEY="YOUR_API_KEY"

curl \
  -H "x-api-key: $CIVIC_API_KEY" \
  "https://civic-translator.org/api/v1/summaries/search?q=teacher%20contract&state=iowa&limit=10"

Never place API keys in URLs, browser JavaScript, public repositories, screenshots, or client-side bundles.

Contact Civic Translator to request an API key. Include your organization, intended use, expected request volume, and the data you need.

Endpoints

API InformationPublic

GET /api/v1

HealthPublic

GET /api/v1/health

CitiesPublic

GET /api/v1/cities
GET /api/v1/cities?state=iowa
GET /api/v1/cities?state=iowa&q=grimes

Returns distinct cities represented by covered jurisdictions. Each item includes the city, state, latitude, and longitude needed for nearby searches.

Supported filters: state and q.

Public BodiesPublic

GET /api/v1/public-bodies
GET /api/v1/public-bodies?state=iowa
GET /api/v1/public-bodies?state=iowa&governmentBody=school-boards
GET /api/v1/public-bodies?q=algona
GET /api/v1/public-bodies?state=iowa&city=grimes

Supported filters: state, governmentBody, city, and q. The city filter matches both primary and served cities configured for each public body.

Summary PreviewsPublic

GET /api/v1/summaries-preview
GET /api/v1/summaries-preview?state=iowa&limit=10
GET /api/v1/summaries-preview?q=construction
GET /api/v1/summaries-preview?topic=facilities-construction
GET /api/v1/summaries-preview?summaryType=packet-summary
GET /api/v1/summaries-preview?state=iowa&publicBody=adel&limit=10

This public endpoint returns limited descriptions, inferred topics, image URLs, and public page URLs. It does not return full Markdown summaries or internal storage keys.

Supported filters: state, governmentBody, publicBody, summaryType, topic, q, and limit. The public maximum is 25.

Recent InfographicsPublic

GET /infographics/recent
GET /infographics/recent?state=iowa&limit=6
GET /infographics/recent?state=nebraska&governmentBody=school-boards&limit=6
GET /infographics/recent?state=colorado&governmentBody=school-boards&publicBody=denver-public-schools&limit=10
GET /infographics/recent?state=colorado&governmentBody=school-boards&publicBody=denver-public-schools&excludeSlug=colorado-school-boards-denver-public-schools-2026-06-22-diligent-community-1437-packet-summary&limit=6

Returns recent published infographic records ordered newest first. This endpoint powers related-content sections such as recent summaries across a state, more summaries from the same public body, and previous/next internal navigation.

Supported filters: state, governmentBody, publicBody, excludeSlug, and limit. The default limit is 12 and the maximum is 50.

The response includes fields such as id, state, governmentBody, publicBody, slug, displayTitle, meetingDate, meetingId, summaryType, s3Key, and timestamps.

Search Full Summary TextAPI Key Required

GET /api/v1/summaries/search?q=air%20quality%20ventilation
GET /api/v1/summaries/search?q="teacher%20contract"&state=iowa
GET /api/v1/summaries/search?q=HVAC%20OR%20geothermal&summaryType=packet-summary
GET /api/v1/summaries/search?q=budget%20-athletics&governmentBody=school-boards&limit=20

Searches the complete stored text of packet and meeting summaries in Aurora PostgreSQL. Results are ranked using PostgreSQL full-text search and include highlighted excerpts rather than the entire document body. Use the detailed-summary endpoint to retrieve the full selected summary.

The required q parameter accepts familiar web-search syntax through PostgreSQL websearch_to_tsquery, including quoted phrases, OR, and excluded terms prefixed with a minus sign.

Supported filters: state, governmentBody, publicBody, meetingId, summaryType, and limit.

curl   -H "x-api-key: $CIVIC_API_KEY"   "https://civic-translator.org/api/v1/summaries/search?q=air%20quality%20ventilation&state=iowa&summaryType=packet-summary&limit=10"

List SummariesAPI Key Required

GET /api/v1/summaries
GET /api/v1/summaries?state=iowa
GET /api/v1/summaries?state=iowa&governmentBody=school-boards
GET /api/v1/summaries?publicBody=adel
GET /api/v1/summaries?summaryType=packet-summary&limit=25

Detailed SummaryAPI Key Required

GET /api/v1/summaries/{state}/{governmentBody}/{publicBody}/{meetingDate}/{summaryType}

curl \
  -H "x-api-key: $CIVIC_API_KEY" \
  "https://civic-translator.org/api/v1/summaries/iowa/school-boards/adel/2026-07-13/packet-summary"

Example Full-Text Search Response

{
  "data": [
    {
      "id": "summary_123",
      "state": "iowa",
      "governmentBody": "school-boards",
      "publicBody": "west-fork-community-school-district",
      "meetingDate": "2026-07-20",
      "meetingId": "apptegy-20260720-0a38d1d36e742660",
      "summaryType": "packet-summary",
      "title": "Regular Board Meeting — Packet Summary",
      "excerpt": "...the board reviewed <mark>air quality</mark> and <mark>ventilation</mark> improvements...",
      "rank": 0.71
    }
  ],
  "meta": {
    "query": "air quality ventilation",
    "limit": 10,
    "count": 1
  }
}

Search responses return ranked metadata and excerpts. Full summary text remains available from the protected detail endpoint.

Example Preview Response

{
  "data": [
    {
      "state": "iowa",
      "governmentBody": "school-boards",
      "publicBody": "clearcreekamana",
      "displayName": "Clear Creek Amana Community School District",
      "meetingDate": "2026-07-15",
      "summaryType": "packet-summary",
      "title": "Clear Creek Amana Community School District — School Board Meeting — Packet Summary — July 15, 2026",
      "description": "The July 15, 2026 board meeting combines routine annual governance work with several significant spending decisions...",
      "topics": [
        {
          "slug": "facilities-construction",
          "label": "Facilities & Construction"
        }
      ],
      "imageUrl": "https://civic-translator.org/api/infographics/image?key=...",
      "pageUrl": "https://civic-translator.org/iowa/school-boards/clearcreekamana/..."
    }
  ],
  "meta": {
    "count": 1,
    "maxLimit": 25,
    "access": "public-preview",
    "fullTextRequiresApiKey": true
  }
}

Errors

Missing API Key

{
  "error": {
    "code": "api_key_required",
    "message": "An x-api-key header is required."
  }
}

Summary Not Found

{
  "error": {
    "code": "summary_not_found",
    "message": "The requested summary was not found."
  }
}

Common status codes include 200, 400, 401, 404, 429, and 500.

Using Civic Translator with AI Applications

Public discovery endpoints may be used by search tools, assistants, and research systems to identify covered public bodies and available meeting summaries. Full summary integrations, retrieval-augmented generation systems, and higher-volume applications should request an API key.

Developers should retain attribution to Civic Translator and the originating public body. Official public-body records remain the authoritative source.

What You Can Build

See practical examples for newsroom research, policy tracking, public spending alerts, academic research, civic chatbots, monitoring dashboards, and statewide meeting comparisons.

Developer Resources