# Dapper Political Intelligence API

> Read-only REST API for structured political & regulatory data across Latin
> American countries: regulations, bills (+updates, +votes), actors (+votes),
> consultations, legislative agendas (schedules), news, votes, and semantic
> document search. Country-first: most paths are /v1/countries/{country_code}/...

## Auth
All data endpoints require an API key in the `X-API-Key` header. Keys are
scoped by country and domain. Public endpoints (no key): /v1/health, /v1/countries.

## Conventions
- Countries are addressed by ISO 3166-1 alpha-2 code (e.g. BR, CO, MX), not
  numeric ids. Call /v1/countries for the full list of codes + available domains.
- Cursor pagination: pass `cursor` from `meta.next_cursor`. No offsets, no totals.
- Rate limits: per-minute + per-day; see X-RateLimit-* response headers.
- Errors carry a machine-readable `code` (UNAUTHENTICATED, FORBIDDEN_COUNTRY,
  FORBIDDEN_DOMAIN, RATE_LIMITED, NOT_FOUND, INVALID_PARAM, SEARCH_UNAVAILABLE).
- Freshness: list responses include a `freshness` block; /v1/health is the
  public status page (call it before time-sensitive questions).

## Start here
- OpenAPI spec: http://dapper-api-403696803454.us-east1.run.app/openapi.json
- Interactive docs: http://dapper-api-403696803454.us-east1.run.app/docs
- Data freshness: http://dapper-api-403696803454.us-east1.run.app/v1/health
- Countries & available domains: http://dapper-api-403696803454.us-east1.run.app/v1/countries

## Key endpoints
- http://dapper-api-403696803454.us-east1.run.app/v1/countries/{country_code}/regulations
- http://dapper-api-403696803454.us-east1.run.app/v1/countries/{country_code}/bills (+/{id}/updates, +/{id}/votes)
- http://dapper-api-403696803454.us-east1.run.app/v1/countries/{country_code}/actors (+/{id}/votes)
- http://dapper-api-403696803454.us-east1.run.app/v1/countries/{country_code}/consultations
- http://dapper-api-403696803454.us-east1.run.app/v1/countries/{country_code}/schedules
- http://dapper-api-403696803454.us-east1.run.app/v1/countries/{country_code}/news
- http://dapper-api-403696803454.us-east1.run.app/v1/regulations?country_code=BR,CO,CL  (cross-country)
- http://dapper-api-403696803454.us-east1.run.app/v1/search?q=...  (semantic document search)