Skip to content

Latest commit

 

History

History
876 lines (632 loc) · 16.2 KB

api-reference.md

File metadata and controls

876 lines (632 loc) · 16.2 KB

API Reference

Referencia completa de la API REST de Cortex Knowledge Assistant.

Base URL: http://localhost:8088 (desarrollo) | https://api.cortex.deeprat.tech (demo)

Autenticación

Cortex utiliza JWT Bearer tokens para autenticación. Todos los endpoints (excepto /health, /live, /ready, /auth/login) requieren autenticación.

Obtener Token

POST /auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your_password"
}

Respuesta (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": "1",
    "username": "admin",
    "user_type": "employee",
    "role": "admin",
    "dlp_level": "standard",
    "can_access_all_subjects": true,
    "subject_ids": []
  }
}

Usar Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Endpoints por Categoría

Health & Status

GET /health

Estado completo del sistema con todos los componentes.

Auth: No requerida

curl http://localhost:8088/health

Respuesta (200 OK):

{
  "status": "healthy",
  "timestamp": "2024-12-27T15:30:00Z",
  "components": {
    "database": { "healthy": true, "status": "connected" },
    "qdrant": { "healthy": true, "status": "connected", "documents": 1234 },
    "redis": { "healthy": true, "status": "connected" },
    "llm": {
      "healthy": true,
      "provider": "hf",
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}

GET /live

Probe de liveness para Kubernetes.

Auth: No requerida

curl http://localhost:8088/live

Respuesta (200 OK):

{
  "status": "alive",
  "timestamp": "2024-12-27T15:30:00Z"
}

GET /ready

Probe de readiness para Kubernetes.

Auth: No requerida

Respuesta (200 OK si listo, 503 si no):

{
  "ready": true,
  "timestamp": "2024-12-27T15:30:00Z",
  "checks": {
    "database": true,
    "qdrant": true,
    "llm": true
  }
}

GET /version

Información de versión y build.

Auth: No requerida

{
  "git_sha": "abc123def",
  "build_time": "2024-12-27T12:00:00Z",
  "app_version": "0.1.0-beta"
}

Authentication

POST /auth/login

Autenticar usuario y obtener JWT.

Request:

{
  "username": "string",
  "password": "string"
}

Respuesta (200 OK): Ver Obtener Token

Errores:

  • 401: Credenciales inválidas
  • 403: Usuario deshabilitado

POST /login

Alias de /auth/login para compatibilidad.

RAG Queries

POST /query

Realizar una consulta RAG con respuesta completa.

Auth: Bearer Token requerido

Request:

{
  "query": "¿Cuáles son los requisitos para abrir una cuenta?",
  "session_id": "optional-session-id",
  "subject_id": "CLI-81093",
  "context_type": "public_docs"
}
Campo Tipo Descripción
query string Requerido. Pregunta del usuario (máx 2000 chars)
session_id string Opcional. ID de sesión para memoria de conversación
subject_id string Opcional. ID del cliente para consultas personalizadas
context_type string Opcional. Filtro: public_docs, educational, o null

Respuesta (200 OK):

{
  "answer": "Para abrir una cuenta necesita presentar...",
  "used_chunks": ["chunk-id-1", "chunk-id-2", "chunk-id-3"],
  "session_id": "my-session-123",
  "citations": [
    { "id": "chunk-id-1", "source": "requisitos_cuenta.pdf" },
    { "id": "chunk-id-2", "source": "documentacion_general.pdf" }
  ]
}

Errores:

  • 401: No autenticado
  • 403: Sin permisos para el subject
  • 413: Query demasiado larga
  • 422: Query vacía
  • 429: Rate limited (incluye header Retry-After)

POST /query/stream

Consulta RAG con respuesta en streaming (SSE).

Auth: Bearer Token requerido

Request: Igual que /query

Respuesta: text/event-stream

data: {"token": "Para"}

data: {"token": " abrir"}

data: {"token": " una"}

data: {"token": " cuenta"}

...

data: {"done": true}

GET /chat/stream

Streaming simplificado (requiere CKA_ENABLE_STREAMING=true).

Query Params: q - la consulta

Subjects

GET /subjects

Listar subjects (clientes/entidades) accesibles para el usuario actual.

Auth: Bearer Token requerido

Respuesta (200 OK):

[
  {
    "subject_id": "CLI-81093",
    "subject_type": "person",
    "display_name": "Juan García",
    "status": "active"
  },
  {
    "subject_id": "CLI-81094",
    "subject_type": "person",
    "display_name": "María López",
    "status": "active"
  }
]

GET /subjects/{subject_id}

Detalle de un subject específico.

Auth: Bearer Token requerido

Respuesta (200 OK):

{
  "subject_id": "CLI-81093",
  "subject_type": "person",
  "display_name": "Juan García",
  "status": "active",
  "attributes": {
    "segment": "premium",
    "joined_date": "2020-01-15"
  }
}

GET /subjects/{subject_id}/services

Listar productos/servicios de un subject.

Auth: Bearer Token requerido

Respuesta (200 OK):

[
  {
    "service_type": "bank_account",
    "service_key": "ES1234567890123456789012",
    "display_name": "Cuenta Corriente",
    "status": "active",
    "metadata": { "currency": "EUR" }
  },
  {
    "service_type": "credit_card",
    "service_key": "****-****-****-1234",
    "display_name": "Visa Gold",
    "status": "active",
    "metadata": { "limit": 5000 }
  }
]

Transactional Data

GET /me/snapshot

Snapshot transaccional del usuario actual (solo customers).

Auth: Bearer Token requerido (user_type: customer)

Respuesta (200 OK):

{
  "subject_key": "CLI-81093",
  "products": [
    {
      "service_type": "bank_account",
      "service_key": "ES1234567890123456789012",
      "status": "active",
      "extra": { "balance": 15000.5 }
    }
  ],
  "recent_transactions": [
    {
      "timestamp": "2024-12-27T10:30:00Z",
      "transaction_type": "debit",
      "amount": -50.0,
      "currency": "EUR",
      "description": "Supermercado",
      "extra": null
    }
  ]
}

GET /customers/{subject_key}/snapshot

Snapshot de cualquier cliente (solo employees).

Auth: Bearer Token requerido (user_type: employee)

Admin - Users

Todos los endpoints de admin requieren user_type: employee y role: admin.

GET /api/admin/users

Listar todos los usuarios.

Query Params:

  • include_inactive (bool): Incluir usuarios deshabilitados
  • user_type (string): Filtrar por "customer" o "employee"

Respuesta (200 OK):

{
  "users": [
    {
      "id": 1,
      "username": "admin",
      "user_type": "employee",
      "role": "admin",
      "dlp_level": "standard",
      "status": "active",
      "can_access_all_subjects": true,
      "subject_ids": []
    }
  ],
  "total": 1
}

POST /api/admin/users

Crear nuevo usuario.

Request:

{
  "username": "nuevo_usuario",
  "password": "password_seguro_123",
  "user_type": "customer",
  "role": "user",
  "display_name": "Nuevo Usuario",
  "dlp_level": "standard",
  "can_access_all_subjects": false,
  "subject_ids": ["CLI-81095"],
  "full_name": "Nombre Completo",
  "document_id": "12345678A",
  "tax_id": "12345678A",
  "email": "usuario@ejemplo.com",
  "phone": "+34612345678"
}

GET /api/admin/users/{user_id}

Obtener usuario por ID.

PUT /api/admin/users/{user_id}

Actualizar usuario.

Request:

{
  "role": "admin",
  "dlp_level": "privileged",
  "status": "active",
  "can_access_all_subjects": true,
  "new_password": "nuevo_password_123"
}

DELETE /api/admin/users/{user_id}

Eliminar o desactivar usuario.

Query Params:

  • hard_delete (bool): Si true, elimina permanentemente. Default: false (soft delete)

Admin - Documents

POST /api/admin/upload-public-document

Subir documento para ingesta.

Auth: Bearer Token (admin)

Content-Type: multipart/form-data

Form Fields:

  • file: Archivo PDF, TXT o MD (máx 50MB)
  • category: public_docs o educational
curl -X POST http://localhost:8088/api/admin/upload-public-document \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@documento.pdf" \
  -F "category=public_docs"

Respuesta (200 OK):

{
  "success": true,
  "message": "Document uploaded and processed",
  "filename": "abc12345_documento.pdf",
  "file_size": 1234567,
  "file_hash": "sha256_hash_aquí",
  "audit_id": 42,
  "ingestion_status": "success",
  "documents_ingested": 15,
  "category": "public_docs"
}

POST /admin/refresh-public-docs

Re-ingestar todos los PDFs del directorio de documentación.

Auth: Bearer Token (admin)

Respuesta (200 OK):

{
  "status": "ok",
  "documents_ingested": 25
}

Admin - Products & Transactions

GET /api/admin/subjects

Listar todos los subjects con conteo de productos.

Respuesta (200 OK):

{
  "subjects": [
    {
      "id": 1,
      "subject_key": "CLI-81093",
      "subject_type": "person",
      "display_name": "Juan García",
      "status": "active",
      "product_count": 3
    }
  ],
  "total": 1
}

GET /api/admin/subjects/{subject_key}/products

Listar productos de un subject.

POST /api/admin/subjects/{subject_key}/products

Crear nuevo producto.

Request:

{
  "service_type": "bank_account",
  "service_key": "ES9876543210987654321098",
  "status": "active",
  "extra_metadata": { "currency": "EUR", "type": "savings" }
}

PUT /api/admin/products/{product_id}

Actualizar producto.

DELETE /api/admin/products/{product_id}

Eliminar producto (soft delete por defecto).

GET /api/admin/products/{product_id}/transactions

Listar transacciones de un producto.

Query Params:

  • limit (int): Máximo resultados (default: 50, max: 500)
  • offset (int): Offset para paginación
  • tx_type (string): Filtrar por tipo

POST /api/admin/products/{product_id}/transactions

Crear nueva transacción.

Request:

{
  "transaction_type": "credit",
  "amount": 1500.0,
  "currency": "EUR",
  "description": "Transferencia recibida",
  "extra_metadata": { "reference": "TRF-123456" }
}

PUT /api/admin/transactions/{transaction_id}

Actualizar transacción.

DELETE /api/admin/transactions/{transaction_id}

Eliminar transacción (hard delete).

Admin - Subject Data

GET /api/admin/subjects/{subject_key}/data

Obtener datos completos de un subject para edición.

Respuesta (200 OK):

{
  "subject_key": "CLI-81093",
  "subject_type": "person",
  "display_name": "Juan García",
  "status": "active",
  "full_name": "Juan García Pérez",
  "document_id": "12345678A",
  "tax_id": "12345678A",
  "email": "juan.garcia@ejemplo.com",
  "phone": "+34612345678",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-12-27T15:00:00Z"
}

PUT /api/admin/subjects/{subject_key}/data

Actualizar datos de subject con auditoría.

Request:

{
  "display_name": "Juan García Pérez",
  "email": "nuevo.email@ejemplo.com",
  "reason": "Actualización por solicitud del cliente vía ticket #12345"
}

Importante: El campo reason es obligatorio (mín 10 caracteres) para documentar el cambio.

GET /api/admin/subjects/{subject_key}/history

Historial de modificaciones de un subject.

Respuesta (200 OK):

[
  {
    "audit_id": 123,
    "timestamp": "2024-12-27T15:00:00Z",
    "operator_user_id": "1",
    "operator_username": "admin",
    "outcome": "success",
    "details": {
      "changes": ["email"],
      "reason": "Actualización por solicitud del cliente"
    }
  }
]

Admin - Audit Log

GET /admin/audit-log

Consultar log de auditoría.

Query Params:

  • user_id (string): Filtrar por usuario
  • subject_key (string): Filtrar por subject
  • operation (string): Filtrar por operación
  • limit (int): Máximo resultados (default: 200, max: 1000)

Respuesta (200 OK):

[
  {
    "id": 456,
    "user_id": "1",
    "username": "admin",
    "subject_key": "CLI-81093",
    "operation": "query",
    "outcome": "success",
    "details": { "duration_sec": 1.23 },
    "created_at": "2024-12-27T15:30:00Z"
  }
]

System Setup

GET /api/system/status

Estado del sistema para setup wizard.

Auth: No requerida (para first-run)

Query Params:

  • check_llm (bool): Verificar LLM (más lento)
  • include_errors (bool): Incluir mensajes de error detallados

Respuesta (200 OK):

{
  "database": {
    "connected": true,
    "first_run": false,
    "admin_exists": true
  },
  "qdrant": {
    "connected": true,
    "collection_exists": true,
    "document_count": 1234
  },
  "llm": {
    "configured": true,
    "provider": "hf"
  },
  "system": {
    "version": "0.1.0-beta"
  }
}

POST /api/setup/create-admin

Crear usuario admin inicial (solo disponible en first-run).

Auth: No requerida

Request:

{
  "username": "admin",
  "password": "password_seguro_minimo_12_caracteres",
  "display_name": "Administrador"
}

Errores:

  • 403: Ya existe un admin (first_run = false)
  • 422: Password no cumple requisitos

POST /api/system/init-qdrant

Inicializar colección de Qdrant.

Auth: Bearer Token (admin)

Demo Mode

GET /api/demo/status

Estado del modo demo (si está habilitado).

Auth: No requerida

Respuesta (200 OK):

{
  "demo_reset_enabled": true,
  "next_reset": "2024-12-27T16:00:00Z",
  "seconds_until_reset": 1800,
  "reset_interval_hours": 1
}

Metrics

GET /metrics

Métricas en formato Prometheus.

Auth: No requerida

Content-Type: text/plain

# HELP cortex_query_latency_seconds Query processing latency
# TYPE cortex_query_latency_seconds histogram
cortex_query_latency_seconds_bucket{le="0.1"} 10
cortex_query_latency_seconds_bucket{le="0.5"} 50
cortex_query_latency_seconds_bucket{le="1.0"} 95
cortex_query_latency_seconds_count 100
cortex_query_latency_seconds_sum 45.67

# HELP cortex_http_requests_total Total HTTP requests
# TYPE cortex_http_requests_total counter
cortex_http_requests_total{endpoint="/query",status_class="2xx"} 100
cortex_http_requests_total{endpoint="/query",status_class="4xx"} 5

Códigos de Error

Código Significado Acción Sugerida
400 Bad Request Verificar formato del request
401 Unauthorized Obtener nuevo token
403 Forbidden Verificar permisos del usuario
404 Not Found Verificar ID/path del recurso
409 Conflict Recurso ya existe
413 Payload Too Large Reducir tamaño del request
422 Unprocessable Entity Corregir datos de entrada
429 Too Many Requests Esperar según Retry-After header
500 Internal Server Error Reportar bug con request_id
503 Service Unavailable Reintentar después

Rate Limiting

  • Límite por defecto: 120 queries por minuto por usuario
  • Burst: Configurable vía CKA_RATE_LIMIT_BURST
  • Window: 60 segundos (configurable)

Cuando se excede el límite:

HTTP/1.1 429 Too Many Requests
Retry-After: 5

{"detail": "rate_limited"}

Headers de Seguridad

Todas las respuestas incluyen:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
X-Request-ID: abc123def456

Con CKA_HTTPS_ENABLED=true:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; ...

← Arquitectura • Configuración →