Ventana de Contexto · Eliminar documento
Eliminar un documento persistido
Endpoint
https://claix.dev/delete-document/{document_id}Endpoint de escritura que borra un documento concreto de la tabla documents por document_id. No recibe body ni query params: el identificador viaja únicamente en la URL.
El borrado filtra por id y por user_id a la vez, de modo que un document_id ajeno nunca puede eliminarse con tu API key. Si el UUID no existe, ya expiró y fue purgado, o pertenece a otra cuenta, responde 404 con el mismo mensaje genérico (sin revelar el motivo exacto).
URL pública: DELETE https://claix.dev/delete-document/{document_id}
La operación es irreversible. 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, esté activa y que el usuario asociado tenga status = active. Si falla, responde 401.
2. Formato de la petición
Método: DELETE · Body: no requerido · Query params: ninguno
| Parámetro | Ubicación | Obligatorio | Descripción |
|---|---|---|---|
| document_id | URL path | Sí | UUID del documento devuelto por una extracción con window_context o memoria persistente activa. |
Formato esperado de la URL: /delete-document/{document_id}
3. Cómo construir la llamada
- Obtén el
document_idde la extracción original o de tu base de datos interna. - Sustituye
{document_id}en la URL por ese UUID. - Envía
DELETEcon tu API key enx-api-key(sin body).
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 se borró de documents. La respuesta solo incluye el document_id eliminado; no hay campo success. Si el borrado no fue posible, la petición termina en 404 antes de construir una respuesta de éxito.
{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b"
}6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Falta document_id en la URL o no tiene formato UUID válido.
401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta no activa.
404 — No se borró ninguna fila: el documento no existe, pertenece a otra cuenta o ya fue eliminado (por ejemplo, tras expirar). Mismo mensaje genérico por seguridad.
Ejemplo de 404:
{
"error": "No existe ningún documento con id 'd4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b'."
}405 — Método distinto de DELETE. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito — documento borrado | — |
| 400 | Error del cliente (document_id ausente o mal formado) | No, corrige la petición primero |
| 401 | Error de autenticación | No, corrige las credenciales primero |
| 404 | Documento no encontrado, ajeno o ya eliminado | No, corrige el document_id primero |
| 405 | Método HTTP incorrecto | No, usa DELETE |
| 500 | Error interno del servidor | Sí, con precaución |
8. Buenas prácticas
- Usa siempre el dominio público
claix.dev, no la URL directa de Supabase. - Elimina documentos cuando el usuario lo solicite o cuando ya no necesites conservar el contexto documental (RGPD, retención contractual, etc.).
- Si usas memoria persistente, combina este endpoint con tu política de borrado por tenant, caso o usuario.
- Tras el borrado,
GETyPOSTsobre/window-context/{document_id}devolverán 404. - No incluyas tu API key en frontend ni repositorios públicos.