# Dapper Political Intelligence API - Agent Guide

API REST de solo lectura para inteligencia politica y regulatoria en Latinoamerica.
Este documento esta optimizado para LLMs/agentes que necesitan entender el universo
de datos completo, como navegarlo y como evitar errores operativos.

## 1) Identidad del producto
- Producto: Dapper Political Intelligence API
- Base URL: https://api.dapperglobal.com
- Version API: v1
- Paradigma: domain-first (rutas por dominio: /v1/bills, /v1/regulations, ...)
    con filtro de pais por query param: ?country_code=BR,CO (multiple, separado
    por comas; opcional — si se omite, aplica el scope de paises de tu API key).
- Cobertura funcional: regulations, bills, actors, votes, consultations,
    schedules (agenda legislativa), news, reference catalogs y metadata de documentos.
- Protocolos de acceso: REST (principal) + MCP en /mcp
- Compatibilidad: las rutas legacy /v1/countries/{country_code}/... siguen
    respondiendo para clientes existentes, pero estan deprecadas y fuera del
    schema OpenAPI. Nuevas integraciones deben usar las rutas por dominio.

## 2) Descubrimiento rapido (orden recomendado)
1. https://api.dapperglobal.com/v1/health
2. https://api.dapperglobal.com/v1/countries
3. https://api.dapperglobal.com/openapi.json
4. https://api.dapperglobal.com/docs

Si tu caso de uso es sensible a actualidad, siempre consulta /v1/health antes de
consumir volumen grande de datos.

## 3) Autenticacion, permisos y alcance
- Header requerido en endpoints autenticados: X-API-Key
- Endpoints publicos (sin key):
    - https://api.dapperglobal.com/
    - https://api.dapperglobal.com/llms.txt
    - https://api.dapperglobal.com/v1/health
    - https://api.dapperglobal.com/v1/health/{country_code}
    - https://api.dapperglobal.com/v1/countries
- El API key esta scopeado por:
    - Paises permitidos
    - Dominios permitidos
- Errores frecuentes de permisos:
    - UNAUTHENTICATED
    - FORBIDDEN_COUNTRY
    - FORBIDDEN_DOMAIN
    - RATE_LIMITED

## 4) Modelo de paises
- Canonico: codigo ISO 3166-1 alpha-2 (ej: BR, CO, CL, MX)
- Filtro multi-pais: ?country_code=BR,CO,CL (separado por comas)
- Si se omite country_code, la respuesta cubre todos los paises permitidos
    por el scope de la API key.
- Compatibilidad legacy: los endpoints tambien aceptan country_id numerico
    (?country_id=8,2,6).
- Recomendacion: usar siempre country_code en nuevas integraciones.
- Fuente de verdad de cobertura por pais/domino: https://api.dapperglobal.com/v1/countries

## 5) Universo de datos por dominio

Los endpoints de detalle /{id} no requieren pais: el id es unico y el pais
del recurso se valida contra el scope de tu key (403 FORBIDDEN_COUNTRY si esta
fuera de tu alcance).

### 5.1 Regulations (normativa)
- Lista (multi-pais):
    - https://api.dapperglobal.com/v1/regulations?country_code=BR,CO,CL
- Detalle:
    - https://api.dapperglobal.com/v1/regulations/{id}
- Tipos de norma:
    - https://api.dapperglobal.com/v1/regulation-types
- Filtros tipicos: rtype_id, entity_id, since, until
- Uso recomendado:
    - discovery de entidad en /v1/entities
    - luego filtrar regulations por entity_id (nota: una entity pertenece a un
        pais, asi que entity_id restringe implicitamente el pais del resultado)

### 5.2 Bills (proyectos de ley)
- Lista (multi-pais):
    - https://api.dapperglobal.com/v1/bills?country_code=BR,CO
- Detalle:
    - https://api.dapperglobal.com/v1/bills/{id}
