ClaixClaixEnglish

Ventana de Contexto

Ventana de Contexto

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

Ventana de Contexto · Crear espacio

Crear un espacio de conocimiento

Endpoint

POSThttps://claix.dev/create-space

Un espacio de conocimiento es una carpeta lógica donde agrupar documentos persistidos. Este endpoint crea el espacio vacío y te devuelve su space_id, que es la pieza que conecta las tres piezas del flujo: agrupar al extraer, preguntar a todo el grupo y, si hace falta, borrarlo.

El único campo de entrada es name. No hay nada más que configurar: un espacio no tiene schema, ni caducidad, ni ajustes propios.

URL pública: POST https://claix.dev/create-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. El espacio queda asociado a la cuenta dueña de la key, así que solo esa cuenta podrá usarlo o borrarlo después.

2. Formato de la petición

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

CampoTipoObligatorioDescripción
namestringSíNombre del espacio, por ejemplo «Proveedores 2026». Máximo 200 caracteres. Se recortan los espacios sobrantes al principio y al final.

Cuerpo de ejemplo:

{
  "name": "Proveedores 2026"
}

Se admiten nombres repetidos: cada llamada crea un espacio nuevo con su propio space_id. Si quieres nombres únicos, compruébalo en tu lado antes de llamar.

3. Cómo construir la llamada

  1. Envía POST a https://claix.dev/create-space con tu API key y un body JSON con name.
  2. Guarda el space_id de la respuesta en tu base de datos: es lo que necesitarás en los dos pasos siguientes.
  3. Al extraer con cualquiera de las cinco llamadas de extracción (o sus versiones Agent), añade space_id como campo opcional para que el documento guardado caiga dentro del espacio. Recuerda que solo se guarda documento si el schema tiene la ventana de contexto activada.
  4. Pregunta a todo el grupo con POST /space-context/{space_id}.

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 201 — Espacio creado. La respuesta devuelve el identificador, el nombre guardado y la fecha de creación.

{
  "success": true,
  "space": {
    "space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c",
    "name": "Proveedores 2026",
    "created_at": "2026-09-05T14:32:11.482Z"
  }
}
CampoTipoDescripción
successbooleanSiempre true en una respuesta 201.
space.space_idstring (uuid)Identificador del espacio. Es el valor que se envía como space_id al extraer y el que va en la URL de space-context y delete-space.
space.namestringNombre guardado, ya recortado de espacios sobrantes.
space.created_atstring (ISO 8601)Fecha y hora de creación del espacio.

6. Códigos de error

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos)."
}

400 — El body no es un objeto JSON, falta name, está vacío o supera los 200 caracteres.

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

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

7. Resumen de códigos

CódigoCategoría¿Reintentar?
201Éxito — espacio creado—
400Error del cliente (name ausente, vacío o demasiado largo)No, corrige la petición primero
401Error de autenticaciónNo, corrige las credenciales primero
405Método HTTP incorrectoNo, usa POST
500Error interno del servidorSí, con precaución

8. Buenas prácticas

  • Crea el espacio una sola vez y reutiliza su space_id; no lo crees en cada extracción.
  • Usa un espacio por unidad real de trabajo (un cliente, un expediente, un trimestre) en lugar de un único espacio gigante: las respuestas cruzadas son más precisas cuanto más acotado está el grupo.
  • Ponle nombres descriptivos: es lo único que verás para identificarlos.
  • 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/create-space" \
  -H "x-api-key: <TU_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Proveedores 2026"}'