Ask: consulta agéntica

Ask

POST /api/v2/ask

Responde preguntas en lenguaje natural sobre normativa de construcción española en el contexto de un proyecto de Normatia.

No es un RAG de un solo disparo: ejecuta el mismo bucle agéntico que el chat de normatia.com. El modelo encadena varias búsquedas con enfoques distintos, lee la memoria y los cálculos guardados del proyecto, consulta los documentos subidos y redacta la respuesta citando cada fuente con marcadores [N] validados contra los bloques realmente recuperados.

Autenticación

Requiere API key en el header Authorization:

Authorization: Bearer sk-normatia-...

El proyecto define el alcance

La consulta se resuelve siempre sobre un proyecto, que ya tiene configurados el municipio, las normativas aplicables y los documentos. No hay que pasar geo_id ni filtros de normativa: el alcance sale del proyecto.

project_id explícito  →  proyecto activo del usuario

Si se omite project_id se usa el proyecto activo. Para consultar otro, obtén su identificador en GET /api/v1/projects y pásalo aquí: no hace falta cambiar el proyecto activo, y dos llamadas en paralelo a proyectos distintos no se pisan.

Request

Body

Campo	Tipo	Requerido	Descripción
`query`	string	Sí	Pregunta en lenguaje natural (de 1 a 2000 caracteres)
`project_id`	uuid	No	Proyecto sobre el que consultar. Si se omite, el proyecto activo del usuario

Ejemplo

{
  "query": "¿Cuál es el límite de transmitancia para ventanas en mi proyecto?",
  "project_id": "3f8c1a90-5b2e-4d77-9d21-0e5f4a6c8b13"
}

Response

Campo	Tipo	Descripción
`answer`	string	Respuesta generada, con marcadores de cita `[N]`
`sources`	array	Fuentes citadas en la respuesta. El `index` es el `N` de cada marcador
`project`	object	Proyecto contra el que se resolvió la consulta
`iterations`	integer	Rondas de razonamiento que consumió el turno
`searches`	integer	Búsquedas normativas ejecutadas

Fuentes (`sources[]`)

Campo	Descripción
`index`	Número de la fuente: el `N` de las citas `[N]`
`citation_type`	`article`, `document`, `collection` o `user_document`
`document_title`	Título del documento normativo
`section_title`	Título de la sección
`block_title`	Título del bloque o artículo concreto
`url`	Enlace directo a la sección en Normatia
`url_valid`	`false` si el enlace no pudo resolverse
`block_id`	UUID del bloque recuperado

citation_type: "user_document" identifica un documento privado subido al proyecto: no lleva URL pública.

Proyecto (`project`)

Campo	Descripción
`project_id`	Identificador del proyecto resuelto
`geo_id`	Identificador geográfico del proyecto
`location`	Municipio o territorio del proyecto

Ejemplo de respuesta

{
  "answer": "Para tu proyecto en Madrid (zona climática D3), el CTE DB-HE 1 establece un límite de transmitancia de 1,4 W/m²K para huecos [1]. Ese valor es el aplicable a la orientación norte sin corrección adicional [2].",
  "sources": [
    {
      "index": 1,
      "citation_type": "article",
      "document_title": "CTE DB-HE Ahorro de Energía",
      "section_title": "3.1.1 Transmitancia térmica",
      "block_title": "Tabla 3.1.1.b-HE1",
      "url": "https://normatia.com/es/normativa/cte-db-he/...",
      "url_valid": true,
      "block_id": "6b1f8c22-...-a41d"
    }
  ],
  "project": {
    "project_id": "3f8c1a90-5b2e-4d77-9d21-0e5f4a6c8b13",
    "geo_id": "ES-28079",
    "location": "Madrid"
  },
  "iterations": 3,
  "searches": 2
}

Latencia y presupuestos

Un turno agéntico encadena varias llamadas al modelo, así que la respuesta tarda bastante más que una búsqueda simple. El servidor acota el turno para que no se dispare:

Presupuesto	Valor
Rondas de razonamiento	6
Búsquedas normativas	6
Timeout del turno	120 s

Configura el timeout de tu cliente HTTP en 150 segundos o más. Si cortas antes, el turno sigue ejecutándose en el servidor, consume su crédito y nadie recibe la respuesta.

Errores

Los errores llegan dentro de detail, con el código en detail.error (ver Autenticación).

Estado	`detail.error`	Cuándo
400	`no_active_project`	No se pasó `project_id` y el usuario no tiene proyecto activo
403	`insufficient_scope`	La clave no tiene el permiso `ask`
403	`not_available_in_sandbox`	Es una clave de prueba: las consultas no están en el entorno de pruebas
404	`project_not_found`	El proyecto no existe o el usuario no tiene acceso
422		`query` vacía o de más de 2000 caracteres, `project_id` que no es un UUID o campos desconocidos en el cuerpo (`detail` es una lista)
429	`quota_exceeded`	Créditos del plan agotados
429	`rate_limit_exceeded`	Demasiadas peticiones por minuto

Si el proyecto no tiene ninguna normativa ni documento seleccionado, la respuesta llega con 200 y un answer que lo explica, sources vacío y iterations: 0, y no se consume crédito.

Cuota

Cada llamada consume 1 crédito, independientemente de cuántas búsquedas encadene el agente internamente. El endpoint pertenece al grupo de inteligencia. Consulta los límites en Autenticación.

Versión anterior: `/api/v1/ask`

POST /api/v1/ask era el motor anterior: una única búsqueda semántica sobre el proyecto activo, sin herramientas, sin memoria de proyecto y sin cálculos.

Está congelado: se mantiene para no romper las integraciones que ya lo usan, no recibe cambios y no aparece en el esquema público. No tiene fecha de retirada; si llega a tenerla, se anunciará en Cambios. Su cuerpo solo admite query: los campos geo_id, codes y messages que aceptaba antes se eliminaron y ahora devuelven 422.

Migrar es directo: cambia la ruta a /api/v2/ask y sustituye la lectura de geo_context por project. La respuesta ya no trae tokens_used, y trae iterations y searches. Los objetos de sources[] mantienen index, citation_type, document_title, section_title, block_title, block_id y url; pierden code_slug, version y similarity_score, y ganan url_valid.