- Tramitacion/actualizaciones (de un bill puntual):
    - https://api.dapperglobal.com/v1/bills/{id}/updates
- Feed cross-bill (que se movio en el pais/ventana, sin bill_id):
    - https://api.dapperglobal.com/v1/bill-updates?country_code=BR,CO&since=...&until=...
- Votaciones del proyecto:
    - https://api.dapperglobal.com/v1/bills/{id}/votes
- Filtros tipicos: since, until, commission_id

### 5.3 Actors (actores politicos)
- Lista (multi-pais):
    - https://api.dapperglobal.com/v1/actors?country_code=BR,CO
- Detalle:
    - https://api.dapperglobal.com/v1/actors/{id}
- Historial de votos del actor:
    - https://api.dapperglobal.com/v1/actors/{id}/votes
- Proyectos presentados por el actor:
    - https://api.dapperglobal.com/v1/actors/{id}/bills
- Filtros tipicos: q (nombre), branch (executive|legislative), commission_id
    (miembros de una comision, ej. "quienes integran la Comision X")

### 5.4 Votes (votaciones)
- Lista top-level (multi-pais):
    - https://api.dapperglobal.com/v1/votes?country_code=BR,CO
- Tambien disponible como sub-recurso:
    - /v1/bills/{id}/votes
    - /v1/actors/{id}/votes
- Filtros tipicos (solo en el listado top-level): since, until — filtran por
    recorded_at (creacion del registro de voto, 100% poblado), no por
    vote_date (solo ~20% poblado)

### 5.5 Consultations (consultas publicas)
- Lista (multi-pais):
    - https://api.dapperglobal.com/v1/consultations?country_code=BR,CO
- Detalle:
    - https://api.dapperglobal.com/v1/consultations/{id}
- Filtros tipicos: since, until (fecha de publicacion); closing_before,
    closing_after, status=open|closed (vigencia sobre end_date)

### 5.6 Schedules (agendas legislativas)
- Lista (multi-pais):
    - https://api.dapperglobal.com/v1/schedules?country_code=BR,CO
- Detalle:
    - https://api.dapperglobal.com/v1/schedules/{id}
- Filtros tipicos: since, until

### 5.7 News (noticias)
- Lista (multi-pais):
    - https://api.dapperglobal.com/v1/news?country_code=BR,CO
- Detalle:
    - https://api.dapperglobal.com/v1/news/{id}
- Filtros tipicos: since, until

### 5.8 Reference catalogs (dimension tables para joins funcionales)
- Entidades emisoras:
    - https://api.dapperglobal.com/v1/entities?country_code=BR,CO
- Top entidades por actividad (conteo de regulations/consultations, ranking
    descendente — evita paginar y contar client-side):
    - https://api.dapperglobal.com/v1/entities/top?domain=regulations&since=...&until=...
    - Solo disponible para domain=regulations|consultations (son los unicos
        dominios con entity_id); no existe para bills/news/etc.
- Comisiones:
    - https://api.dapperglobal.com/v1/commissions?country_code=BR,CO
- Partidos:
    - https://api.dapperglobal.com/v1/parties?country_code=BR,CO
- Nota operativa:
    - /v1/entities es clave para mapear "nombre conocido" -> entity_id y luego
        filtrar regulations/consultations. Cada item incluye country_code.

### 5.9 Documents y semantic layer
- Metadata de documento:
    - https://api.dapperglobal.com/v1/documents/{id}
- Busqueda semantica (hybrid: semantic + lexical RRF + cross-encoder rerank):
    - https://api.dapperglobal.com/v1/search?q=...
- Estado actual (2026-08-07, `q` unificado):
    - /v1/search y el `q` de list_bills/list_regulations/list_consultations/
        list_news/list_transcripts intentan primero el motor hybrid (semantic +
        lexical RRF + cross-encoder rerank) y caen automaticamente a un match
        por substring de titulo/numero si ese servicio no esta configurado,
        esta caido, hace timeout, o no encuentra match semantico -- `meta.mode`
        en la respuesta indica cual de los dos respondio ("semantic" o
        "keyword_fallback"). Ya no devuelve 503 SEARCH_UNAVAILABLE por esto.
    - /v1/documents/{id} si esta operativo con autenticacion y scope.

