Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.1.0",
"info": {
"title": "ES·pera API",
"version": "1.0.0",
"description": "API pública de solo lectura para consultar releases, métricas, hospitales y listas de espera autonómicas publicadas por ES·pera. Los datos se sirven desde releases inmutables fijadas en cada despliegue. La procedencia y las condiciones aplicables se conservan por conjunto de datos. El tráfico anónimo está limitado a 120 solicitudes por minuto; /waiting/facets y /waiting/observations tienen además un límite de 20 por minuto. Las respuestas 429 indican el tiempo de espera mediante Retry-After."
},
"externalDocs": {
"description": "Documentación de la API",
"url": "https://es-pera.org/metodologia/api/"
},
"servers": [
{
"url": "https://es-pera.org/api/v1",
"description": "Producción"
}
],
"security": [],
"tags": [
{
"name": "Estado",
"description": "Salud y releases fijadas por el despliegue."
},
{
"name": "Hospitales",
"description": "Métricas, directorio y detalle hospitalario nacional."
},
{
"name": "Listas autonómicas",
"description": "Catálogo acotado de listas de espera publicadas por las comunidades autónomas."
}
],
"paths": {
"/health": {
"get": {
"operationId": "getHealth",
"summary": "Comprueba el estado de la API y sus releases",
"tags": ["Estado"],
"responses": {
"200": {
"description": "Todas las releases configuradas están accesibles.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
}
}
}
},
"/releases/current": {
"get": {
"operationId": "getCurrentReleases",
"summary": "Devuelve las releases activas del despliegue",
"tags": ["Estado"],
"responses": {
"200": {
"description": "Metadatos de las releases hospitalaria, de registro y autonómica.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/CurrentReleases" }
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/metrics": {
"get": {
"operationId": "listMetrics",
"summary": "Enumera las métricas hospitalarias publicadas",
"tags": ["Hospitales"],
"responses": {
"200": {
"description": "Catálogo de métricas de la release hospitalaria activa.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["releaseId", "metrics"],
"properties": {
"releaseId": { "type": "string" },
"metrics": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/entities": {
"get": {
"operationId": "listEntities",
"summary": "Busca hospitales o enumera complejos",
"tags": ["Hospitales"],
"parameters": [
{
"name": "q",
"in": "query",
"description": "Nombre, CCN o código del hospital.",
"schema": { "type": "string", "maxLength": 100 }
},
{
"name": "ccaa",
"in": "query",
"description": "Nombre exacto de la comunidad autónoma.",
"schema": { "type": "string", "maxLength": 80 }
},
{
"name": "type",
"in": "query",
"description": "Perímetro de entidad.",
"schema": { "type": "string", "enum": ["hospital", "complex"] }
},
{
"name": "limit",
"in": "query",
"description": "Número máximo de resultados.",
"schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }
}
],
"responses": {
"200": {
"description": "Entidades de la release activa.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["releaseId", "registryReleaseId", "entities"],
"properties": {
"releaseId": { "type": "string" },
"registryReleaseId": { "type": "string" },
"entities": {
"type": "array",
"items": { "$ref": "#/components/schemas/EntitySummary" }
}
}
}
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/entities/{entityId}": {
"get": {
"operationId": "getEntity",
"summary": "Devuelve el detalle publicado de una entidad",
"tags": ["Hospitales"],
"parameters": [
{
"name": "entityId",
"in": "path",
"required": true,
"description": "Identificador devuelto por el listado de entidades.",
"schema": { "type": "string", "minLength": 1, "maxLength": 160 }
}
],
"responses": {
"200": {
"description": "Identidad pública, capacidades, observaciones y procedencia pública disponibles. Los identificadores de unidad fuente y la evidencia interna de resolución de identidad no forman parte del contrato público.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/EntityDetailResponse" }
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/waiting/releases/current": {
"get": {
"operationId": "getCurrentWaitingRelease",
"summary": "Devuelve la release autonómica activa",
"tags": ["Listas autonómicas"],
"responses": {
"200": {
"description": "Metadatos del catálogo autonómico activo.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/WaitingRelease" }
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/waiting/communities": {
"get": {
"operationId": "listWaitingCommunities",
"summary": "Enumera la cobertura autonómica disponible",
"tags": ["Listas autonómicas"],
"responses": {
"200": {
"description": "Cobertura por comunidad y dominio.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["releaseId", "availability"],
"properties": {
"releaseId": { "type": "string" },
"availability": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/waiting/facets": {
"get": {
"operationId": "getWaitingFacets",
"summary": "Enumera filtros disponibles para una comunidad",
"tags": ["Listas autonómicas"],
"parameters": [
{ "$ref": "#/components/parameters/Community" },
{ "$ref": "#/components/parameters/Domain" },
{ "$ref": "#/components/parameters/Period" },
{ "$ref": "#/components/parameters/DatasetId" }
],
"responses": {
"200": {
"description": "Periodos, perímetros, territorios, centros, prestaciones y cohortes disponibles.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/waiting/observations": {
"get": {
"operationId": "listWaitingObservations",
"summary": "Consulta observaciones autonómicas paginadas",
"tags": ["Listas autonómicas"],
"parameters": [
{ "$ref": "#/components/parameters/Community" },
{ "$ref": "#/components/parameters/Domain" },
{ "$ref": "#/components/parameters/Period" },
{ "$ref": "#/components/parameters/DatasetId" },
{
"name": "perimeter",
"in": "query",
"schema": { "type": "string", "enum": ["community", "province", "area", "centre"] }
},
{
"name": "geographyId",
"in": "query",
"schema": { "type": "string", "maxLength": 100 }
},
{
"name": "centreId",
"in": "query",
"schema": { "type": "string", "maxLength": 100 }
},
{
"name": "itemId",
"in": "query",
"schema": { "type": "string", "maxLength": 100 }
},
{
"name": "cohortId",
"in": "query",
"schema": { "type": "string", "maxLength": 100 }
},
{
"name": "limit",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }
},
{
"name": "offset",
"in": "query",
"schema": { "type": "integer", "minimum": 0, "maximum": 50000, "default": 0 }
}
],
"responses": {
"200": {
"description": "Página de observaciones con contexto, valores y procedencia.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["releaseId", "filters", "pagination", "observations"],
"properties": {
"releaseId": { "type": "string" },
"filters": { "type": "object", "additionalProperties": true },
"pagination": { "$ref": "#/components/schemas/Pagination" },
"observations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"503": {
"$ref": "#/components/responses/Unavailable"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
}
},
"components": {
"parameters": {
"Community": {
"name": "community",
"in": "query",
"required": true,
"description": "Slug de la comunidad devuelto por /waiting/communities.",
"schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 80 }
},
"Domain": {
"name": "domain",
"in": "query",
"schema": { "type": "string", "enum": ["consultation", "surgery", "diagnostic_test"] }
},
"Period": {
"name": "period",
"in": "query",
"schema": { "type": "string", "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$", "example": "2026-07" }
},
"DatasetId": {
"name": "datasetId",
"in": "query",
"schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 100 }
}
},
"responses": {
"BadRequest": {
"description": "Los filtros o el identificador no son válidos.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
},
"NotFound": {
"description": "La entidad no existe en la release activa.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
},
"Unavailable": {
"description": "Una release configurada no está disponible.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
},
"TooManyRequests": {
"description": "Se ha superado el límite de tráfico anónimo. El cliente debe esperar antes de reintentar.",
"headers": {
"Retry-After": {
"description": "Segundos que debe esperar el cliente antes de reintentar.",
"schema": { "type": "integer", "minimum": 1, "example": 60 }
},
"RateLimit-Limit": {
"description": "Máximo aplicable en la ventana actual.",
"schema": { "type": "integer", "example": 120 }
},
"RateLimit-Policy": {
"description": "Política aplicada con límite y ventana en segundos.",
"schema": { "type": "string", "example": "120;w=60" }
}
},
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
}
},
"schemas": {
"Health": {
"type": "object",
"required": ["ok", "service", "releaseId", "registryReleaseId"],
"properties": {
"ok": { "type": "boolean" },
"service": { "type": "string", "const": "es-pera-core" },
"releaseId": { "type": "string" },
"registryReleaseId": { "type": "string" },
"sourceCommit": { "type": ["string", "null"] },
"dataDate": { "type": ["string", "null"], "format": "date" },
"contentSha256": { "type": ["string", "null"] },
"registryContentSha256": { "type": ["string", "null"] },
"registryCenterCount": { "type": ["integer", "null"] },
"waitingReleaseId": { "type": ["string", "null"] },
"waitingContentSha256": { "type": ["string", "null"] }
}
},
"EntitySummary": {
"type": "object",
"required": ["id", "entityType", "name"],
"properties": {
"id": { "type": "string", "description": "Identificador opaco devuelto por la API. Debe reutilizarse sin intentar derivar identificadores de las fuentes internas." },
"entityType": { "type": "string", "enum": ["hospital", "complex"] },
"ccn": { "type": ["string", "null"], "description": "Código público del registro sanitario cuando está disponible." },
"codcnh": { "type": ["string", "null"], "description": "Código público del Catálogo Nacional de Hospitales cuando está disponible." },
"name": { "type": "string" },
"municipality": { "type": ["string", "null"] },
"ccaa": { "type": ["string", "null"] },
"routePath": { "type": ["string", "null"] },
"regcessCurrent": { "type": "boolean" },
"centreClass": { "type": ["string", "null"] },
"dependencyFamily": { "type": ["string", "null"] },
"teaching": { "type": ["boolean", "null"] },
"snsConcert": { "type": ["boolean", "null"] },
"snsRelationship": { "type": ["string", "null"] },
"snsRelationshipLabel": { "type": ["string", "null"] },
"authorizedServiceCount": { "type": ["integer", "null"] },
"capabilities": {
"oneOf": [
{ "$ref": "#/components/schemas/EntityCapabilities" },
{ "type": "null" }
]
}
},
"additionalProperties": false
},
"EntityCapabilities": {
"type": "object",
"properties": {
"structure": { "type": "boolean" },
"activityLatest": { "type": "boolean" },
"economics": { "type": "boolean" },
"technology": { "type": "boolean" },
"waiting": { "type": "boolean" },
"longitudinal": { "type": "boolean" },
"specialties": { "type": "boolean" },
"waitingSystem": { "type": ["string", "null"] },
"waitingLabel": { "type": ["string", "null"] },
"waitingDataUrl": { "type": ["string", "null"] },
"seriesYears": { "type": "array", "items": { "type": "integer" } },
"specialtyYears": { "type": "array", "items": { "type": "integer" } }
},
"additionalProperties": false
},
"HospitalObservation": {
"type": "object",
"required": ["metric_id", "label", "domain", "kind", "period_year", "observation_kind", "perimeter"],
"properties": {
"metric_id": { "type": "string" },
"label": { "type": "string" },
"short_label": { "type": ["string", "null"] },
"domain": { "type": "string" },
"kind": { "type": "string" },
"period_year": { "type": "integer" },
"observation_kind": { "type": "string" },
"value_num": { "type": ["number", "null"] },
"perimeter": { "type": "string" }
},
"additionalProperties": false
},
"PublicHospitalProvenance": {
"type": "object",
"required": ["metric_id", "period_year", "layer", "publisher", "perimeter"],
"properties": {
"metric_id": { "type": ["string", "null"] },
"period_year": { "type": "integer" },
"layer": { "type": "string", "const": "national-hospital-activity" },
"publisher": { "type": "string", "const": "Ministerio de Sanidad" },
"perimeter": { "type": "string" }
},
"additionalProperties": false
},
"EntityDetailResponse": {
"type": "object",
"required": ["entity", "capabilities", "observations", "peerReference", "peerReferenceYears", "provenance"],
"properties": {
"releaseId": { "type": "string" },
"registryReleaseId": { "type": "string" },
"entity": { "$ref": "#/components/schemas/EntitySummary" },
"capabilities": {
"oneOf": [
{ "$ref": "#/components/schemas/EntityCapabilities" },
{ "type": "null" }
]
},
"observations": { "type": "array", "items": { "$ref": "#/components/schemas/HospitalObservation" } },
"peerReference": { "type": ["object", "null"], "additionalProperties": true },
"peerReferenceYears": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
"provenance": { "type": "array", "items": { "$ref": "#/components/schemas/PublicHospitalProvenance" } },
"registry": {
"type": "object",
"properties": {
"regcessCurrent": { "type": "boolean" },
"regcessReferenceDate": { "type": ["string", "null"], "format": "date" },
"cnhReferenceDate": { "type": ["string", "null"], "format": "date" },
"address": { "type": ["string", "null"] },
"phone": { "type": ["string", "null"] },
"url": { "type": ["string", "null"] },
"bedsInstalled": { "type": ["integer", "null"] },
"services": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
"technologies": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
"peers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"HospitalCoreRelease": {
"type": "object",
"required": ["release_id", "content_sha256"],
"properties": {
"release_id": { "type": "string" },
"schema_version": { "type": "integer" },
"content_sha256": { "type": "string" },
"label": { "type": "string" },
"source_commit": { "type": "string" },
"data_date": { "type": ["string", "null"], "format": "date" },
"created_at": { "type": "string" }
},
"additionalProperties": false
},
"RegistryRelease": {
"type": "object",
"required": ["release_id", "content_sha256", "center_count"],
"properties": {
"release_id": { "type": "string" },
"source_commit": { "type": "string" },
"content_sha256": { "type": "string" },
"regcess_reference_date": { "type": ["string", "null"], "format": "date" },
"cnh_reference_date": { "type": ["string", "null"], "format": "date" },
"center_count": { "type": "integer" },
"service_count": { "type": "integer" },
"technology_count": { "type": "integer" },
"peer_count": { "type": "integer" },
"imported_at": { "type": "string" }
},
"additionalProperties": false
},
"WaitingRelease": {
"type": "object",
"required": ["catalog_release_id", "content_sha256"],
"properties": {
"catalog_release_id": { "type": "string" },
"schema_version": { "type": "integer" },
"content_sha256": { "type": "string" },
"label": { "type": "string" },
"source_commit": { "type": "string" },
"created_at": { "type": "string" },
"notes": { "type": ["string", "null"] }
},
"additionalProperties": false
},
"CurrentReleases": {
"type": "object",
"required": ["release_id", "content_sha256", "registryRelease", "waitingRelease"],
"properties": {
"release_id": { "type": "string" },
"schema_version": { "type": "integer" },
"content_sha256": { "type": "string" },
"label": { "type": "string" },
"source_commit": { "type": "string" },
"data_date": { "type": ["string", "null"], "format": "date" },
"created_at": { "type": "string" },
"registryRelease": { "$ref": "#/components/schemas/RegistryRelease" },
"waitingRelease": {
"oneOf": [
{ "$ref": "#/components/schemas/WaitingRelease" },
{ "type": "null" }
]
}
},
"additionalProperties": false
},
"Pagination": {
"type": "object",
"required": ["limit", "offset", "returned", "hasMore", "nextOffset"],
"properties": {
"limit": { "type": "integer" },
"offset": { "type": "integer" },
"returned": { "type": "integer" },
"hasMore": { "type": "boolean" },
"nextOffset": { "type": ["integer", "null"] }
}
},
"Error": {
"type": "object",
"required": ["error"],
"properties": {
"error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": { "type": "string" },
"message": { "type": "string" }
}
}
}
}
}
}
}