API

cd-api is a FastAPI service that serves CivicDog's congressional data over HTTP — current members for cd-lookup, member voting records, and a semantic search API(GET /bills?filter[query]=…) that answers natural-language questions about legislation with a tiered exact-match / similarity-fallback retrieval strategy (seeSemantic Search). It's wrapped with Mangum and deployed as an AWS Lambda function behind API Gateway — there's no long-running server to patch or scale.

• Base URL: https://api.civicdog.com/v1
• Auth: x-api-key header, required on every route
• Format: JSON:API resources for members, bills, and votes
• Errors: JSON:API error documents ({ "errors": [...] }) on the JSON:API endpoints, application/problem+json per RFC 9457 on GET /version — never a bespoke { "error": "..." } shape

Schema

Generated directly from cd-api's OpenAPI spec, so it can't drift from what's actually deployed.

Deployment

• Lambda + RDS Proxy. Lambda's connection model (many short-lived invocations) doesn't play well with Postgres's per-connection overhead, so cd-api connects through RDS Proxy rather than directly to RDS.
• Tag-triggered deploys. A cd-api-v* tag triggers cd-api-deploy.yml, which builds a Lambda zip with uv, checks it against Lambda's 50MB limit, and calls aws lambda update-function-code.
• Keyless CI. The deploy workflow assumes an IAM role via GitHub OIDC — no static AWS credentials stored in GitHub. More on this in CI/CD & Automation.
• OpenAPI spec, exported on every deploy. The same workflow calls FastAPI's app.openapi() to generate openapi.json and pushes it to a public S3 bucket, which is what powers this page — no separate step to remember, no risk of the published schema falling behind a deploy. API Gateway requires an API key on every route (including a live /openapi.json), so publishing a static export to S3 is what makes an unauthenticated reference page possible at all.