### 5.10 Links a la plataforma (dapper_url)
- Cada registro trae `dapper_url`: la pagina de ESE registro dentro de la
    plataforma Dapper (dapperglobal.com), ya construida. Es el link que se le
    entrega a una persona para ver el detalle completo (fases y documentos de un
    proyecto, texto de una norma, historial de un legislador).
- Usar el valor tal cual viene. No armar URLs a mano ni editar el path de otra
    fila: las rutas no son deducibles del payload (el perfil de un actor, por
    ejemplo, esta indexado por un id distinto al del campo `id`).
- `dapper_url: null` significa que ese registro no tiene pagina, no que falte el
    dato. Casos esperados: consultations en PE y AR (pagina deshabilitada),
    actores sin mandato activo (ministros, fichas de candidatos), y los catalogos
    que son filtros y no paginas (regulation-types, interest tags).
- Algunas filas apuntan a la pagina mas cercana que si existe, porque la
    plataforma no tiene una propia para ese tipo de registro: un voto y un
    discurso apuntan al proyecto de ley del que tratan, una tramitacion a su
    proyecto, un partido a su bancada en el listado de actores, una entidad a su
    porcion del feed de normativa.
- Distinto de `external_link` / `congress_records[].link`, que son la fuente
    primaria oficial (gaceta, expediente de la camara). `dapper_url` es el link
    al producto; los otros son la cita documental.

## 6) Paginacion y navegacion de grandes volumenes
- Estrategia: cursor-based pagination (sin offset, sin total global)
- Patron:
    1. pedir pagina con limit
    2. leer meta.next_cursor
    3. reenviar como cursor en la siguiente llamada
- No asumas estabilidad por offset. Usa siempre el cursor devuelto.

## 7) Freshness y calidad de dato
- Endpoint de salud/frescura global:
    - https://api.dapperglobal.com/v1/health
- Endpoint por pais:
    - https://api.dapperglobal.com/v1/health/{country_code}
- Dominios evaluados en health:
    - regulations, consultations, bills, actors, schedules, news, transcripts
- Dominios con datos pero sin reportar freshness todavia (ingesta en curso):
    - votes, interventions
- Estados por dominio:
    - ok, warning, stale, no_data, not_covered (Dapper no tiene fuente para ese dominio en ese pais)
- Recomendacion para agentes:
    - antes de responder preguntas sensibles al tiempo, validar freshness y citar
        generated_at + estado del dominio/pais.

## 8) Rate limits, headers y resiliencia
- Limites por key: por minuto + por dia
- Observar headers X-RateLimit-* en cada respuesta
- Ante RATE_LIMITED:
    - bajar concurrencia
    - reducir limit por pagina
    - aplicar backoff exponencial

## 9) Contrato de errores (machine-readable)
El error payload incluye un code util para decisiones automaticas.
Codigos comunes:
- UNAUTHENTICATED
- FORBIDDEN_COUNTRY
- FORBIDDEN_DOMAIN
- RATE_LIMITED
- NOT_FOUND
- INVALID_PARAM
- SEARCH_UNAVAILABLE

## 10) Estrategias de consulta recomendadas para LLMs
- Preguntas exploratorias por pais:
    - countries -> seleccionar pais y dominios disponibles ->
        /v1/{dominio}?country_code=XX.
- Preguntas por entidad (ej. ministerio/agencia):
    - /v1/entities -> resolver entity_id -> /v1/regulations?entity_id=...
- Preguntas transversales regionales:
    - cualquier dominio con country_code multiple:
        /v1/bills?country_code=BR,CO,CL.
