ClaixClaixEN

Ventana de Contexto

Ventana de Contexto

Pregunta a un documento persistido tras una extracción con window_context activo.

Ventana de Contexto · Añadir a espacio

Asignar un documento a un espacio

Endpoint

POSThttps://claix.dev/add-space

Asigna un documento persistido que aún no tiene space_id a un espacio de conocimiento existente. Si el documento ya pertenece a un espacio, la API responde 400.

Útil cuando extrajiste el documento sin space_id y después quieres agruparlo para consultas cruzadas con POST /space-context/{space_id}.

URL pública: POST https://claix.dev/add-space. Nunca expongas la URL directa de Supabase.

Esta llamada es gratuita: no se factura ni consume el cupo de extracciones ni de ventana de contexto.

1. Autenticación

Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión de usuario.

Opción A — Header dedicado (recomendado):

x-api-key: <TU_API_KEY>

Opción B — Header estándar Authorization:

Authorization: Bearer <TU_API_KEY>

Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.

El sistema valida que la key exista y esté activa, y que la cuenta no esté suspendida. Si falla, responde 401. Documento y espacio deben pertenecer a la misma cuenta.

2. Formato de la petición

Método: POST · Content-Type: application/json

CampoTipoObligatorioDescripción
document_idstring (uuid)SíUUID del documento sin space_id. Debe existir y pertenecer a tu cuenta.
space_idstring (uuid)SíUUID del espacio de destino, obtenido con POST /create-space.

Cuerpo de ejemplo:

{
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
}

3. Cómo construir la llamada

  1. Ten un space_id (con POST /create-space) y un document_id de un documento sin espacio asignado.
  2. Envía POST a https://claix.dev/add-space con tu API key y el body JSON.
  3. Comprueba success y guarda space_id / version si los necesitas en tu flujo.

4. Ejemplos de llamada

Usa el panel de código de la derecha para copiar ejemplos en cURL, JavaScript, Python, etc.

5. Formato de la respuesta exitosa

HTTP 200 — El documento queda vinculado al espacio.

{
  "success": true,
  "document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
  "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c",
  "space_name": "Proveedores 2026",
  "file_name": "factura.pdf",
  "version": 1,
  "message": "Documento añadido al espacio de conocimiento."
}
CampoTipoDescripción
successbooleanSiempre true en una respuesta 200.
document_idstring (uuid)Documento asignado.
space_idstring (uuid)Espacio al que se ha añadido.
space_namestringNombre del espacio de destino.
file_namestringNombre de archivo del documento.
versionnumberVersión actual del documento.
messagestringMensaje legible de confirmación.

6. Códigos de error

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

400 — Body inválido, UUIDs mal formados, o el documento ya tiene un space_id.

401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta no activa.

404 — El documento o el espacio no existen, o no pertenecen a tu cuenta.

405 — Método distinto de POST. · 500 — Error interno.

7. Resumen de códigos

CódigoCategoría¿Reintentar?
200Éxito — documento añadido al espacio—
400Error del cliente (ya tiene espacio, UUID inválido o body incorrecto)No, corrige la petición primero
401Error de autenticaciónNo, corrige las credenciales primero
404Documento o espacio no encontradoNo, corrige los IDs primero
405Método HTTP incorrectoNo, usa POST
500Error interno del servidorSí, con precaución

8. Buenas prácticas

  • Prefiere pasar space_id en la extracción cuando ya sepas el grupo; usa este endpoint solo para reasignar a posteriori.
  • Si el documento ya está en un espacio, quítalo antes con DELETE /remove-document-from-space/{document_id} y luego vuelve a añadirlo.
  • Usa siempre el dominio público claix.dev, no la URL directa de Supabase.
  • No incluyas tu API key en frontend ni repositorios públicos.

Ejemplos de petición

curl -X POST "https://claix.dev/add-space" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"document_id":"d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b","space_id":"5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"}'