{
 "openapi": "3.1.0",
 "info": {
  "title": "API pública del Índice OIA-CO",
  "version": "1.0.0",
  "description": "Datos públicos y de solo lectura del Índice OIA-CO (Observatorio de Inteligencia Artificial de Colombia). Archivos JSON estáticos regenerados en cada publicación; los filtros por consulta están disponibles en el servidor MCP. Atribución: citar «Índice OIA-CO» con la fecha de corte. Valores ausentes = null."
 },
 "servers": [
  {
   "url": "https://observatorioiacolombia.com"
  }
 ],
 "paths": {
  "/api/v1/metodologia.json": {
   "get": {
    "summary": "Metodología oficial, dimensiones S/I/A/L/R, reglas y limitaciones.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/estadisticas.json": {
   "get": {
    "summary": "Indicadores agregados con periodo y fecha de corte.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/lineas.json": {
   "get": {
    "summary": "Líneas del ecosistema con conteos.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/lineas/{slug}.json": {
   "get": {
    "summary": "Una línea con su ranking.",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/especialidades.json": {
   "get": {
    "summary": "Catálogo controlado de especialidades (8 de IA + áreas vecinas).",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/especialidades/{slug}.json": {
   "get": {
    "summary": "Una especialidad con actores y señales.",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/ciudades.json": {
   "get": {
    "summary": "Ciudades con actores documentados, coordenadas y DIVIPOLA.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/ciudades/{slug}.json": {
   "get": {
    "summary": "Una ciudad con sus actores.",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/ranking.json": {
   "get": {
    "summary": "Ranking general con desglose S/I/A/L/R.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/actores.json": {
   "get": {
    "summary": "Índice de personas y organizaciones con su identificador estable.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/personas/{id}.json": {
   "get": {
    "summary": "Ficha pública de una persona.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/personas/{id}/fuentes.json": {
   "get": {
    "summary": "Fuentes de una persona.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/personas/{id}/senales.json": {
   "get": {
    "summary": "Señales de una persona.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/organizaciones.json": {
   "get": {
    "summary": "Organizaciones con líderes vinculados.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/organizaciones/{id}.json": {
   "get": {
    "summary": "Ficha de una organización.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/senales.json": {
   "get": {
    "summary": "Señales con fuente, ordenadas por fecha de publicación.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/senales/{id}.json": {
   "get": {
    "summary": "Una señal con sus entidades.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/relaciones.json": {
   "get": {
    "summary": "Relaciones documentadas (trabaja_en, menciona_a) con evidencia.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/grafo.json": {
   "get": {
    "summary": "Nodos y aristas del grafo de señales.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/preguntas.json": {
   "get": {
    "summary": "Preguntas frecuentes con respuesta y enlaces.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/preguntas/{id}.json": {
   "get": {
    "summary": "Una pregunta.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  },
  "/api/v1/participacion/requisitos.json": {
   "get": {
    "summary": "Requisitos de nominación, corrección y tipos de solicitud.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "OK. Cuerpo: { data, meta, api_version }",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "Recurso inexistente"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Envelope": {
    "type": "object",
    "required": [
     "data",
     "meta",
     "api_version"
    ],
    "properties": {
     "data": {},
     "api_version": {
      "type": "string"
     },
     "meta": {
      "type": "object",
      "properties": {
       "fuente": {
        "type": "string"
       },
       "edicion": {
        "type": "string"
       },
       "fecha_corte": {
        "type": "string",
        "format": "date"
       },
       "actualizado": {
        "type": "string",
        "format": "date"
       },
       "ventana": {
        "type": "string"
       },
       "metodologia": {
        "type": "string"
       },
       "atribucion": {
        "type": "string"
       },
       "total": {
        "type": "integer"
       }
      }
     }
    }
   },
   "Persona": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "tipo": {
      "const": "persona"
     },
     "nombre": {
      "type": "string"
     },
     "cargo": {
      "type": [
       "string",
       "null"
      ]
     },
     "puntaje": {
      "type": "object",
      "properties": {
       "total": {
        "type": "number"
       },
       "S": {
        "type": "number"
       },
       "I": {
        "type": "number"
       },
       "A": {
        "type": "number"
       },
       "L": {
        "type": "number"
       },
       "R": {
        "type": "number"
       },
       "penalizacion": {
        "type": "number"
       }
      }
     },
     "fuentes": {
      "type": "array"
     },
     "url_canonica": {
      "type": "string"
     },
     "fecha_corte": {
      "type": "string"
     }
    }
   },
   "Senal": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "titulo": {
      "type": [
       "string",
       "null"
      ]
     },
     "medio": {
      "type": [
       "string",
       "null"
      ]
     },
     "fecha_publicacion": {
      "type": [
       "string",
       "null"
      ]
     },
     "fecha_hecho": {
      "type": [
       "string",
       "null"
      ]
     },
     "url_fuente": {
      "type": "string"
     },
     "verificacion": {
      "type": [
       "string",
       "null"
      ]
     },
     "actores": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "Relacion": {
    "type": "object",
    "properties": {
     "source_id": {
      "type": "string"
     },
     "target_id": {
      "type": "string"
     },
     "relation_type": {
      "type": "string"
     },
     "evidence_url": {
      "type": [
       "string",
       "null"
      ]
     },
     "verified_at": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   }
  }
 }
}