{
    "openapi": "3.1.0",
    "info": {
        "title": "Política Electoral API",
        "version": "1.0.0",
        "description": "Public read-only API for political data: politicians, parties, public figures, events, key Congress votes, institutions, parliamentary procedures and political concepts. Coverage focused on Spain plus 23 other countries.",
        "contact": {
            "url": "https://www.politicaelectoral.com"
        },
        "license": {
            "name": "CC-BY-4.0",
            "identifier": "CC-BY-4.0"
        }
    },
    "servers": [
        {
            "url": "https://www.politicaelectoral.com",
            "description": "Production"
        }
    ],
    "paths": {
        "/api/v1/politicians": {
            "get": {
                "summary": "List politicians",
                "description": "Returns a paginated list of politicians for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listPoliticians",
                "tags": [
                    "Politicians"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "party",
                        "in": "query",
                        "description": "Filter by party slug.",
                        "schema": {
                            "type": "string",
                            "example": "psoe"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PoliticianListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/politicians/{slug}": {
            "get": {
                "summary": "Get a single Politicians",
                "description": "Returns a single Politicians by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getPoliticiansItem",
                "tags": [
                    "Politicians"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PoliticianResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/parties": {
            "get": {
                "summary": "List parties",
                "description": "Returns a paginated list of parties for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listParties",
                "tags": [
                    "Parties"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PartyListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/parties/{slug}": {
            "get": {
                "summary": "Get a single Parties",
                "description": "Returns a single Parties by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getPartiesItem",
                "tags": [
                    "Parties"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PartyResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/public-figures": {
            "get": {
                "summary": "List public-figures",
                "description": "Returns a paginated list of public-figures for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listPublicFigures",
                "tags": [
                    "Public figures"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "description": "Filter by `tipo` (monarch, journalist, businessman, advisor, judge, prosecutor, figure…). Judges and prosecutors are served under /jueces-y-fiscales on the site.",
                        "schema": {
                            "type": "string",
                            "example": "journalist"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicFigureListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/public-figures/{slug}": {
            "get": {
                "summary": "Get a single Public figures",
                "description": "Returns a single Public figures by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getPublicFiguresItem",
                "tags": [
                    "Public figures"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicFigureResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/events": {
            "get": {
                "summary": "List events",
                "description": "Returns a paginated list of events for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listEvents",
                "tags": [
                    "Events"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/events/{slug}": {
            "get": {
                "summary": "Get a single Events",
                "description": "Returns a single Events by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getEventsItem",
                "tags": [
                    "Events"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EventResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/votes": {
            "get": {
                "summary": "List votes",
                "description": "Returns a paginated list of votes for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listVotes",
                "tags": [
                    "Votes"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "year",
                        "in": "query",
                        "description": "Filter by year (4 digits).",
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{4}$",
                            "example": "2024"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VoteListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/votes/{slug}": {
            "get": {
                "summary": "Get a single Votes",
                "description": "Returns a single Votes by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getVotesItem",
                "tags": [
                    "Votes"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VoteResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/institutions": {
            "get": {
                "summary": "List institutions",
                "description": "Returns a paginated list of institutions for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listInstitutions",
                "tags": [
                    "Institutions"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "description": "Filter by `categoria` (parlamento, gobierno, judicial, control, consultivo, jefatura-estado).",
                        "schema": {
                            "type": "string",
                            "example": "judicial"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/InstitutionListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/institutions/{slug}": {
            "get": {
                "summary": "Get a single Institutions",
                "description": "Returns a single Institutions by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getInstitutionsItem",
                "tags": [
                    "Institutions"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/InstitutionResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/organizations": {
            "get": {
                "summary": "List organizations",
                "description": "Returns a paginated list of organizations for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listOrganizations",
                "tags": [
                    "Organizations"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "description": "Filter by `categoria` (sindicato, patronal, empresa, fundacion, lobby, ong).",
                        "schema": {
                            "type": "string",
                            "example": "sindicato"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrganizationListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/organizations/{slug}": {
            "get": {
                "summary": "Get a single Organizations",
                "description": "Returns a single Organizations by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getOrganizationsItem",
                "tags": [
                    "Organizations"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OrganizationResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/countries": {
            "get": {
                "summary": "List countries",
                "description": "Returns a paginated list of countries for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listCountries",
                "tags": [
                    "Countries"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "continent",
                        "in": "query",
                        "description": "Filter by `continente` (africa, america, asia, europa, oceania). Country pages live in the global scope: use `country=xx`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "africa",
                                "america",
                                "asia",
                                "europa",
                                "oceania"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CountryListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/countries/{slug}": {
            "get": {
                "summary": "Get a single Countries",
                "description": "Returns a single Countries by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getCountriesItem",
                "tags": [
                    "Countries"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CountryResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/procedures": {
            "get": {
                "summary": "List procedures",
                "description": "Returns a paginated list of procedures for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listProcedures",
                "tags": [
                    "Procedures"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProcedureListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/procedures/{slug}": {
            "get": {
                "summary": "Get a single Procedures",
                "description": "Returns a single Procedures by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getProceduresItem",
                "tags": [
                    "Procedures"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProcedureResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/political-concepts": {
            "get": {
                "summary": "List political-concepts",
                "description": "Returns a paginated list of political-concepts for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listPoliticalConcepts",
                "tags": [
                    "Political concepts"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "subcategory",
                        "in": "query",
                        "description": "Filter by `subcategoria` (fundamental | electoral | ley).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "fundamental",
                                "electoral",
                                "ley"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PoliticalConceptListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/political-concepts/{slug}": {
            "get": {
                "summary": "Get a single Political concepts",
                "description": "Returns a single Political concepts by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getPoliticalConceptsItem",
                "tags": [
                    "Political concepts"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PoliticalConceptResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/glossary": {
            "get": {
                "summary": "List glossary",
                "description": "Returns a paginated list of glossary for the given country. Items without published content in `lang` are excluded.",
                "operationId": "listGlossary",
                "tags": [
                    "Glossary"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1–200).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Pagination offset.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    },
                    {
                        "name": "letter",
                        "in": "query",
                        "description": "Filter by initial letter (a-z; ñ entries live under n).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GlossaryTermListResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/glossary/{slug}": {
            "get": {
                "summary": "Get a single Glossary",
                "description": "Returns a single Glossary by slug. Returns 404 when the slug has no published content for the requested `lang`.",
                "operationId": "getGlossaryItem",
                "tags": [
                    "Glossary"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Item",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GlossaryTermResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid slug or lang",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/dump.json": {
            "get": {
                "summary": "Full dump of every resource for a country (no pagination)",
                "description": "Returns all items of every resource in a single payload. Heavy; intended for offline snapshots and analytics. Use individual `/api/v1/dump/{resource}.json` for lighter dumps.",
                "operationId": "dumpAll",
                "tags": [
                    "Bulk dump"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Full dump",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BulkDumpAllResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/dump/{resource}.json": {
            "get": {
                "summary": "Full dump of a single resource for a country (no pagination)",
                "description": "Returns ALL items of the given resource for the given country, without pagination. Accepts the same filters as the regular listing endpoint.",
                "operationId": "dumpResource",
                "tags": [
                    "Bulk dump"
                ],
                "parameters": [
                    {
                        "name": "resource",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "politicians",
                                "parties",
                                "public-figures",
                                "events",
                                "votes",
                                "institutions",
                                "organizations",
                                "countries",
                                "procedures",
                                "political-concepts",
                                "glossary"
                            ]
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Content language. Only `es` is supported (the EN pilot was retired in August 2026).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "es"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resource dump",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BulkDumpResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown resource or country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/search": {
            "get": {
                "summary": "Free-text search across politicians, parties, public figures, events, votes, institutions, procedures and political concepts",
                "description": "Case- and accent-insensitive substring/prefix/whole-word match against the most relevant fields of each entity type. Results are scored and sorted by relevance.",
                "operationId": "search",
                "tags": [
                    "Search"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Search query (minimum 2 characters).",
                        "schema": {
                            "type": "string",
                            "minLength": 2
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Max results (1–50, default 20).",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 50,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Search results",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SearchResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Query too short",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/examples.json": {
            "get": {
                "summary": "Curated example URLs for AI agents",
                "description": "Returns a small set of suggested API calls covering the main resources. Useful for agent onboarding and discovery.",
                "operationId": "examples",
                "tags": [
                    "Discovery"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Examples",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/parties/{slug}/politicians": {
            "get": {
                "summary": "List politicians affiliated with a party",
                "operationId": "partyPoliticians",
                "tags": [
                    "Relations"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Related items",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meta": {
                                            "type": "object"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Politician"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/events/{slug}/related-politicians": {
            "get": {
                "summary": "List politicians referenced by an event",
                "operationId": "eventRelatedPoliticians",
                "tags": [
                    "Relations"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Related items",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meta": {
                                            "type": "object"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Politician"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/votes/{slug}/parties": {
            "get": {
                "summary": "Vote breakdown by party (with party metadata)",
                "description": "For each party that participated in the vote, returns the sense (for/against/abstain/absent/not_voting) plus the full party object.",
                "operationId": "voteParties",
                "tags": [
                    "Relations"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Vote breakdown",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meta": {
                                            "type": "object"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "party_id": {
                                                        "type": "string"
                                                    },
                                                    "sense": {
                                                        "type": "string",
                                                        "enum": [
                                                            "for",
                                                            "against",
                                                            "abstain",
                                                            "absent",
                                                            "not_voting"
                                                        ]
                                                    },
                                                    "party": {
                                                        "$ref": "#/components/schemas/Party"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Vote not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/politicians/{slug}/votes": {
            "get": {
                "summary": "Votes where the politician's party participated",
                "description": "Proxy: individual votes are not yet tracked, so the sense returned is the politician's party position for each vote.",
                "operationId": "politicianVotes",
                "tags": [
                    "Relations"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z0-9-]+$"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `ar`).",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$",
                            "enum": [
                                "ar",
                                "br",
                                "cl",
                                "co",
                                "de",
                                "es",
                                "eu",
                                "fr",
                                "gb",
                                "gr",
                                "hu",
                                "il",
                                "it",
                                "ma",
                                "mx",
                                "nl",
                                "pe",
                                "pl",
                                "pt",
                                "ru",
                                "se",
                                "sv",
                                "us",
                                "uy",
                                "ve",
                                "xx"
                            ],
                            "default": "es"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Votes by party proxy",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "meta": {
                                            "type": "object"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "vote_id": {
                                                        "type": "string"
                                                    },
                                                    "title": {
                                                        "type": "string"
                                                    },
                                                    "date": {
                                                        "type": "string",
                                                        "format": "date",
                                                        "nullable": true
                                                    },
                                                    "party_sense": {
                                                        "type": "string"
                                                    },
                                                    "links": {
                                                        "type": "object"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Politician not found",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Politician": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "pedro-sanchez"
                    },
                    "country": {
                        "type": "string",
                        "example": "espana"
                    },
                    "name": {
                        "type": "string",
                        "example": "Pedro Sánchez Pérez-Castejón"
                    },
                    "party": {
                        "type": "string",
                        "nullable": true
                    },
                    "current_role": {
                        "type": "string",
                        "nullable": true
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "birth_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "scope": {
                        "type": "string",
                        "nullable": true
                    },
                    "order": {
                        "type": "integer",
                        "nullable": true
                    },
                    "wikidata_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "same_as": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "PoliticianListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Politician"
                        }
                    }
                }
            },
            "PoliticianResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Politician"
                    }
                }
            },
            "Party": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "psoe"
                    },
                    "country": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "acronym": {
                        "type": "string",
                        "nullable": true
                    },
                    "color": {
                        "type": "string",
                        "nullable": true
                    },
                    "founded_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "ideological_family": {
                        "type": "string",
                        "nullable": true
                    },
                    "scope": {
                        "type": "string",
                        "nullable": true
                    },
                    "website": {
                        "type": "string",
                        "nullable": true,
                        "format": "uri"
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "PartyListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Party"
                        }
                    }
                }
            },
            "PartyResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Party"
                    }
                }
            },
            "PublicFigure": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "kind": {
                        "type": "string",
                        "description": "monarca | periodista | empresario | asesor | juez | fiscal | figura"
                    },
                    "current_role": {
                        "type": "string",
                        "nullable": true
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "birth_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "wikidata_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "same_as": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "PublicFigureListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PublicFigure"
                        }
                    }
                }
            },
            "PublicFigureResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/PublicFigure"
                    }
                }
            },
            "Event": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "title"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "date_end": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "category": {
                        "type": "string",
                        "nullable": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true
                    },
                    "keywords": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "EventListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Event"
                        }
                    }
                }
            },
            "EventResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Event"
                    }
                }
            },
            "Vote": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "title"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "kind": {
                        "type": "string",
                        "nullable": true,
                        "description": "ley-organica | ley-ordinaria | decreto-ley | mocion-censura | …"
                    },
                    "result": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "passed",
                            "rejected",
                            "withdrawn",
                            "pending"
                        ],
                        "description": "Outcome translated to English."
                    },
                    "votes": {
                        "type": "object",
                        "nullable": true,
                        "description": "Aggregate vote counts.",
                        "properties": {
                            "for": {
                                "type": "integer"
                            },
                            "against": {
                                "type": "integer"
                            },
                            "abstain": {
                                "type": "integer"
                            }
                        }
                    },
                    "votes_by_party": {
                        "type": "object",
                        "nullable": true,
                        "description": "Map of party_slug → vote sense.",
                        "additionalProperties": {
                            "type": "string",
                            "enum": [
                                "for",
                                "against",
                                "abstain",
                                "absent",
                                "not_voting"
                            ]
                        }
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "VoteListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Vote"
                        }
                    }
                }
            },
            "VoteResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Vote"
                    }
                }
            },
            "Institution": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "acronym": {
                        "type": "string",
                        "nullable": true
                    },
                    "category": {
                        "type": "string",
                        "nullable": true
                    },
                    "founded_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "headquarters": {
                        "type": "string",
                        "nullable": true
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "InstitutionListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Institution"
                        }
                    }
                }
            },
            "InstitutionResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Institution"
                    }
                }
            },
            "Organization": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "acronym": {
                        "type": "string",
                        "nullable": true
                    },
                    "category": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "sindicato",
                            "patronal",
                            "empresa",
                            "fundacion",
                            "lobby",
                            "ong",
                            null
                        ]
                    },
                    "founded_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "headquarters": {
                        "type": "string",
                        "nullable": true
                    },
                    "leader": {
                        "type": "string",
                        "nullable": true,
                        "description": "Current leader, free text (name and office)."
                    },
                    "members": {
                        "type": "string",
                        "nullable": true,
                        "description": "Membership figure as reported, free text with year and source."
                    },
                    "website": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true
                    },
                    "wikidata_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "same_as": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "OrganizationListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Organization"
                        }
                    }
                }
            },
            "OrganizationResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Organization"
                    }
                }
            },
            "Country": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string",
                        "description": "Scope of the page (xx = internacional)."
                    },
                    "name": {
                        "type": "string"
                    },
                    "official_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "iso2": {
                        "type": "string",
                        "nullable": true,
                        "description": "ISO 3166-1 alpha-2 code of the country itself."
                    },
                    "continent": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "africa",
                            "america",
                            "asia",
                            "europa",
                            "oceania",
                            null
                        ]
                    },
                    "capital": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "government": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "head_of_state": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "head_of_government": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "leaders": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Public-figure ids in the same scope."
                    },
                    "groups": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Institution ids in the same scope (g20, brics…)."
                    },
                    "population": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "gdp": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "currency": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "languages": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "next_elections": {
                        "type": "string",
                        "nullable": true,
                        "description": "Markdown text."
                    },
                    "website": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true
                    },
                    "wikidata_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "same_as": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "CountryListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Country"
                        }
                    }
                }
            },
            "CountryResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Country"
                    }
                }
            },
            "Procedure": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "acronym": {
                        "type": "string",
                        "nullable": true
                    },
                    "founded_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "ProcedureListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Procedure"
                        }
                    }
                }
            },
            "ProcedureResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Procedure"
                    }
                }
            },
            "PoliticalConcept": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name"
                ],
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "subcategory": {
                        "type": "string",
                        "enum": [
                            "fundamental",
                            "electoral",
                            "ley"
                        ]
                    },
                    "acronym": {
                        "type": "string",
                        "nullable": true
                    },
                    "founded_year": {
                        "type": "integer",
                        "nullable": true
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri"
                            },
                            "markdown": {
                                "type": "string",
                                "format": "uri"
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "PoliticalConceptListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/PoliticalConcept"
                        }
                    }
                }
            },
            "PoliticalConceptResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/PoliticalConcept"
                    }
                }
            },
            "GlossaryTerm": {
                "type": "object",
                "required": [
                    "id",
                    "country",
                    "name",
                    "definition"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "trifachito"
                    },
                    "country": {
                        "type": "string",
                        "example": "es"
                    },
                    "name": {
                        "type": "string",
                        "example": "Trifachito"
                    },
                    "definition": {
                        "type": "string"
                    },
                    "letter": {
                        "type": "string",
                        "pattern": "^[a-z]$"
                    },
                    "related": {
                        "type": "array",
                        "description": "Resolved links to canonical entities (politicians, parties, events, concepts, procedures, institutions, public figures).",
                        "items": {
                            "type": "object",
                            "properties": {
                                "kind": {
                                    "type": "string",
                                    "enum": [
                                        "politico",
                                        "partido",
                                        "personaje",
                                        "evento",
                                        "votacion",
                                        "institucion",
                                        "organizacion",
                                        "procedimiento",
                                        "concepto"
                                    ]
                                },
                                "name": {
                                    "type": "string"
                                },
                                "url": {
                                    "type": "string",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "profile": {
                                "type": "string",
                                "format": "uri",
                                "description": "HTML page (anchor in letter index)."
                            },
                            "self": {
                                "type": "string",
                                "format": "uri"
                            }
                        }
                    }
                }
            },
            "GlossaryTermListResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "offset": {
                                "type": "integer"
                            },
                            "returned": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/GlossaryTerm"
                        }
                    }
                }
            },
            "GlossaryTermResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object"
                    },
                    "data": {
                        "$ref": "#/components/schemas/GlossaryTerm"
                    }
                }
            },
            "SearchResult": {
                "type": "object",
                "properties": {
                    "kind": {
                        "type": "string",
                        "enum": [
                            "politician",
                            "public_figure",
                            "party",
                            "event",
                            "vote",
                            "institution",
                            "organization",
                            "country",
                            "procedure",
                            "political_concept"
                        ]
                    },
                    "id": {
                        "type": "string",
                        "description": "Slug of the matched entity."
                    },
                    "name": {
                        "type": "string"
                    },
                    "extra": {
                        "type": "string",
                        "description": "Secondary label (current role, acronym, date, subcategory, ...)."
                    },
                    "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "Public HTML profile URL."
                    },
                    "api": {
                        "type": "string",
                        "format": "uri",
                        "description": "Direct REST API endpoint for this item."
                    },
                    "score": {
                        "type": "integer"
                    }
                }
            },
            "SearchResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "query": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/SearchResult"
                        }
                    }
                }
            },
            "BulkDumpResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "resource": {
                                "type": "string"
                            },
                            "total": {
                                "type": "integer"
                            },
                            "api_version": {
                                "type": "string"
                            },
                            "generated_at": {
                                "type": "string",
                                "format": "date-time"
                            }
                        }
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "description": "Resource-specific schema; see the matching list endpoint."
                        }
                    }
                }
            },
            "BulkDumpAllResponse": {
                "type": "object",
                "properties": {
                    "meta": {
                        "type": "object",
                        "properties": {
                            "country": {
                                "type": "string"
                            },
                            "totals": {
                                "type": "object",
                                "description": "Map of resource → count"
                            },
                            "api_version": {
                                "type": "string"
                            },
                            "generated_at": {
                                "type": "string",
                                "format": "date-time"
                            }
                        }
                    },
                    "data": {
                        "type": "object",
                        "description": "Object keyed by resource name; each value is an array of that resource's items."
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            },
                            "status": {
                                "type": "integer"
                            }
                        }
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "Politicians"
        },
        {
            "name": "Parties"
        },
        {
            "name": "Public figures"
        },
        {
            "name": "Events"
        },
        {
            "name": "Votes"
        },
        {
            "name": "Institutions"
        },
        {
            "name": "Organizations"
        },
        {
            "name": "Countries"
        },
        {
            "name": "Procedures"
        },
        {
            "name": "Political concepts"
        },
        {
            "name": "Glossary"
        },
        {
            "name": "Bulk dump",
            "description": "Snapshot endpoints that return entire resources at once."
        },
        {
            "name": "Search",
            "description": "Cross-entity free-text search."
        },
        {
            "name": "Discovery",
            "description": "Endpoints helpful for agent onboarding."
        },
        {
            "name": "Relations",
            "description": "Endpoints that navigate between related entities (party↔politicians, vote↔parties, event↔politicians)."
        }
    ]
}