- Preguntas de trazabilidad legislativa:
    - /v1/bills -> /v1/bills/{id} -> /v1/bills/{id}/updates +
        /v1/bills/{id}/votes.
- Preguntas de comportamiento politico individual:
    - /v1/actors/{id} + /v1/actors/{id}/votes + /v1/actors/{id}/bills.

## 11) MCP y uso por agentes
- Endpoint MCP: https://api.dapperglobal.com/mcp
- El servidor MCP reutiliza auth/scopes de la API REST para las tools que
    siguen siendo espejo 1:1 de una ruta (catalogos, health, usage, list_actor_tweets).
- Desde el 2026-08-10, las tools de contenido por dominio estan consolidadas
    (get+list+sub-recurso fusionados en un solo tool, sin id requerido de
    antemano): list_bills, list_bill_updates, list_regulations, list_actors,
    list_votes, list_interventions, list_news, list_consultations,
    list_schedules, list_transcripts, search. Cada una sin `id` lista/filtra;
    con `id` devuelve el detalle completo (list_bills/list_actors devuelven
    ademas un overview agregado: bill+tramitaciones+votos+intervenciones, o
    actor+votos+bills recientes). list_votes/list_interventions aceptan
    bill_id/actor_id como filtros libres en vez de tools separadas por
    sub-recurso; list_bills acepta actor_id igual. list_bill_updates sin
    bill_id es el feed cross-bill (que se movio en el pais/ventana de tiempo
    dada). search acepta document_id para el detalle de un documento
    encontrado por busqueda. Catalogos sin cambios: list_entities,
    list_commissions, list_parties, list_regulation_types, list_interest_tags,
    list_top_entities (conteo agregado por entidad en regulations/
    consultations, no un listado paginado).
- Los params country_code / country_id de las tools funcionan igual que en REST
    (multi-pais separado por comas, opcional).
- /admin no esta expuesto por MCP.
- Acciones sobre la cuenta del usuario logueado (solo con sesion OAuth o una
    llave con client_email, y solo si el servidor las lista): follow_bill,
    unfollow_bill, update_my_interests (agrega/quita; replace=true es
    explicito), update_my_preferences, create_listening (gasta cuota paga:
    get_listening_quota primero y confirm=true). En REST: PUT/DELETE
    /v1/bills/{bill_id}/follow, PATCH /v1/me/interests, PATCH
    /v1/me/preferences, POST /v1/listenings.
- Listado vivo y completo (nombre, params, descripcion) en https://api.dapperglobal.com/mcp-tools.json.
- Si el cliente MCP soporta OAuth, usar login browser; para scripts/CI, X-API-Key.

## 12) Operacion y confiabilidad
- Los datos de dominio son de solo lectura; las unicas escrituras son sobre
    la cuenta del propio usuario (seguimientos, intereses, preferencias,
    pedidos de escucha), y se ejecutan en la plataforma Dapper.
- Cache en Redis para listas y catalogos, con TTL por dominio.
- / (root) realiza chequeo liviano de DB/Redis para liveness tecnica.

## 13) Recursos canonicos
- OpenAPI JSON: https://api.dapperglobal.com/openapi.json
- Swagger UI: https://api.dapperglobal.com/docs
- Redoc: https://api.dapperglobal.com/redoc
- LLM index: https://api.dapperglobal.com/llms.txt
- Health/freshness: https://api.dapperglobal.com/v1/health
- Countries coverage map: https://api.dapperglobal.com/v1/countries

## 14) Notas de implementacion para integradores
- Mantener almacenamiento local de cursores y checkpoints por endpoint/pais.
- No mezclar country_id legacy con country_code en un mismo flujo nuevo.
- Versionar prompts/herramientas con awareness de SEARCH_UNAVAILABLE para evitar
    fallback loops en /v1/search.
- Validar permisos por dominio antes de planificar pipelines (ej. votes vs bills).