{
    "openapi": "3.1.0",
    "info": {
        "title": "Polímetro — API de datos públicos de Colombia",
        "version": "1.0.0",
        "summary": "Datos públicos de Colombia estructurados, conectados por su geografía y verificables.",
        "description": "API pública de solo lectura. Devuelve JSON paginado con `data`, `links` y `meta`. Todas las llamadas requieren `X-Api-Key` (regístrate para obtener una; el plan gratis la incluye). Todo se conecta por los códigos oficiales de DIVIPOLA (departamento y municipio).",
        "contact": {
            "name": "Polímetro",
            "url": "https://polimetro.org/developers"
        },
        "license": {
            "name": "Datos públicos",
            "url": "https://polimetro.org/developers"
        }
    },
    "servers": [
        {
            "url": "https://polimetro.org/api/v1",
            "description": "API v1"
        }
    ],
    "externalDocs": {
        "description": "Documentación",
        "url": "https://polimetro.org/developers"
    },
    "tags": [
        {
            "name": "Personas",
            "description": "Políticos y cargos"
        },
        {
            "name": "Candidatos",
            "description": "Candidatos electorales aún no vinculados a un político"
        },
        {
            "name": "Educación",
            "description": "Instituciones de educación superior (SNIES) y colegios (DANE/SISE)"
        },
        {
            "name": "Congreso",
            "description": "Proyectos de ley y votaciones"
        },
        {
            "name": "Cuestionario",
            "description": "Cuestionario de afinidad: preguntas generadas de leyes y coincidencia con políticos"
        },
        {
            "name": "Curules",
            "description": "Número de curules por cargo, periodo y ámbito geográfico"
        },
        {
            "name": "Ejecutivo",
            "description": "Presidente y Vicepresidente por periodo, elección, estado y partido"
        },
        {
            "name": "Salud",
            "description": "IPS / prestadores de salud (REPS) y acreditación"
        },
        {
            "name": "Estado",
            "description": "Entidades del Estado (SIGEP / Función Pública)"
        },
        {
            "name": "Geografía",
            "description": "Regiones, departamentos y municipios (DIVIPOLA)"
        },
        {
            "name": "Lugares",
            "description": "Otros lugares y entidades públicas"
        },
        {
            "name": "Catálogos",
            "description": "Partidos y cargos"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key",
                "description": "Opcional. Aumenta los límites de uso. Genera claves en /api-keys."
            }
        },
        "parameters": {
            "page": {
                "name": "page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 1
                },
                "description": "Número de página."
            },
            "perPage": {
                "name": "per_page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                },
                "description": "Elementos por página."
            },
            "q": {
                "name": "q",
                "in": "query",
                "schema": {
                    "type": "string"
                },
                "description": "Búsqueda de texto."
            },
            "department": {
                "name": "department",
                "in": "query",
                "schema": {
                    "type": "string"
                },
                "description": "Filtra por departamento (nombre o código DIVIPOLA)."
            },
            "municipality": {
                "name": "municipality",
                "in": "query",
                "schema": {
                    "type": "string"
                },
                "description": "Filtra por municipio (nombre o código DIVIPOLA)."
            }
        },
        "schemas": {
            "Pagination": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "first": {
                                "type": "string",
                                "nullable": true
                            },
                            "last": {
                                "type": "string",
                                "nullable": true
                            },
                            "prev": {
                                "type": "string",
                                "nullable": true
                            },
                            "next": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "meta": {
                        "type": "object",
                        "properties": {
                            "current_page": {
                                "type": "integer"
                            },
                            "per_page": {
                                "type": "integer"
                            },
                            "total": {
                                "type": "integer"
                            }
                        }
                    }
                }
            }
        },
        "responses": {
            "Collection": {
                "description": "Colección paginada.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Pagination"
                        }
                    }
                }
            }
        }
    },
    "security": [
        [],
        {
            "ApiKey": []
        }
    ],
    "paths": {
        "/people": {
            "get": {
                "summary": "Lista de políticos",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "position",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "president",
                                "vice_president",
                                "senator",
                                "representative",
                                "governor",
                                "mayor",
                                "deputy",
                                "councilor",
                                "corregidor"
                            ]
                        },
                        "description": "Filtra por cargo."
                    },
                    {
                        "name": "selection_method",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "elected",
                                "appointed"
                            ]
                        },
                        "description": "Cargos de elección popular vs. de designación (p. ej. corregidor)."
                    },
                    {
                        "name": "party",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filtra por partido."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/people/{politician}": {
            "get": {
                "summary": "Detalle de un político (incluye su trayectoria: periodos)",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "name": "politician",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/people/{politician}/terms": {
            "get": {
                "summary": "Trayectoria del político: periodos y cargos",
                "description": "Devuelve un periodo por cada cargo ejercido (position, period \"2022-2026\", fechas, departamento/municipio, partido e is_current), ordenados del más antiguo al más reciente.",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "name": "politician",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug del político."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/people/{politician}/bills": {
            "get": {
                "summary": "Leyes/proyectos de los que el político es autor",
                "tags": [
                    "Congreso"
                ],
                "parameters": [
                    {
                        "name": "politician",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug del político."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/coverage/{position}": {
            "get": {
                "summary": "Cobertura política por periodo: geografía sin el cargo",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "name": "position",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "representative",
                                "governor",
                                "deputy",
                                "mayor",
                                "councilor",
                                "corregidor"
                            ]
                        },
                        "description": "Cargo. representative/governor/deputy = departamento; mayor/councilor = municipio."
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Periodo electoral, p. ej. 2024-2027 (o usa from/to)."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Año inicial del periodo."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Año final del periodo."
                    },
                    {
                        "name": "department",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filtra municipios por departamento (nombre o código)."
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "422": {
                        "description": "Cargo sin cobertura geográfica"
                    }
                }
            }
        },
        "/candidates": {
            "get": {
                "summary": "Lista de candidatos (solo los no vinculados a un político)",
                "tags": [
                    "Candidatos"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "$ref": "#/components/parameters/municipality"
                    },
                    {
                        "name": "region",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filtra por región (nombre o código) — según el departamento de la candidatura."
                    },
                    {
                        "name": "position",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "president",
                                "vice_president",
                                "senator",
                                "representative",
                                "governor",
                                "mayor",
                                "deputy",
                                "councilor",
                                "corregidor"
                            ]
                        },
                        "description": "Filtra por cargo al que se aspiró (position_sought)."
                    },
                    {
                        "name": "party",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filtra por partido (nombre normalizado o texto del partido en la candidatura)."
                    },
                    {
                        "name": "coalition",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filtra por coalición."
                    },
                    {
                        "name": "election_type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "national",
                                "regional"
                            ]
                        },
                        "description": "Tipo de elección."
                    },
                    {
                        "name": "year",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Año de la elección (alias: election_year)."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Año inicial (candidaturas desde)."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Año final (candidaturas hasta)."
                    },
                    {
                        "name": "won",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Solo candidaturas ganadas/perdidas (normalmente desconocido para no vinculados)."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/candidates/{candidate}": {
            "get": {
                "summary": "Detalle de un candidato (incluye sus candidaturas)",
                "tags": [
                    "Candidatos"
                ],
                "parameters": [
                    {
                        "name": "candidate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/candidates/{candidate}/terms": {
            "get": {
                "summary": "Candidaturas de un candidato (una por elección/cargo)",
                "tags": [
                    "Candidatos"
                ],
                "parameters": [
                    {
                        "name": "candidate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Id del candidato."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "404": {
                        "description": "No encontrado o ya vinculado a un político."
                    }
                }
            }
        },
        "/senators": {
            "get": {
                "summary": "Senadores",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/representatives": {
            "get": {
                "summary": "Representantes a la Cámara",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/governors": {
            "get": {
                "summary": "Gobernadores",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/mayors": {
            "get": {
                "summary": "Alcaldes",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/deputies": {
            "get": {
                "summary": "Diputados",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/councilors": {
            "get": {
                "summary": "Concejales",
                "tags": [
                    "Personas"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/institutions": {
            "get": {
                "summary": "Instituciones (educación superior y colegios)",
                "tags": [
                    "Educación"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "university",
                                "school"
                            ]
                        },
                        "description": "Tipo de institución."
                    },
                    {
                        "name": "sector",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Oficial, Privado, No Oficial…"
                    },
                    {
                        "name": "academic_character",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Carácter académico (universidades)."
                    },
                    {
                        "name": "accredited",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Solo acreditadas de alta calidad."
                    },
                    {
                        "$ref": "#/components/parameters/municipality"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/institutions/{institution}": {
            "get": {
                "summary": "Detalle de una institución",
                "tags": [
                    "Educación"
                ],
                "parameters": [
                    {
                        "name": "institution",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/universities": {
            "get": {
                "summary": "Universidades / IES (SNIES)",
                "tags": [
                    "Educación"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/schools": {
            "get": {
                "summary": "Colegios y sedes educativas (DANE/SISE)",
                "tags": [
                    "Educación"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "sector",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/municipality"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/bills": {
            "get": {
                "summary": "Proyectos de ley",
                "tags": [
                    "Congreso"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "name": "bill_type",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tipo (p. ej. Acto Legislativo, Proyecto de Ley)."
                    },
                    {
                        "name": "commission",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Comisión (coincidencia parcial, p. ej. \"Comisión Primera\")."
                    },
                    {
                        "name": "origin",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Origen (Senado / Cámara)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Estado del trámite."
                    },
                    {
                        "name": "author",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Autor: slug o nombre del político, o el nombre del autor en el proyecto."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/bills/{bill}": {
            "get": {
                "summary": "Detalle de un proyecto de ley",
                "tags": [
                    "Congreso"
                ],
                "parameters": [
                    {
                        "name": "bill",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/bills/{bill}/authors": {
            "get": {
                "summary": "Autores de un proyecto de ley",
                "tags": [
                    "Congreso"
                ],
                "parameters": [
                    {
                        "name": "bill",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/bills/{bill}/votes": {
            "get": {
                "summary": "Votaciones de un proyecto de ley",
                "tags": [
                    "Congreso"
                ],
                "parameters": [
                    {
                        "name": "bill",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/quiz/generate": {
            "post": {
                "summary": "Generar preguntas del cuestionario a partir de leyes",
                "description": "Crea entre 1 y 50 preguntas a partir de leyes elegidas al azar y devuelve las preguntas creadas junto con las leyes de origen. Requiere API key. Las posiciones de los políticos se derivan de la autoría/votación de esas leyes (solo políticos activos).",
                "tags": [
                    "Cuestionario"
                ],
                "security": [
                    {
                        "ApiKey": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "count"
                                ],
                                "properties": {
                                    "count": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 50
                                    },
                                    "pool_size": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 200,
                                        "nullable": true
                                    },
                                    "version_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "description": "Versión destino; si se omite se crea una automáticamente."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Preguntas creadas (con las leyes de origen)."
                    },
                    "401": {
                        "description": "Falta API key."
                    },
                    "422": {
                        "description": "No hay leyes con datos suficientes para generar."
                    }
                }
            }
        },
        "/quiz/answers": {
            "post": {
                "summary": "Enviar respuestas y obtener políticos coincidentes",
                "description": "Recibe las respuestas del ciudadano y devuelve los políticos ordenados por afinidad.",
                "tags": [
                    "Cuestionario"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "answers"
                                ],
                                "properties": {
                                    "answers": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "required": [
                                                "question_id",
                                                "stance"
                                            ],
                                            "properties": {
                                                "question_id": {
                                                    "type": "integer"
                                                },
                                                "stance": {
                                                    "type": "string",
                                                    "enum": [
                                                        "agree",
                                                        "neutral",
                                                        "disagree"
                                                    ]
                                                },
                                                "important": {
                                                    "type": "boolean"
                                                }
                                            }
                                        }
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 100
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Políticos ordenados por coincidencia."
                    },
                    "422": {
                        "description": "Respuestas inválidas."
                    }
                }
            }
        },
        "/quiz/questions": {
            "get": {
                "summary": "Preguntas del cuestionario",
                "tags": [
                    "Cuestionario"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "name": "version_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Filtra por versión."
                    },
                    {
                        "name": "bill_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Filtra por ley de origen."
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Solo preguntas activas."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/quiz/questions/{question}": {
            "get": {
                "summary": "Detalle de una pregunta (con su ley de origen)",
                "tags": [
                    "Cuestionario"
                ],
                "parameters": [
                    {
                        "name": "question",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/quiz/versions/{version}": {
            "get": {
                "summary": "Preguntas de una versión",
                "tags": [
                    "Cuestionario"
                ],
                "parameters": [
                    {
                        "name": "version",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/quiz/bills/{bill}/questions": {
            "get": {
                "summary": "Preguntas generadas a partir de una ley (por id)",
                "tags": [
                    "Cuestionario"
                ],
                "parameters": [
                    {
                        "name": "bill",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/seats": {
            "get": {
                "summary": "Curules por cargo, periodo y ámbito",
                "tags": [
                    "Curules"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "name": "position",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Cargo/rol (senator, deputy, mayor, …)."
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "municipality_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "term_start",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Inicio exacto del periodo."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Rango: periodos que se solapan con [from, to]."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/seats/summary": {
            "get": {
                "summary": "Totales de curules agrupados por cargo",
                "description": "Suma curules, ocupadas, vacantes y vacancias registradas por cargo, con los mismos filtros que /seats.",
                "tags": [
                    "Curules"
                ],
                "parameters": [
                    {
                        "name": "position",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "department_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "municipality_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "term_start",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Totales por cargo."
                    }
                }
            }
        },
        "/executives": {
            "get": {
                "summary": "Presidente y Vicepresidente",
                "tags": [
                    "Ejecutivo"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Ciclo constitucional, p. ej. 2022-2026."
                    },
                    {
                        "name": "election_date",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "active|inactive."
                    },
                    {
                        "name": "party",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Nombre (parcial) o id del partido."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/executives/presidents": {
            "get": {
                "summary": "Presidentes",
                "tags": [
                    "Ejecutivo"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "election_date",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "party",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/executives/vice-presidents": {
            "get": {
                "summary": "Vicepresidentes",
                "tags": [
                    "Ejecutivo"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "election_date",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "party",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/regions": {
            "get": {
                "summary": "Regiones",
                "tags": [
                    "Geografía"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/regions/{region}/departments": {
            "get": {
                "summary": "Departamentos de una región",
                "tags": [
                    "Geografía"
                ],
                "parameters": [
                    {
                        "name": "region",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/departments": {
            "get": {
                "summary": "Departamentos (DIVIPOLA)",
                "tags": [
                    "Geografía"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/departments/{department}/municipalities": {
            "get": {
                "summary": "Municipios de un departamento",
                "tags": [
                    "Geografía"
                ],
                "parameters": [
                    {
                        "name": "department",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/municipalities": {
            "get": {
                "summary": "Municipios (DIVIPOLA). Incluye áreas no municipalizadas (corregimientos departamentales).",
                "tags": [
                    "Geografía"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "non_municipalized",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Filtra áreas no municipalizadas / corregimientos departamentales (DANE)."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/lookup": {
            "get": {
                "summary": "Resolver id/código por nombre o código",
                "description": "Devuelve el id interno (y código DIVIPOLA / ids padre) de una región, departamento, municipio o tipo de catálogo. Pasa cualquier combinación de parámetros.",
                "tags": [
                    "Geografía"
                ],
                "parameters": [
                    {
                        "name": "region",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Nombre o código de región."
                    },
                    {
                        "name": "department",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Nombre o código de departamento (también filtra municipios)."
                    },
                    {
                        "name": "municipality",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Nombre o código de municipio."
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Etiqueta de un ítem de catálogo (ej. tipo de IPS)."
                    },
                    {
                        "name": "catalog",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Restringe type a un catálogo (ej. ips_type)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Coincidencias por tipo.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/places": {
            "get": {
                "summary": "Lugares",
                "tags": [
                    "Lugares"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/places/{place}": {
            "get": {
                "summary": "Detalle de un lugar",
                "tags": [
                    "Lugares"
                ],
                "parameters": [
                    {
                        "name": "place",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/ips": {
            "get": {
                "summary": "IPS / prestadores de salud (principales, REPS)",
                "tags": [
                    "Salud"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Tipo de IPS (IPS Públicas, IPS Privadas, Profesional Independiente, Dir. Territoriales de Salud)."
                    },
                    {
                        "name": "region",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Región (nombre o código) — filtra por la región del departamento."
                    },
                    {
                        "name": "accredited",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Solo IPS acreditadas."
                    },
                    {
                        "$ref": "#/components/parameters/municipality"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/ips/{health_provider}": {
            "get": {
                "summary": "Detalle de una IPS con sus sedes (por código de habilitación de 10 dígitos)",
                "tags": [
                    "Salud"
                ],
                "parameters": [
                    {
                        "name": "health_provider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/ips-sedes": {
            "get": {
                "summary": "Todas las sedes de IPS (filtrables por código, departamento, municipio y acreditación)",
                "tags": [
                    "Salud"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Código de habilitación de la sede (12 dígitos)."
                    },
                    {
                        "name": "accredited",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Solo sedes acreditadas."
                    },
                    {
                        "$ref": "#/components/parameters/municipality"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/ips-sedes/{sede_code}": {
            "get": {
                "summary": "Una sede por su código de habilitación (12 dígitos)",
                "tags": [
                    "Salud"
                ],
                "parameters": [
                    {
                        "name": "sede_code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Código de habilitación de la sede (12 dígitos)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/ips/{health_provider}/sedes": {
            "get": {
                "summary": "Sedes de una IPS",
                "tags": [
                    "Salud"
                ],
                "parameters": [
                    {
                        "name": "health_provider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Código de habilitación del prestador (10 dígitos)."
                    },
                    {
                        "name": "accredited",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        },
                        "description": "Solo sedes acreditadas."
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/hospitals": {
            "get": {
                "summary": "Hospitales / IPS (alias de /ips)",
                "tags": [
                    "Salud"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/government-entities": {
            "get": {
                "summary": "Entidades del Estado (SIGEP / Función Pública)",
                "tags": [
                    "Estado"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    },
                    {
                        "name": "nit",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "NIT (coincidencia parcial)."
                    },
                    {
                        "name": "order",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "ORDEN (Nacional, Territorial)."
                    },
                    {
                        "name": "suborden",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "SUBORDEN (Municipal, Departamental, Distrital, …). Alias: kind."
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Alias de suborden (p. ej. kind=municipal)."
                    },
                    {
                        "name": "nivel",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "NIVEL (Central, Descentralizado)."
                    },
                    {
                        "name": "organic_classification",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "CLASIFICACIÓN ORGÁNICA."
                    },
                    {
                        "name": "sector",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "SECTOR."
                    },
                    {
                        "name": "legal_nature",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "NATURALEZA JURÍDICA."
                    },
                    {
                        "name": "linkage_type",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "TIPO DE VINCULACIÓN."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "ESTADO."
                    },
                    {
                        "$ref": "#/components/parameters/municipality"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/government-entities/{government_entity}": {
            "get": {
                "summary": "Detalle de una entidad del Estado (por slug)",
                "tags": [
                    "Estado"
                ],
                "parameters": [
                    {
                        "name": "government_entity",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Slug o identificador."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Recurso.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No encontrado."
                    }
                }
            }
        },
        "/public-entities": {
            "get": {
                "summary": "Entidades públicas",
                "tags": [
                    "Lugares"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    },
                    {
                        "$ref": "#/components/parameters/q"
                    },
                    {
                        "$ref": "#/components/parameters/department"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/parties": {
            "get": {
                "summary": "Partidos políticos",
                "tags": [
                    "Catálogos"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        },
        "/positions": {
            "get": {
                "summary": "Cargos",
                "tags": [
                    "Catálogos"
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/page"
                    },
                    {
                        "$ref": "#/components/parameters/perPage"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Collection"
                    }
                }
            }
        }
    }
}