{ "components": { "securitySchemes": { "bearerAuth": { "bearerFormat": "JWT", "description": "Admite token Bearer o cookie gratia_access_token.", "scheme": "bearer", "type": "http" } } }, "info": { "title": "GratiaMesh API", "version": "dev" }, "openapi": "3.0.3", "paths": { "/api/v1/admin/autoscaling/events": { "get": { "description": "Lista auditoría de autoscaling_events (filtros target_type, dry_run).", "operationId": "listAutoscalingEvents", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista de eventos" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eventos del autoscaler interno", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs": { "get": { "description": "Lista jobs de gratia.background_jobs con filtros status, kind y búsqueda.", "operationId": "listBackgroundJobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Colección de jobs" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar background jobs", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/bulk/cancel": { "post": { "description": "Marca como failed los jobs pending/running indicados.", "operationId": "bulkCancelBackgroundJobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado bulk" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancelar background jobs (bulk)", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/bulk/cancel-filter": { "post": { "description": "Cancela todos los pending/running que coincidan con status, kind y búsqueda (como el listado admin).", "operationId": "cancelBackgroundJobsByFilter", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Número cancelados" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancelar jobs por filtro", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/bulk/delete": { "post": { "description": "Borra permanentemente jobs failed o completed indicados por id.", "operationId": "bulkDeleteBackgroundJobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado bulk" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar background jobs (bulk)", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/bulk/delete-filter": { "post": { "description": "Borra todos los failed/completed que coincidan con los filtros del listado.", "operationId": "deleteBackgroundJobsByFilter", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Número eliminados" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar jobs por filtro", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/bulk/retry": { "post": { "description": "Resetea a pending los jobs indicados (failed, completed o running).", "operationId": "bulkRetryBackgroundJobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado bulk" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reencolar background jobs (bulk)", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/kinds": { "get": { "description": "Lista kinds conocidos con flag paused y conteos en cola.", "operationId": "listBackgroundJobKinds", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista de kinds" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Políticas por tipo de job", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/kinds/{kind}": { "patch": { "description": "Cuando paused=true, el runner no reclama jobs de ese kind y los schedulers no encolan nuevos.", "operationId": "patchBackgroundJobKind", "parameters": [ { "description": "Nombre del job kind (ej. ReconcileBifrostJob)", "in": "path", "name": "kind", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Política actualizada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Pausar o reanudar un tipo de job", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/summary": { "get": { "description": "Conteos por estado (pending, running, failed, completed).", "operationId": "backgroundJobsSummary", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resumen" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Resumen cola background jobs", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/{id}": { "delete": { "description": "Solo completed o failed.", "operationId": "deleteBackgroundJob", "parameters": [ { "description": "Identificador numérico del background job", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Job eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar background job", "tags": [ "Admin" ] }, "get": { "operationId": "getBackgroundJob", "parameters": [ { "description": "Identificador numérico del background job", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del job" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Job no encontrado" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle background job", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/{id}/cancel": { "post": { "description": "Marca pending/running como failed.", "operationId": "cancelBackgroundJob", "parameters": [ { "description": "Identificador numérico del background job", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Job cancelado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancelar background job", "tags": [ "Admin" ] } }, "/api/v1/admin/background-jobs/{id}/retry": { "post": { "description": "Resetea el job a pending (failed, completed o running stale).", "operationId": "retryBackgroundJob", "parameters": [ { "description": "Identificador numérico del background job", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Job reencolado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reencolar background job", "tags": [ "Admin" ] } }, "/api/v1/admin/bifrost-breaker": { "get": { "operationId": "getBifrostBreakerConfig", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Breaker config" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Bifrost circuit breaker configuration", "tags": [ "Settings" ] }, "patch": { "operationId": "patchBifrostBreakerConfig", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "enabled, failure_threshold, open_timeout_seconds", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated breaker config" }, "400": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Invalid config" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update Bifrost circuit breaker configuration", "tags": [ "Settings" ] } }, "/api/v1/admin/config-export-schedules": { "get": { "operationId": "listConfigExportSchedules", "responses": { "200": { "description": "Lista" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar schedules de export", "tags": [ "Admin" ] }, "post": { "operationId": "createConfigExportSchedule", "responses": { "201": { "description": "Schedule creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear schedule de export", "tags": [ "Admin" ] } }, "/api/v1/admin/config-export-schedules/{id}": { "delete": { "operationId": "deleteConfigExportSchedule", "parameters": [ { "description": "UUID del config export schedule", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Borrado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Borrar schedule", "tags": [ "Admin" ] }, "get": { "operationId": "getConfigExportSchedule", "parameters": [ { "description": "UUID del config export schedule", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Schedule" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle de schedule", "tags": [ "Admin" ] }, "patch": { "operationId": "updateConfigExportSchedule", "parameters": [ { "description": "UUID del config export schedule", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Schedule" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar schedule", "tags": [ "Admin" ] } }, "/api/v1/admin/config-exports": { "get": { "operationId": "listConfigExports", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Historial" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar exports de configuración", "tags": [ "Admin" ] }, "post": { "description": "Scope selectivo de definiciones. Mode omit → job async; encrypted_payload → sync con passphrase (D10).", "operationId": "createConfigExport", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Export cifrado completado" }, "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Export encolado (omit)" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear export de configuración", "tags": [ "Admin" ] } }, "/api/v1/admin/config-exports/{id}": { "get": { "operationId": "getConfigExport", "parameters": [ { "description": "UUID del config export", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Export" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle de un export", "tags": [ "Admin" ] } }, "/api/v1/admin/config-exports/{id}/download": { "get": { "description": "Stream del blob en S3. Modo C: blob cifrado tal cual (sin descifrar en servidor).", "operationId": "downloadConfigExport", "parameters": [ { "description": "UUID del config export", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archivo" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Descargar artefacto de export", "tags": [ "Admin" ] } }, "/api/v1/admin/config-exports/{id}/remirror": { "post": { "operationId": "remirrorConfigExport", "parameters": [ { "description": "UUID del config export", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mirror actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reintentar mirror externo de un export", "tags": [ "Admin" ] } }, "/api/v1/admin/config-imports": { "get": { "operationId": "listConfigImports", "responses": { "200": { "description": "Historial" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar imports de configuración", "tags": [ "Admin" ] }, "post": { "description": "Upload multipart (file) o JSON con s3_key. dry_run=true → plan create/update/skip + detected_values; dry_run=false → merge apply. Passphrase solo en memoria (D10).", "operationId": "createConfigImport", "responses": { "200": { "description": "Dry-run o fallo con plan" }, "201": { "description": "Import aplicado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Importar bundle de configuración", "tags": [ "Admin" ] } }, "/api/v1/admin/config-imports/{id}": { "get": { "operationId": "getConfigImport", "parameters": [ { "description": "UUID del config import", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle de un import", "tags": [ "Admin" ] } }, "/api/v1/admin/observability/grafana": { "get": { "description": "Returns public URL and admin credentials from Helm Secret when observability is enabled. Password source: observability.grafana.adminPassword.", "operationId": "getGrafanaObservability", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Grafana access info" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Grafana admin access (bundled observability)", "tags": [ "Settings" ] } }, "/api/v1/admin/oidc/providers": { "get": { "operationId": "listOIDCProviders", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Providers" } }, "security": [ { "bearerAuth": [] } ], "summary": "List OIDC providers (admin)", "tags": [ "OIDC" ] }, "post": { "operationId": "createOIDCProvider", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create OIDC provider", "tags": [ "OIDC" ] } }, "/api/v1/admin/oidc/providers/{id}": { "delete": { "operationId": "deleteOIDCProvider", "parameters": [ { "description": "OIDC provider UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete OIDC provider", "tags": [ "OIDC" ] }, "get": { "operationId": "getOIDCProvider", "parameters": [ { "description": "OIDC provider UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Provider" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get OIDC provider", "tags": [ "OIDC" ] }, "put": { "operationId": "updateOIDCProvider", "parameters": [ { "description": "OIDC provider UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update OIDC provider", "tags": [ "OIDC" ] } }, "/api/v1/admin/oidc/providers/{id}/maps": { "get": { "operationId": "listOIDCMaps", "parameters": [ { "description": "OIDC provider UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Maps" } }, "security": [ { "bearerAuth": [] } ], "summary": "List IdP → RBAC maps", "tags": [ "OIDC" ] }, "put": { "operationId": "putOIDCMaps", "parameters": [ { "description": "OIDC provider UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Maps" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace IdP → RBAC maps", "tags": [ "OIDC" ] } }, "/api/v1/admin/oidc/providers/{id}/test": { "post": { "operationId": "testOIDCProvider", "parameters": [ { "description": "OIDC provider UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Discovery" } }, "security": [ { "bearerAuth": [] } ], "summary": "Test OIDC discovery for a saved provider", "tags": [ "OIDC" ] } }, "/api/v1/admin/oidc/status": { "get": { "operationId": "oidcStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Status" } }, "security": [ { "bearerAuth": [] } ], "summary": "SSO kill-switch and default redirect URI", "tags": [ "OIDC" ] } }, "/api/v1/admin/oidc/test": { "post": { "operationId": "testOIDCDiscovery", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Discovery" } }, "security": [ { "bearerAuth": [] } ], "summary": "Test OIDC discovery (issuer in body)", "tags": [ "OIDC" ] } }, "/api/v1/admin/runtime-config": { "get": { "operationId": "getRuntimeConfig", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Runtime config" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Global agent execution switch", "tags": [ "Settings" ] }, "patch": { "operationId": "patchRuntimeConfig", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "enabled boolean", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated runtime config" }, "400": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Invalid config" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update global agent execution switch", "tags": [ "Settings" ] } }, "/api/v1/agent-memories": { "get": { "responses": { "200": { "description": "Success" } }, "summary": "List shared agent memories", "tags": [ "Agent memories" ] }, "post": { "responses": { "200": { "description": "Success" } }, "summary": "Create shared agent memory", "tags": [ "Agent memories" ] } }, "/api/v1/agent-runs": { "get": { "description": "Devuelve las ejecuciones del usuario autenticado, paginadas y sin contenidos de entrada/salida.", "operationId": "listAgentRuns", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Ejecuciones del usuario" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar ejecuciones de agentes", "tags": [ "Agents" ] } }, "/api/v1/agent-runs/{id}": { "get": { "description": "Consulta el estado de un agent run encolado (pending/running/completed/failed).", "operationId": "getAgentRun", "parameters": [ { "description": "Identificador del agent run", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Estado del run" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Run inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Estado de ejecuci?n async", "tags": [ "Agents" ] } }, "/api/v1/agent-runs/{id}/trace": { "get": { "description": "Devuelve tools, knowledge hits y clasificaci?n de error de una ejecuci?n propia.", "operationId": "getAgentRunTrace", "parameters": [ { "description": "Identificador del agent run", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Traza del run" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Run de otro usuario" } }, "security": [ { "bearerAuth": [] } ], "summary": "Traza de ejecuci?n de agente", "tags": [ "Agents" ] } }, "/api/v1/agents": { "get": { "description": "Devuelve la lista paginada de agentes.", "operationId": "listAgents", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de agentes" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar agentes", "tags": [ "Agents" ] }, "post": { "description": "Crea un nuevo agente conversacional.", "operationId": "createAgent", "requestBody": { "content": { "application/json": { "schema": { "properties": { "agent_type": { "type": "string" }, "chat_memory_limit": { "format": "int32", "type": "integer" }, "context_policy": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "data_product_ids": { "items": { "type": "string" }, "type": "array" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "glossary_ids": { "items": { "type": "string" }, "type": "array" }, "indicator": { "type": "string" }, "knowledge_ids": { "items": { "type": "string" }, "type": "array" }, "llm_id": { "type": "string" }, "name": { "type": "string" }, "orchestration_config": { "properties": { "children": { "items": { "type": "string" }, "type": "array" }, "steps": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "reasoning_effort": { "type": "string" }, "require_rag_citation": { "properties": { "Set": { "type": "boolean" }, "Value": { "type": "boolean" } }, "type": "object" }, "run_budget": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "sponsor_id": { "type": "string" }, "system_prompt": { "type": "string" }, "temperature": { "format": "double", "type": "number" }, "token_quota": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "tool_group_ids": { "items": { "type": "string" }, "type": "array" }, "tool_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Definici?n del agente", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Agente creado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear agente", "tags": [ "Agents" ] } }, "/api/v1/agents/by-indicator/{indicator}": { "get": { "description": "Devuelve un agente buscado por su indicator (por ejemplo gratia-assistant).", "operationId": "getAgentByIndicator", "parameters": [ { "description": "Indicator del agente", "in": "path", "name": "indicator", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Agente" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "No existe" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener agente por indicator", "tags": [ "Agents" ] } }, "/api/v1/agents/estimate-cost": { "post": { "description": "Non-binding projection using the administrator-maintained app_settings.model_prices table; no provider price feed is implied.", "operationId": "estimateAgentCost", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Model, prompt and configured run/token caps", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Estimate or explicit unavailable-pricing result" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Estimate agent cost per run", "tags": [ "Agents" ] } }, "/api/v1/agents/sponsor-candidates": { "get": { "description": "Usuarios habilitados (id, email, nombre). No exige users.read.", "operationId": "listSponsorCandidates", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Candidatos" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Personas que pueden patrocinar un agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}": { "delete": { "description": "Elimina un agente.", "operationId": "deleteAgent", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Agente eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar agente", "tags": [ "Agents" ] }, "get": { "description": "Devuelve el detalle de un agente espec?fico.", "operationId": "getAgent", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del agente" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Agente inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener agente", "tags": [ "Agents" ] }, "put": { "description": "Modifica la configuraci?n de un agente existente.", "operationId": "updateAgent", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agent_type": { "type": "string" }, "chat_memory_limit": { "format": "int32", "type": "integer" }, "context_policy": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "data_product_ids": { "items": { "type": "string" }, "type": "array" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "glossary_ids": { "items": { "type": "string" }, "type": "array" }, "knowledge_ids": { "items": { "type": "string" }, "type": "array" }, "llm_id": { "type": "string" }, "name": { "type": "string" }, "orchestration_config": { "properties": { "children": { "items": { "type": "string" }, "type": "array" }, "steps": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "pii_policy": { "type": "string" }, "reasoning_effort": { "type": "string" }, "require_rag_citation": { "properties": { "Set": { "type": "boolean" }, "Value": { "type": "boolean" } }, "type": "object" }, "run_budget": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "system_prompt": { "type": "string" }, "temperature": { "format": "double", "type": "number" }, "token_quota": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "tool_group_ids": { "items": { "type": "string" }, "type": "array" }, "tool_hitl_mutating": { "type": "boolean" }, "tool_ids": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Payload completo del agente", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Agente actualizado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/draft": { "delete": { "description": "Elimina el draft pendiente (vuelve a == live).", "operationId": "discardAgentDraft", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Draft descartado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Descartar draft del agente", "tags": [ "Agents" ] }, "put": { "description": "Guarda un draft pendiente sobre la fila del agente sin tocar el live.", "operationId": "saveAgentDraft", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Snapshot del draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Draft guardado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Guardar draft del agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/publish": { "post": { "description": "Aplica el draft pendiente al live y crea la siguiente versión. Respeta el hard gate de eval (409) salvo force=true.", "operationId": "publishAgent", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Notas y force (opcionales)" }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Versión publicada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sin draft o hard gate de eval" } }, "security": [ { "bearerAuth": [] } ], "summary": "Publicar draft del agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/run": { "post": { "description": "Ejecuta un turno del agente con memoria, tools y posible delegaci?n a sub-agentes. Con async=true devuelve 202 y run_id.", "operationId": "runAgent", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Mensaje del usuario y sesi?n", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Respuesta del agente" }, "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Ejecuci?n async encolada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Ejecutar agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/sponsor": { "post": { "description": "Nombra a la persona accountable. No vuelve a activar un agente huérfano.", "operationId": "setAgentSponsor", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Agente" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cambiar el sponsor del agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/tools": { "get": { "description": "Devuelve las herramientas asignadas a un agente.", "operationId": "getAgentTools", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Tools del agente" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar tools de agente", "tags": [ "Agents" ] }, "put": { "description": "Establece la lista de herramientas que un agente puede utilizar.", "operationId": "setAgentTools", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Lista de IDs de tools", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Tools asignadas" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Asignar tools a agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/versions": { "get": { "description": "Lista las versiones de configuración (newest-first) con agregados de eval por versión.", "operationId": "listAgentVersions", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Versiones + estado draft" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Agente inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Historial de versiones del agente", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/versions/{versionNumber}": { "get": { "description": "Devuelve el config_snapshot completo de una versión.", "operationId": "getAgentVersion", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Número de versión del agente", "in": "path", "name": "versionNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Versión con snapshot" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Versión inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle de una versión", "tags": [ "Agents" ] } }, "/api/v1/agents/{id}/versions/{versionNumber}/restore": { "post": { "description": "Aplica una versión previa al live creando una versión nueva (1-click rollback, no destructivo).", "operationId": "restoreAgentVersion", "parameters": [ { "description": "Identificador del agente", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Número de versión del agente", "in": "path", "name": "versionNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Notas y force (opcionales)" }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Versión restaurada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Ya está en live o hard gate de eval" } }, "security": [ { "bearerAuth": [] } ], "summary": "Restaurar versión del agente", "tags": [ "Agents" ] } }, "/api/v1/alerts/channel/test": { "post": { "operationId": "testAlertChannel", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Optional to email" }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sent" }, "400": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "SMTP error" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Test SMTP alert channel", "tags": [ "Alerts" ] } }, "/api/v1/alerts/firings": { "get": { "operationId": "listAlertFirings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Firings" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List alert firings", "tags": [ "Alerts" ] } }, "/api/v1/alerts/firings/bulk/delete": { "post": { "description": "Delete up to 200 firings by id (inbox cleanup).", "operationId": "bulkDeleteAlertFirings", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "ids[]", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Deleted count" }, "400": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Invalid body" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Bulk delete alert firings", "tags": [ "Alerts" ] } }, "/api/v1/alerts/firings/{id}": { "get": { "operationId": "getAlertFiring", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Firing" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get alert firing", "tags": [ "Alerts" ] } }, "/api/v1/alerts/resources/{resourceType}/{resourceId}/firings": { "get": { "operationId": "listAlertFiringsForResource", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Firings" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List firings for resource", "tags": [ "Alerts" ] } }, "/api/v1/alerts/rules": { "get": { "description": "Fixed system alert rules with current config + defaults (read-only; edit via PATCH /app-settings alert_rules).", "operationId": "getAlertsRules", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Rules" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Alert rules catalog", "tags": [ "Alerts" ] } }, "/api/v1/alerts/status": { "get": { "description": "SMTP configured flag and firing counts (24h).", "operationId": "getAlertsStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Status" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Alert channel status", "tags": [ "Alerts" ] } }, "/api/v1/app-settings": { "get": { "description": "Ajustes globales (solo admin).", "operationId": "getAppSettings", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Settings" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Configuraci?n de aplicaci?n", "tags": [ "Settings" ] }, "patch": { "description": "Parcial: nombre, log level, concurrencia, chunks, rate limit (solo admin).", "operationId": "patchAppSettings", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Campos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Settings actualizados" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar configuraci?n", "tags": [ "Settings" ] } }, "/api/v1/app-settings/branding/avatar": { "delete": { "operationId": "deleteBrandingAvatar", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Avatar eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar avatar de sistema", "tags": [ "Settings" ] }, "post": { "description": "PNG/JPEG/GIF/WebP, m?x. 2 MB (solo admin).", "operationId": "postBrandingAvatar", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Settings con avatar" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Subir avatar de sistema", "tags": [ "Settings" ] } }, "/api/v1/app-settings/extraction-capabilities": { "get": { "description": "Modo global, max_bytes, alcanzabilidad de Tika y tipos MIME soportados por modo.", "operationId": "getExtractionCapabilities", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Capacidades de extracción" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Capacidades de extracción", "tags": [ "Settings" ] } }, "/api/v1/app-settings/hnsw-rebuild": { "post": { "description": "Encola un job que crea los índices parciales de chunk_embeddings con m y ef_construction de Settings.", "operationId": "rebuildHnswIndex", "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Job encolado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reconstruir índice HNSW", "tags": [ "Settings" ] } }, "/api/v1/app-settings/model-prices": { "get": { "description": "Administrator-maintained USD per million token rates; no provider synchronization is performed.", "operationId": "getModelPrices", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Configured exact model-name price map" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Read model price table", "tags": [ "Settings" ] }, "put": { "description": "Rates are USD per million tokens and must be supplied/updated explicitly by an administrator.", "operationId": "putModelPrices", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Map from exact llms.model_name values to input/output USD per million tokens", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated price table" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace model price table", "tags": [ "Settings" ] } }, "/api/v1/audit-events": { "get": { "description": "Eventos de mutación (quién cambió qué). Filtros: resource_type, resource_id, action, actor_email, limit.", "operationId": "listAuditEvents", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Eventos" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar auditoría de plataforma", "tags": [ "Admin" ] } }, "/api/v1/audit-events/export": { "get": { "description": "Descarga CSV o NDJSON (format=csv|ndjson, mismos filtros que el listado, límite 5000).", "operationId": "exportAuditEvents", "responses": { "200": { "description": "Archivo" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Exportar auditoría", "tags": [ "Admin" ] } }, "/api/v1/auth/api-key/regenerate": { "post": { "description": "Invalidates existing user API keys and returns a new sl_* key (shown once).", "operationId": "regenerateMyAPIKey", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Nueva API key" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Regenerate own API key", "tags": [ "Auth" ] } }, "/api/v1/auth/login": { "post": { "description": "Autenticaci?n de usuario y emisi?n de tokens.", "operationId": "loginUser", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" } }, "type": "object" } } }, "description": "Credenciales de acceso", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "user": { "properties": { "authMethod": { "type": "string" }, "createdAt": { "properties": { "InfinityModifier": { "maximum": 127, "minimum": -128, "type": "integer" }, "Time": { "format": "date-time", "type": "string" }, "Valid": { "type": "boolean" } }, "type": "object" }, "email": { "type": "string" }, "enabled": { "type": "boolean" }, "id": {}, "name": { "type": "string" }, "passwordHash": { "type": "string" }, "preferences": { "format": "byte", "type": "string" }, "role": { "type": "string" }, "tokenQuota": { "format": "byte", "type": "string" }, "updatedAt": { "properties": { "InfinityModifier": { "maximum": 127, "minimum": -128, "type": "integer" }, "Time": { "format": "date-time", "type": "string" }, "Valid": { "type": "boolean" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "Sesi?n iniciada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Credenciales inv?lidas" } }, "summary": "Login", "tags": [ "Auth" ] } }, "/api/v1/auth/logout": { "post": { "description": "Revoca la cookie de autenticaci?n actual.", "operationId": "logoutUser", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sesi?n cerrada" } }, "summary": "Logout", "tags": [ "Auth" ] } }, "/api/v1/auth/me": { "get": { "description": "Devuelve los datos del usuario autenticado.", "operationId": "getCurrentUser", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos del usuario" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Usuario autenticado", "tags": [ "Auth" ] } }, "/api/v1/auth/oidc/callback": { "get": { "description": "Exchanges code+PKCE, provisions or links the user, sets the Gratia session cookie.", "operationId": "callbackOIDC", "responses": { "302": { "description": "Redirect to /v2 or /app" } }, "summary": "OIDC callback", "tags": [ "Auth" ] } }, "/api/v1/auth/oidc/clear-hint": { "post": { "operationId": "clearOIDCHint", "responses": { "204": { "description": "Hint cleared" } }, "summary": "Clear last-IdP hint cookie", "tags": [ "Auth" ] } }, "/api/v1/auth/oidc/providers": { "get": { "description": "Public: id, name, display_name, is_default, sort_order, email_domains for login buttons.", "operationId": "listPublicOIDCProviders", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Enabled providers" } }, "summary": "List enabled SSO providers", "tags": [ "Auth" ] } }, "/api/v1/auth/oidc/resume": { "get": { "operationId": "resumeOIDC", "responses": { "302": { "description": "Redirect to IdP or login" } }, "summary": "Silent SSO resume from hint cookie", "tags": [ "Auth" ] } }, "/api/v1/auth/oidc/start": { "get": { "description": "302 to the IdP authorize endpoint.", "operationId": "startOIDC", "responses": { "302": { "description": "Redirect to IdP" } }, "summary": "Start OIDC Authorization Code + PKCE", "tags": [ "Auth" ] } }, "/api/v1/auth/refresh": { "post": { "description": "Exchanges a refresh JWT for a new access token and rotated refresh token.", "operationId": "refreshToken", "requestBody": { "content": { "application/json": { "schema": { "properties": { "refresh_token": { "type": "string" } }, "type": "object" } } }, "description": "Refresh token", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "user": { "properties": { "authMethod": { "type": "string" }, "createdAt": { "properties": { "InfinityModifier": { "maximum": 127, "minimum": -128, "type": "integer" }, "Time": { "format": "date-time", "type": "string" }, "Valid": { "type": "boolean" } }, "type": "object" }, "email": { "type": "string" }, "enabled": { "type": "boolean" }, "id": {}, "name": { "type": "string" }, "passwordHash": { "type": "string" }, "preferences": { "format": "byte", "type": "string" }, "role": { "type": "string" }, "tokenQuota": { "format": "byte", "type": "string" }, "updatedAt": { "properties": { "InfinityModifier": { "maximum": 127, "minimum": -128, "type": "integer" }, "Time": { "format": "date-time", "type": "string" }, "Valid": { "type": "boolean" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "Tokens renovados" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Refresh inválido" } }, "summary": "Refresh access token", "tags": [ "Auth" ] } }, "/api/v1/auth/register": { "post": { "description": "Crea un usuario (solo admin autenticado; no hay self-signup público).", "operationId": "registerUser", "requestBody": { "content": { "application/json": { "schema": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" } }, "type": "object" } } }, "description": "Credenciales y datos opcionales", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "user": { "properties": { "authMethod": { "type": "string" }, "createdAt": { "properties": { "InfinityModifier": { "maximum": 127, "minimum": -128, "type": "integer" }, "Time": { "format": "date-time", "type": "string" }, "Valid": { "type": "boolean" } }, "type": "object" }, "email": { "type": "string" }, "enabled": { "type": "boolean" }, "id": {}, "name": { "type": "string" }, "passwordHash": { "type": "string" }, "preferences": { "format": "byte", "type": "string" }, "role": { "type": "string" }, "tokenQuota": { "format": "byte", "type": "string" }, "updatedAt": { "properties": { "InfinityModifier": { "maximum": 127, "minimum": -128, "type": "integer" }, "Time": { "format": "date-time", "type": "string" }, "Valid": { "type": "boolean" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "Usuario registrado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Usuario existente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Registrar usuario", "tags": [ "Auth" ] } }, "/api/v1/branding": { "get": { "description": "Nombre de aplicaci?n y URL de avatar para login y shell (sin autenticaci?n).", "operationId": "getBrandingPublic", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Branding" } }, "summary": "Branding p?blico", "tags": [ "Branding" ] } }, "/api/v1/branding/avatar": { "get": { "description": "Imagen de marca (PNG/JPEG/GIF/WebP) sin autenticaci?n.", "operationId": "getBrandingAvatar", "responses": { "200": { "description": "Bytes de imagen" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sin avatar" } }, "summary": "Avatar de sistema", "tags": [ "Branding" ] } }, "/api/v1/chat/my-documents": { "get": { "description": "Lists the authenticated user's personal documents.", "operationId": "listMyDocuments", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Document collection" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "List personal documents", "tags": [ "Chat" ] }, "post": { "description": "Uploads a document to the authenticated user's personal RAG corpus (Mis Documentos).", "operationId": "uploadMyDocument", "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Queued for ingest" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Upload personal document", "tags": [ "Chat" ] } }, "/api/v1/chat/my-documents/{id}": { "delete": { "description": "Deletes the authenticated user's personal document (row + object storage).", "operationId": "deleteMyDocument", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Deleted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete personal document", "tags": [ "Chat" ] } }, "/api/v1/chat/my-documents/{id}/file": { "get": { "description": "Streams a personal document (inline preview for images/PDF; ?download=1 forces a download).", "operationId": "getMyDocumentFile", "parameters": [ { "description": "Personal document identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File stream" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Download/preview personal document", "tags": [ "Chat" ] } }, "/api/v1/chat/sessions": { "get": { "description": "Returns chat sessions for the authenticated user (end-user UI).", "operationId": "listChatSessions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Session collection" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "List chat sessions", "tags": [ "Chat" ] }, "post": { "description": "Starts a new conversation with an agent or LLM (end-user UI).", "operationId": "createChatSession", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "agent_id or llm_id and optional title", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create chat session", "tags": [ "Chat" ] } }, "/api/v1/chat/sessions/{id}": { "delete": { "description": "Deletes a chat session and its messages (end-user UI).", "operationId": "deleteChatSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete chat session", "tags": [ "Chat" ] }, "get": { "description": "Returns a chat session (end-user UI).", "operationId": "getChatSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Session detail" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get chat session", "tags": [ "Chat" ] }, "patch": { "description": "Updates a chat session title (end-user UI).", "operationId": "patchChatSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Updated" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update chat session", "tags": [ "Chat" ] } }, "/api/v1/chat/sessions/{id}/messages": { "get": { "description": "Returns enriched messages for a chat session (end-user UI).", "operationId": "listChatMessages", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Messages" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "List chat messages", "tags": [ "Chat" ] } }, "/api/v1/chat/sessions/{id}/messages/{msgId}": { "patch": { "description": "Rewrites a message's content (edit-and-regenerate, end-user UI).", "operationId": "updateChatMessage", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated message" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update chat message", "tags": [ "Chat" ] } }, "/api/v1/chat/sessions/{id}/truncate": { "post": { "description": "Deletes all messages after a user message to fork/regenerate a conversation (end-user UI).", "operationId": "truncateChatMessages", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Truncated" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Truncate chat messages", "tags": [ "Chat" ] } }, "/api/v1/dashboard/stats": { "get": { "description": "Estad?sticas agregadas de la plataforma.", "operationId": "getDashboardStats", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Estad?sticas" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "KPIs del dashboard", "tags": [ "Dashboard" ] } }, "/api/v1/data-agents": { "get": { "description": "Devuelve la lista de data agents (configuraciones de datos consultables).", "operationId": "listDataAgents", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colección de data agents" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar data agents", "tags": [ "Data Agents" ] }, "post": { "description": "Crea un nuevo data agent. El indicator se deriva del name si se omite.", "operationId": "createDataAgent", "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "type": "string" }, "enabled": { "type": "boolean" }, "indicator": { "type": "string" }, "llmId": {}, "name": { "type": "string" }, "sourceConfig": {}, "sourceType": { "type": "string" }, "sqlValidatorConfig": {} }, "type": "object" } } }, "description": "Datos del data agent", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Data agent creado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Body inválido" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear data agent", "tags": [ "Data Agents" ] } }, "/api/v1/data-agents/{id}": { "delete": { "description": "Elimina un data agent y todas sus invocaciones.", "operationId": "deleteDataAgent", "parameters": [ { "description": "Identificador del data agent", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Data agent eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar data agent", "tags": [ "Data Agents" ] }, "get": { "description": "Devuelve el detalle de un data agent, incluyendo su schema detectado.", "operationId": "getDataAgent", "parameters": [ { "description": "Identificador del data agent", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del data agent" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Data agent inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener data agent", "tags": [ "Data Agents" ] }, "put": { "description": "Modifica un data agent existente.", "operationId": "updateDataAgent", "parameters": [ { "description": "Identificador del data agent", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "type": "string" }, "enabled": { "type": "boolean" }, "indicator": { "type": "string" }, "llmId": {}, "name": { "type": "string" }, "sourceConfig": {}, "sourceType": { "type": "string" }, "sqlValidatorConfig": {} }, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Data agent actualizado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Body inválido" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar data agent", "tags": [ "Data Agents" ] } }, "/api/v1/data-agents/{id}/ask": { "post": { "description": "Envía una pregunta en lenguaje natural y recibe filas + SQL generado. Solo en pods con el registry cargado.", "operationId": "askDataAgent", "parameters": [ { "description": "Identificador del data agent", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "question": { "type": "string" } }, "type": "object" } } }, "description": "Pregunta", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Respuesta con SQL + filas" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Data agent no cargado en este pod" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Registry no disponible en este pod" } }, "security": [ { "bearerAuth": [] } ], "summary": "Preguntar al data agent", "tags": [ "Data Agents" ] } }, "/api/v1/data-agents/{id}/invocations": { "get": { "description": "Devuelve las últimas invocaciones de un data agent (audit + métricas).", "operationId": "listDataAgentInvocations", "parameters": [ { "description": "Identificador del data agent", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colección de invocaciones" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar invocaciones", "tags": [ "Data Agents" ] } }, "/api/v1/data-retrievers": { "get": { "description": "Devuelve la lista de configuraciones de ingesta de datos.", "operationId": "listDataRetrievers", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de data retrievers" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar data retrievers", "tags": [ "Data Retrievers" ] }, "post": { "description": "Crea una nueva configuraci?n de ingesta vinculada a un datasource y knowledge.", "operationId": "createDataRetriever", "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_columns": {}, "cron_expression": { "type": "string" }, "datasource_id": {}, "enabled": { "type": "boolean" }, "file_pattern": { "type": "string" }, "folder_path": { "type": "string" }, "incremental": { "type": "boolean" }, "incremental_sql_query": { "type": "string" }, "knowledge_id": {}, "name": { "type": "string" }, "recursive": { "type": "boolean" }, "sql_query": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "description": "Configuraci?n del retriever", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Retriever creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear data retriever", "tags": [ "Data Retrievers" ] } }, "/api/v1/data-retrievers/{id}": { "delete": { "description": "Elimina una configuraci?n de ingesta.", "operationId": "deleteDataRetriever", "parameters": [ { "description": "Identificador del data retriever", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Retriever eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar data retriever", "tags": [ "Data Retrievers" ] }, "get": { "description": "Devuelve el detalle de un data retriever.", "operationId": "getDataRetriever", "parameters": [ { "description": "Identificador del data retriever", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del retriever" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Retriever inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener data retriever", "tags": [ "Data Retrievers" ] }, "put": { "description": "Modifica una configuraci?n de ingesta existente.", "operationId": "updateDataRetriever", "parameters": [ { "description": "Identificador del data retriever", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content_columns": {}, "cron_expression": { "type": "string" }, "datasource_id": {}, "enabled": { "type": "boolean" }, "file_pattern": { "type": "string" }, "folder_path": { "type": "string" }, "incremental": { "type": "boolean" }, "incremental_sql_query": { "type": "string" }, "knowledge_id": {}, "name": { "type": "string" }, "recursive": { "type": "boolean" }, "sql_query": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Retriever actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar data retriever", "tags": [ "Data Retrievers" ] } }, "/api/v1/data-retrievers/{id}/sync": { "post": { "description": "Encola un trabajo de ingesta para el retriever especificado.", "operationId": "syncDataRetriever", "parameters": [ { "description": "Identificador del data retriever", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sincronizaci?n encolada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Sincronizar data retriever", "tags": [ "Data Retrievers" ] } }, "/api/v1/datasources": { "get": { "description": "Devuelve la lista de datasources.", "operationId": "listDatasources", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de datasources" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar datasources", "tags": [ "Datasources" ] }, "post": { "description": "Crea un nuevo datasource.", "operationId": "createDatasource", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos del datasource", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datasource creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear datasource", "tags": [ "Datasources" ] } }, "/api/v1/datasources/{id}": { "delete": { "description": "Elimina un datasource.", "operationId": "deleteDatasource", "parameters": [ { "description": "Identificador del datasource", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Datasource eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar datasource", "tags": [ "Datasources" ] }, "get": { "description": "Devuelve el detalle de un datasource.", "operationId": "getDatasource", "parameters": [ { "description": "Identificador del datasource", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle de datasource" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Datasource inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener datasource", "tags": [ "Datasources" ] }, "put": { "description": "Modifica un datasource existente.", "operationId": "updateDatasource", "parameters": [ { "description": "Identificador del datasource", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datasource actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar datasource", "tags": [ "Datasources" ] } }, "/api/v1/datasources/{id}/probe": { "post": { "description": "Verifica conectividad del datasource.", "operationId": "probeDatasource", "parameters": [ { "description": "Identificador del datasource", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado del probe" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Probar datasource", "tags": [ "Datasources" ] } }, "/api/v1/eval/datasets": { "get": { "description": "Admin evaluation datasets (versioned Q\u0026A corpora).", "operationId": "listEvalDatasets", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Dataset list" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List eval datasets", "tags": [ "Evaluation" ] }, "post": { "description": "Creates an empty logical dataset; publish versions via POST .../versions.", "operationId": "createEvalDataset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "name + description", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create eval dataset", "tags": [ "Evaluation" ] } }, "/api/v1/eval/datasets/template": { "get": { "description": "Canonical CSV or JSONL template with query, expected_answer, expected_behavior columns.", "operationId": "downloadEvalDatasetTemplate", "responses": { "200": { "description": "Template file" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Invalid format" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Download eval dataset import template", "tags": [ "Evaluation" ] } }, "/api/v1/eval/datasets/{id}": { "delete": { "description": "Cascades versions and rows.", "operationId": "deleteEvalDataset", "parameters": [ { "description": "Eval dataset UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete eval dataset", "tags": [ "Evaluation" ] }, "get": { "description": "Dataset metadata plus published versions.", "operationId": "getEvalDataset", "parameters": [ { "description": "Eval dataset UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Dataset + versions" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get eval dataset", "tags": [ "Evaluation" ] }, "patch": { "operationId": "updateEvalDataset", "parameters": [ { "description": "Eval dataset UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Partial name/description", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update eval dataset metadata", "tags": [ "Evaluation" ] } }, "/api/v1/eval/datasets/{id}/versions": { "post": { "description": "Import JSON/JSONL/CSV cases into an immutable version (max 5000 rows).", "operationId": "publishEvalDatasetVersion", "parameters": [ { "description": "Eval dataset UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "JSON {rows} or JSONL/CSV body/multipart file", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Version published" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Publish eval dataset version", "tags": [ "Evaluation" ] } }, "/api/v1/eval/datasets/{id}/versions/{vid}/export": { "get": { "description": "Download all cases for a published version as CSV or JSONL (format=csv|jsonl).", "operationId": "exportEvalDatasetVersion", "parameters": [ { "description": "Eval dataset UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Eval dataset version UUID", "in": "path", "name": "vid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV or JSONL file" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Invalid format" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Export eval dataset version", "tags": [ "Evaluation" ] } }, "/api/v1/eval/datasets/{id}/versions/{vid}/rows": { "get": { "description": "Paginated immutable cases for a published version.", "operationId": "listEvalDatasetRows", "parameters": [ { "description": "Eval dataset UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Eval dataset version UUID", "in": "path", "name": "vid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Rows page" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List eval dataset rows", "tags": [ "Evaluation" ] } }, "/api/v1/eval/judges": { "get": { "description": "Built-in judge kinds including llm_custom with config.system_prompt.", "operationId": "listEvalJudges", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Judge catalog" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List eval judge catalog", "tags": [ "Evaluation" ] } }, "/api/v1/eval/prompt-accept-history": { "get": { "description": "Audit trail of prompts promoted via prompt-improve Accept. Filter by suite_id, agent_id, or improve_job_id.", "operationId": "listEvalPromptAcceptHistory", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "History page" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List prompt accept history", "tags": [ "Evaluation" ] } }, "/api/v1/eval/prompt-improve": { "get": { "description": "Optional filters: suite_id, status.", "operationId": "listEvalPromptImproveJobs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Job list" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List prompt-improve jobs", "tags": [ "Evaluation" ] } }, "/api/v1/eval/prompt-improve/{id}": { "get": { "operationId": "getEvalPromptImproveJob", "parameters": [ { "description": "Prompt improve job UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Job detail" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get prompt-improve job", "tags": [ "Evaluation" ] } }, "/api/v1/eval/prompt-improve/{id}/accept": { "post": { "description": "Applies best_prompt (or optional prompt / cycle_index) to the suite target. Respects eval hard gate against the candidate run; pass force=true to override (audited).", "operationId": "acceptEvalPromptImproveJob", "parameters": [ { "description": "Prompt improve job UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "optional prompt, cycle_index, force" }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Prompt applied" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" }, "409": { "description": "Not acceptable or eval_hard_gate" } }, "security": [ { "bearerAuth": [] } ], "summary": "Accept prompt-improve candidate", "tags": [ "Evaluation" ] } }, "/api/v1/eval/prompt-improve/{id}/cancel": { "post": { "operationId": "cancelEvalPromptImproveJob", "parameters": [ { "description": "Prompt improve job UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Cancelled" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" }, "409": { "description": "Not cancellable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel prompt-improve job", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs": { "get": { "description": "Optional filters: suite_id, status.", "operationId": "listEvalRuns", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Run list" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List eval runs", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs/{id}": { "get": { "operationId": "getEvalRun", "parameters": [ { "description": "Eval run UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Run" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get eval run", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs/{id}/cancel": { "post": { "description": "Cancels a pending or running eval run. Worker stops between cases; partial results remain visible.", "operationId": "cancelEvalRun", "parameters": [ { "description": "Eval run UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Run cancelled" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" }, "409": { "description": "Run not cancellable" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel eval run", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs/{id}/compare": { "post": { "description": "Recomputes comparison against an explicit baseline run (same suite + dataset version).", "operationId": "compareEvalRun", "parameters": [ { "description": "Eval run UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "baseline_run_id", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated run with comparison" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Compare eval run to baseline", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs/{id}/progress": { "get": { "description": "Live progress: results_count, passed/failed vs dataset_row_count while run is pending or running.", "operationId": "getEvalRunProgress", "parameters": [ { "description": "Eval run UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Run progress" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get eval run progress", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs/{id}/report.pdf": { "get": { "description": "Exports a single-page PDF summary (status, pass rate, comparison, sample cases).", "operationId": "exportEvalRunReportPDF", "parameters": [ { "description": "Eval run UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "application/pdf" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" }, "404": { "description": "Run not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Download eval run PDF report", "tags": [ "Evaluation" ] } }, "/api/v1/eval/runs/{id}/results": { "get": { "operationId": "listEvalRunResults", "parameters": [ { "description": "Eval run UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Per-case results" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List eval run results", "tags": [ "Evaluation" ] } }, "/api/v1/eval/suites": { "get": { "operationId": "listEvalSuites", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Suite list" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "List eval suites", "tags": [ "Evaluation" ] }, "post": { "description": "Agent or LLM target + dataset pin + judges/budgets/thresholds.", "operationId": "createEvalSuite", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Suite config", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create eval suite", "tags": [ "Evaluation" ] } }, "/api/v1/eval/suites/{id}": { "delete": { "operationId": "deleteEvalSuite", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete eval suite", "tags": [ "Evaluation" ] }, "get": { "operationId": "getEvalSuite", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Suite" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get eval suite", "tags": [ "Evaluation" ] }, "patch": { "operationId": "updateEvalSuite", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Suite config", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update eval suite", "tags": [ "Evaluation" ] } }, "/api/v1/eval/suites/{id}/agents/{agentID}": { "delete": { "operationId": "unlinkAgentEvalSuite", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Agent UUID", "in": "path", "name": "agentID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Unlinked" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Unlink agent from eval suite", "tags": [ "Evaluation" ] }, "put": { "description": "Sets agents.eval_suite_id for soft regression gating.", "operationId": "linkAgentEvalSuite", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Agent UUID", "in": "path", "name": "agentID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Linked" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Link agent to eval suite", "tags": [ "Evaluation" ] } }, "/api/v1/eval/suites/{id}/prompt-improve": { "post": { "description": "Eval-driven system prompt research cycles. Does not mutate the agent; best_prompt is advisory. Optional max_cycles (1–8) and researcher_llm_id.", "operationId": "startEvalPromptImprove", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "max_cycles, researcher_llm_id" }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Improve job accepted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Start prompt auto-improve job", "tags": [ "Evaluation" ] } }, "/api/v1/eval/suites/{id}/run": { "post": { "description": "Creates a pending eval run and enqueues EvalRunJob (agent target, ephemeral agentrun per case).", "operationId": "startEvalSuiteRun", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Run accepted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Start eval suite run", "tags": [ "Evaluation" ] } }, "/api/v1/eval/suites/{id}/schedule": { "post": { "description": "Sets schedule_enabled + schedule_cron preset (1d|2d|3d|7d|14d|30d) and next_run_at.", "operationId": "scheduleEvalSuite", "parameters": [ { "description": "Eval suite UUID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "enabled + schedule_cron", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Suite schedule updated" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Enable or disable eval suite schedule", "tags": [ "Evaluation" ] } }, "/api/v1/hitl-requests": { "get": { "description": "Llamadas a tools en pausa porque el agente tiene tool_hitl activo.", "operationId": "listPendingHITL", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Pendientes" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Aprobaciones de tools pendientes", "tags": [ "Admin" ] } }, "/api/v1/hitl-requests/{id}": { "post": { "description": "Body {decision: approve|reject}. El run que espera continúa o recibe error.", "operationId": "decideHITL", "parameters": [ { "description": "UUID de la solicitud HITL", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Decisión aplicada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "description": "Ya no está pendiente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Aprobar o rechazar una tool", "tags": [ "Admin" ] } }, "/api/v1/hooks/{id}": { "post": { "description": "Verifica firma Gratia, registra delivery e encola agent run async. Responde 202.", "operationId": "inboundWebhook", "parameters": [ { "description": "UUID del webhook trigger", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Delivery accepted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Firma inválida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Trigger no encontrado" } }, "summary": "Inbound webhook (HMAC)", "tags": [ "Webhooks" ] } }, "/api/v1/knowledge": { "get": { "description": "Devuelve la lista de documentos knowledge.", "operationId": "listKnowledge", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de knowledge" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar knowledge", "tags": [ "Knowledge" ] }, "post": { "description": "Crea un nuevo documento knowledge.", "operationId": "createKnowledge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos del knowledge", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Knowledge creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear knowledge", "tags": [ "Knowledge" ] } }, "/api/v1/knowledge/upload": { "post": { "description": "Sube un archivo, extrae texto con Tika, chunking y guarda.", "operationId": "uploadKnowledge", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Knowledge procesado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Subir knowledge", "tags": [ "Knowledge" ] } }, "/api/v1/knowledge/{id}": { "delete": { "description": "Elimina un knowledge.", "operationId": "deleteKnowledge", "parameters": [ { "description": "Identificador del knowledge", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Knowledge eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar knowledge", "tags": [ "Knowledge" ] }, "get": { "description": "Devuelve el detalle de un knowledge.", "operationId": "getKnowledge", "parameters": [ { "description": "Identificador del knowledge", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle de knowledge" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Knowledge inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener knowledge", "tags": [ "Knowledge" ] }, "put": { "description": "Modifica un knowledge existente.", "operationId": "updateKnowledge", "parameters": [ { "description": "Identificador del knowledge", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Knowledge actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar knowledge", "tags": [ "Knowledge" ] } }, "/api/v1/knowledge/{id}/re-extract": { "post": { "description": "Re-encola la extracción para todos los documentos del knowledge (background_jobs).", "operationId": "reextractKnowledge", "parameters": [ { "description": "Identificador del knowledge", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Jobs encolados" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Re-extraer documentos", "tags": [ "Knowledge" ] } }, "/api/v1/knowledge/{id}/reindex": { "post": { "description": "Encola ReindexKnowledgeJob en el worker (chunks + embeddings). Responde 202.", "operationId": "reindexKnowledge", "parameters": [ { "description": "Identificador del knowledge", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Reindex encolado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Index ya en curso" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reindexar knowledge", "tags": [ "Knowledge" ] } }, "/api/v1/knowledge/{id}/search": { "post": { "description": "B?squeda h?brida (pgvector + trigram) sobre chunks del knowledge.", "operationId": "searchKnowledge", "parameters": [ { "description": "Identificador del knowledge", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultados" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Buscar en knowledge", "tags": [ "Knowledge" ] } }, "/api/v1/llm": { "get": { "description": "Devuelve la lista de modelos de lenguaje configurados.", "operationId": "listLLMs", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de LLMs" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar LLMs", "tags": [ "LLMs" ] }, "post": { "description": "Crea un nuevo modelo de lenguaje.", "operationId": "createLLM", "requestBody": { "content": { "application/json": { "schema": { "properties": { "base_url": { "type": "string" }, "enabled": { "type": "boolean" }, "extra": { "additionalProperties": {}, "type": "object" }, "max_input_tokens": { "format": "int32", "type": "integer" }, "max_output_tokens": { "format": "int32", "type": "integer" }, "model_name": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "reasoning_effort": { "type": "string" }, "temperature": { "format": "double", "type": "number" }, "token_quota": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "type": { "type": "string" } }, "type": "object" } } }, "description": "Datos del LLM", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "LLM creado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear LLM", "tags": [ "LLMs" ] } }, "/api/v1/llm/analyze": { "get": { "description": "Structured use-case suggestions for a gratia.llms row.", "operationId": "analyzeLLM", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Analysis" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "LLM not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Analyze registered LLM", "tags": [ "LLMs" ] } }, "/api/v1/llm/catalog": { "get": { "description": "Lists upstream models from Bifrost with Gratia guidance overlay.", "operationId": "listLLMCatalog", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Catalog page" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Upstream LLM catalog", "tags": [ "LLMs" ] } }, "/api/v1/llm/catalog/entry": { "get": { "description": "Returns one upstream model enriched with Gratia guidance.", "operationId": "getLLMCatalogEntry", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Catalog entry" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Upstream LLM catalog entry", "tags": [ "LLMs" ] } }, "/api/v1/llm/providers": { "get": { "description": "Declarative upstream providers with shared API keys for gratia.llms.", "operationId": "listLLMProviders", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Provider rows" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "List LLM provider credentials", "tags": [ "LLMs" ] }, "post": { "description": "Stores shared upstream API key used when gratia.llms.api_key is empty.", "operationId": "createLLMProvider", "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_key": { "type": "string" }, "config": { "additionalProperties": {}, "type": "object" }, "display_name": { "type": "string" }, "enabled": { "type": "boolean" }, "kind": { "type": "string" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "Provider credential", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Provider created" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Name already exists" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create LLM provider credential", "tags": [ "LLMs" ] } }, "/api/v1/llm/providers/{id}": { "delete": { "operationId": "deleteLLMProvider", "parameters": [ { "description": "Identificador del LLM provider", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "LLMs still reference provider" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete LLM provider credential", "tags": [ "LLMs" ] }, "get": { "operationId": "getLLMProvider", "parameters": [ { "description": "Identificador del LLM provider", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Provider row" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get LLM provider credential", "tags": [ "LLMs" ] }, "put": { "operationId": "updateLLMProvider", "parameters": [ { "description": "Identificador del LLM provider", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "api_key": { "type": "string" }, "config": { "additionalProperties": {}, "type": "object" }, "display_name": { "type": "string" }, "enabled": { "type": "boolean" }, "kind": { "type": "string" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "Provider fields", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Provider updated" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update LLM provider credential", "tags": [ "LLMs" ] } }, "/api/v1/llm/providers/{id}/test": { "post": { "description": "Runs a minimal probe through Bifrost using the provider's shared credential (no persistence).", "operationId": "testLLMProvider", "parameters": [ { "description": "Identificador del LLM provider", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Probe result (success true/false)" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Test LLM provider credential", "tags": [ "LLMs" ] } }, "/api/v1/llm/recommendations": { "get": { "description": "Curated use-case to model matrix maintained by GratiaMesh.", "operationId": "listLLMRecommendations", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Recommendation matrix" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "LLM use-case recommendations", "tags": [ "LLMs" ] } }, "/api/v1/llm/reconcile": { "post": { "description": "Queues ReconcileBifrostJob to mirror gratia.llms into Bifrost.", "operationId": "reconcileLLMs", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Job queued" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Enqueue Bifrost reconcile", "tags": [ "LLMs" ] } }, "/api/v1/llm/sync-status": { "get": { "description": "Read-only mirror of gratia.llms sync state to Bifrost.", "operationId": "listLLMSyncStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sync rows" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "LLM Bifrost sync status", "tags": [ "LLMs" ] } }, "/api/v1/llm/test-connection": { "post": { "description": "Syncs credentials to Bifrost and runs a minimal chat or embedding request without persisting.", "operationId": "testLLMConnection", "requestBody": { "content": { "application/json": { "schema": { "properties": { "base_url": { "type": "string" }, "llm_id": {}, "model_name": { "type": "string" }, "provider": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "description": "LLM id and/or inline credentials", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Probe result (success true/false)" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Test LLM connection", "tags": [ "LLMs" ] } }, "/api/v1/llm/{id}": { "delete": { "description": "Elimina un modelo de lenguaje.", "operationId": "deleteLLM", "parameters": [ { "description": "Identificador del LLM", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "LLM eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "En uso por agentes" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar LLM", "tags": [ "LLMs" ] }, "get": { "description": "Devuelve el detalle de un modelo de lenguaje.", "operationId": "getLLM", "parameters": [ { "description": "Identificador del LLM", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del LLM" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "LLM inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener LLM", "tags": [ "LLMs" ] }, "put": { "description": "Modifica un modelo de lenguaje existente.", "operationId": "updateLLM", "parameters": [ { "description": "Identificador del LLM", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "base_url": { "type": "string" }, "enabled": { "type": "boolean" }, "extra": { "additionalProperties": {}, "type": "object" }, "max_input_tokens": { "format": "int32", "type": "integer" }, "max_output_tokens": { "format": "int32", "type": "integer" }, "model_name": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "reasoning_effort": { "type": "string" }, "temperature": { "format": "double", "type": "number" }, "token_quota": { "properties": { "Raw": {}, "Set": { "type": "boolean" } }, "type": "object" }, "type": { "type": "string" } }, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "LLM actualizado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar LLM", "tags": [ "LLMs" ] } }, "/api/v1/llm/{id}/enabled": { "patch": { "description": "Toggle del estado enabled de un LLM.", "operationId": "setLLMEnabled", "parameters": [ { "description": "Identificador del LLM", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": { "type": "boolean" }, "type": "object" } } }, "description": "{enabled: bool}", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Estado actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Activar/desactivar LLM", "tags": [ "LLMs" ] } }, "/api/v1/mcp/servers": { "get": { "description": "Devuelve la lista de servidores Model Context Protocol configurados.", "operationId": "listMCPServers", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de servidores MCP" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar servidores MCP", "tags": [ "MCP" ] }, "post": { "description": "Registra un nuevo servidor MCP para extender capacidades de los agentes.", "operationId": "createMCPServer", "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowed_tools": { "items": { "type": "string" }, "type": "array" }, "config": {}, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "description": "Configuraci?n del servidor MCP", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Servidor MCP creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear servidor MCP", "tags": [ "MCP" ] } }, "/api/v1/mcp/servers/{id}": { "delete": { "description": "Elimina un servidor MCP.", "operationId": "deleteMCPServer", "parameters": [ { "description": "Identificador del servidor MCP", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Servidor MCP eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar servidor MCP", "tags": [ "MCP" ] }, "get": { "description": "Devuelve el detalle de un servidor MCP.", "operationId": "getMCPServer", "parameters": [ { "description": "Identificador del servidor MCP", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del servidor MCP" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Servidor MCP inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener servidor MCP", "tags": [ "MCP" ] }, "put": { "description": "Modifica la configuraci?n de un servidor MCP existente.", "operationId": "updateMCPServer", "parameters": [ { "description": "Identificador del servidor MCP", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowed_tools": { "items": { "type": "string" }, "type": "array" }, "config": {}, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Servidor MCP actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar servidor MCP", "tags": [ "MCP" ] } }, "/api/v1/platform/assistant": { "get": { "description": "Indica si el agente gratia-assistant está listo para operar. Requiere platform_assistant.use.", "operationId": "getPlatformAssistantStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Estado del asistente" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sin permiso" } }, "security": [ { "bearerAuth": [] } ], "summary": "Estado del asistente de plataforma", "tags": [ "Platform" ] } }, "/api/v1/playground/sessions": { "get": { "description": "Returns PlayGround sessions for the authenticated user.", "operationId": "listPlaygroundSessions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Session collection" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "List PlayGround sessions", "tags": [ "PlayGround" ] }, "post": { "description": "Starts a new conversation with an agent or LLM.", "operationId": "createPlaygroundSession", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "agent_id or llm_id and optional title", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create PlayGround session", "tags": [ "PlayGround" ] } }, "/api/v1/playground/sessions/{id}": { "delete": { "description": "Deletes a PlayGround session and its messages.", "operationId": "deletePlaygroundSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete session", "tags": [ "PlayGround" ] }, "get": { "description": "Returns a PlayGround session.", "operationId": "getPlaygroundSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Session detail" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get session", "tags": [ "PlayGround" ] }, "patch": { "description": "Updates a PlayGround session title.", "operationId": "patchPlaygroundSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Updated" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update session", "tags": [ "PlayGround" ] } }, "/api/v1/playground/sessions/{id}/compact": { "post": { "description": "Appends an extractive summary for older turns; full history remains in DB.", "operationId": "compactPlaygroundSession", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Compaction result" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Compact session context", "tags": [ "PlayGround" ] } }, "/api/v1/playground/sessions/{id}/messages": { "get": { "description": "Returns enriched messages with tokens, tools, reasoning and knowledge refs.", "operationId": "listPlaygroundMessagesEnhanced", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Messages" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "List messages (UI)", "tags": [ "PlayGround" ] }, "post": { "description": "Adds a user message to the session.", "operationId": "postPlaygroundMessage", "parameters": [ { "description": "Session identifier", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Post message", "tags": [ "PlayGround" ] } }, "/api/v1/rbac/groups": { "get": { "operationId": "listUserGroups", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Groups" } }, "security": [ { "bearerAuth": [] } ], "summary": "List user groups", "tags": [ "RBAC" ] }, "post": { "operationId": "createUserGroup", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create user group", "tags": [ "RBAC" ] } }, "/api/v1/rbac/groups/{id}": { "delete": { "operationId": "deleteUserGroup", "parameters": [ { "description": "Group ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete user group", "tags": [ "RBAC" ] }, "get": { "operationId": "getUserGroup", "parameters": [ { "description": "Group ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Group" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get user group", "tags": [ "RBAC" ] }, "patch": { "operationId": "patchUserGroup", "parameters": [ { "description": "Group ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update user group", "tags": [ "RBAC" ] } }, "/api/v1/rbac/groups/{id}/members": { "get": { "operationId": "listUserGroupMembers", "parameters": [ { "description": "Group ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Members" } }, "security": [ { "bearerAuth": [] } ], "summary": "List group members", "tags": [ "RBAC" ] }, "put": { "operationId": "putUserGroupMembers", "parameters": [ { "description": "Group ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Members" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace group members", "tags": [ "RBAC" ] } }, "/api/v1/rbac/groups/{id}/roles": { "put": { "operationId": "putUserGroupRoles", "parameters": [ { "description": "Group ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Group" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace group roles", "tags": [ "RBAC" ] } }, "/api/v1/rbac/permissions": { "get": { "operationId": "listRBACPermissions", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Permissions" } }, "security": [ { "bearerAuth": [] } ], "summary": "List permission catalog", "tags": [ "RBAC" ] } }, "/api/v1/rbac/roles": { "get": { "operationId": "listRBACRoles", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Roles" } }, "security": [ { "bearerAuth": [] } ], "summary": "List roles", "tags": [ "RBAC" ] }, "post": { "operationId": "createRBACRole", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Created" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create custom role", "tags": [ "RBAC" ] } }, "/api/v1/rbac/roles/{id}": { "delete": { "operationId": "deleteRBACRole", "parameters": [ { "description": "Role ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete custom role", "tags": [ "RBAC" ] }, "get": { "operationId": "getRBACRole", "parameters": [ { "description": "Role ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Role" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get role", "tags": [ "RBAC" ] }, "patch": { "operationId": "patchRBACRole", "parameters": [ { "description": "Role ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update custom role", "tags": [ "RBAC" ] } }, "/api/v1/rbac/roles/{id}/permissions": { "put": { "operationId": "putRBACRolePermissions", "parameters": [ { "description": "Role ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Updated" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace role permissions", "tags": [ "RBAC" ] } }, "/api/v1/ready": { "get": { "description": "Indica si el servicio est? listo para recibir tr?fico.", "operationId": "getReady", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Listo" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "No listo" } }, "summary": "Readiness check", "tags": [ "System" ] } }, "/api/v1/resource-acl": { "get": { "description": "Sin filas, el permiso de rol basta. Con filas, solo esas personas o grupos.", "operationId": "getResourceACL", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Lista de acceso de un recurso", "tags": [ "Admin" ] }, "put": { "description": "emails y groups vacíos vuelven a dejar el recurso abierto.", "operationId": "putResourceACL", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Sustituir la lista de acceso", "tags": [ "Admin" ] } }, "/api/v1/sandboxes": { "get": { "operationId": "listSandboxes", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colección de sandboxes" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar sandboxes", "tags": [ "Sandboxes" ] }, "post": { "operationId": "createSandbox", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sandbox creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/by-name/{name}/published": { "get": { "description": "Usado por el runner MCP (header X-Gratia-MCP-Key).", "operationId": "getPublishedSandboxByName", "parameters": [ { "description": "Nombre del sandbox", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Snapshot JSON" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sandbox inexistente" } }, "summary": "Snapshot publicado del sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/probe-url": { "post": { "description": "Handshake MCP initialize contra la URL; usado por el formulario New sandbox (remote URL).", "operationId": "probeSandboxURL", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado del probe (reachable/unreachable)" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "URL ausente o inválida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Probe una URL MCP remota (sin persistir)", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/runtime-stats": { "get": { "operationId": "listSandboxesRuntimeStats", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Métricas por sandbox" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "501": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Operator deshabilitado" } }, "security": [ { "bearerAuth": [] } ], "summary": "CPU/RAM en vivo de pods MCP por sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}": { "delete": { "operationId": "deleteSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sandbox eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar sandbox", "tags": [ "Sandboxes" ] }, "get": { "operationId": "getSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del sandbox" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sandbox inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener sandbox", "tags": [ "Sandboxes" ] }, "put": { "operationId": "updateSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sandbox actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/commands": { "get": { "operationId": "listSandboxCommands", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Comandos del sandbox" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar comandos del sandbox", "tags": [ "Sandboxes" ] }, "post": { "operationId": "createSandboxCommand", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Comando creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear comando sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/commands/validate": { "post": { "operationId": "validateSandboxCommand", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Código válido" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Política o contrato fallido" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Validar código de comando (dry-run script_policy)", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/commands/{commandId}": { "delete": { "operationId": "deleteSandboxCommand", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Identificador del comando", "in": "path", "name": "commandId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Comando eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar comando sandbox", "tags": [ "Sandboxes" ] }, "put": { "operationId": "updateSandboxCommand", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Identificador del comando", "in": "path", "name": "commandId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Comando actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar comando sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/commands/{commandId}/test": { "post": { "operationId": "testSandboxCommand", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Identificador del comando", "in": "path", "name": "commandId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado del tool call" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error MCP" } }, "security": [ { "bearerAuth": [] } ], "summary": "Probar comando MCP directamente", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/deploy": { "post": { "operationId": "deploySandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sandbox desplegado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "501": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Operator deshabilitado" } }, "security": [ { "bearerAuth": [] } ], "summary": "Desplegar sandbox MCP en K8s", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/logs": { "get": { "operationId": "sandboxLogs", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Últimas líneas de log" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Logs del pod MCP del sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/probe": { "post": { "description": "Comprueba internal_base_url (handshake MCP) y guarda el resultado en config.probe.", "operationId": "probeSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado del probe + sandbox actualizado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sandbox sin URL remota" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sandbox inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Probe del sandbox remoto y persistencia del estado", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/publish": { "post": { "description": "Genera snapshot de comandos habilitados para el runner MCP.", "operationId": "publishSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sandbox publicado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Publicar sandbox", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/restart": { "post": { "operationId": "restartSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sandbox reiniciado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reiniciar pods del sandbox MCP", "tags": [ "Sandboxes" ] } }, "/api/v1/sandboxes/{id}/stop": { "post": { "operationId": "stopSandbox", "parameters": [ { "description": "Identificador del sandbox", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Sandbox detenido" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detener sandbox MCP (scale 0)", "tags": [ "Sandboxes" ] } }, "/api/v1/t/{id}": { "post": { "description": "Ejecuta una tool MCP opted-in de forma síncrona. Auth: Bearer sl_* o tk_* (no JWT). Header opcional Idempotency-Key (o X-Gratia-Idempotency-Key): reintentos con la misma clave y el mismo body reutilizan la respuesta cacheada 24h; misma clave con body distinto → 409.", "operationId": "toolHTTPInvoke", "parameters": [ { "description": "UUID del tool_http_endpoint", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Clave opcional generada por el cliente; evita re-ejecutar MCP en retries", "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Args JSON de la tool" }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Endpoint no encontrado o disabled" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Idempotency-Key reutilizada con body distinto" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Args inválidos" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Rate limit" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error MCP" }, "504": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Timeout" } }, "security": [ { "bearerAuth": [] } ], "summary": "Invocar tool vía HTTP (Function URL)", "tags": [ "Tools" ] } }, "/api/v1/token-quotas/status": { "get": { "description": "Porcentaje de consumo del periodo actual para user/agent/llm.", "operationId": "getTokenQuotaStatus", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "statuses" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Estado de cuotas de tokens", "tags": [ "FinOps" ] } }, "/api/v1/tool-groups": { "get": { "description": "Carpetas/toolbox de tools (sistema + custom).", "operationId": "listToolGroups", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colección de groups" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar tool groups", "tags": [ "Tools" ] }, "post": { "description": "Crea un grupo custom de tools.", "operationId": "createToolGroup", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "name/slug/description", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Group creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear tool group", "tags": [ "Tools" ] } }, "/api/v1/tool-groups/{id}": { "delete": { "description": "Elimina un group custom; mueve tools a ungrouped.", "operationId": "deleteToolGroup", "parameters": [ { "description": "Identificador del tool group", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Group eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar tool group", "tags": [ "Tools" ] }, "get": { "operationId": "getToolGroup", "parameters": [ { "description": "Identificador del tool group", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "No encontrado" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener tool group", "tags": [ "Tools" ] }, "put": { "operationId": "updateToolGroup", "parameters": [ { "description": "Identificador del tool group", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "name/description", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Group actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar tool group", "tags": [ "Tools" ] } }, "/api/v1/tool-invocations": { "get": { "operationId": "listToolInvocations", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Invocaciones recientes" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar invocaciones de tools (auditoría)", "tags": [ "Tools" ] } }, "/api/v1/tools": { "get": { "description": "Devuelve la lista de herramientas disponibles para los agentes.", "operationId": "listTools", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de tools" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar tools", "tags": [ "Tools" ] }, "post": { "description": "Registra una nueva herramienta (ej. funci?n, API externa).", "operationId": "createTool", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Definici?n de la tool", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Tool creada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear tool", "tags": [ "Tools" ] } }, "/api/v1/tools/http-endpoints": { "get": { "operationId": "listToolHTTPSummaries", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Lista id/tool_id/enabled" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Resumen de endpoints HTTP de tools", "tags": [ "Tools" ] } }, "/api/v1/tools/{id}": { "delete": { "description": "Elimina una herramienta.", "operationId": "deleteTool", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tool eliminada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar tool", "tags": [ "Tools" ] }, "get": { "description": "Devuelve el detalle de una herramienta.", "operationId": "getTool", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle de la tool" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Tool inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener tool", "tags": [ "Tools" ] }, "put": { "description": "Modifica la configuraci?n de una herramienta existente.", "operationId": "updateTool", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Tool actualizada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar tool", "tags": [ "Tools" ] } }, "/api/v1/tools/{id}/http": { "get": { "operationId": "getToolHTTP", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Endpoint HTTP" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Estado HTTP externo de una tool", "tags": [ "Tools" ] }, "put": { "operationId": "putToolHTTP", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "enabled + knobs", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Endpoint actualizado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Habilitar/configurar acceso HTTP externo", "tags": [ "Tools" ] } }, "/api/v1/tools/{id}/http/invocations": { "get": { "operationId": "listToolHTTPInvocations", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Invocaciones" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Últimas invocaciones HTTP de una tool", "tags": [ "Tools" ] } }, "/api/v1/tools/{id}/http/keys": { "get": { "operationId": "listToolHTTPKeys", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Keys (sin secreto)" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar keys tk_* del Function URL", "tags": [ "Tools" ] }, "post": { "operationId": "createToolHTTPKey", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "name + expires_at opcional", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Key creada + api_key plaintext" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear key tk_* (plaintext una vez)", "tags": [ "Tools" ] } }, "/api/v1/tools/{id}/http/keys/{keyId}": { "delete": { "operationId": "revokeToolHTTPKey", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "UUID de tool_http_keys", "in": "path", "name": "keyId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Key revocada" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Revocar key tk_*", "tags": [ "Tools" ] } }, "/api/v1/tools/{id}/invoke": { "post": { "description": "Admin Try: mismo tools.Invoke que Function URL; auth JWT/sesión (no solo sl_*).", "operationId": "invokeTool", "parameters": [ { "description": "Identificador del tool", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Args JSON object" }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Resultado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Probar invocación sync de una tool MCP", "tags": [ "Tools" ] } }, "/api/v1/users": { "get": { "description": "Devuelve la lista de usuarios registrados.", "operationId": "listUsers", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de usuarios" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar usuarios", "tags": [ "Users" ] }, "post": { "description": "Crea un usuario y su API key por defecto (solo admin).", "operationId": "createUser", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Usuario creado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear usuario", "tags": [ "Users" ] } }, "/api/v1/users/me": { "patch": { "description": "Actualiza nombre, password y preferencias de chat del usuario autenticado (self-service).", "operationId": "patchCurrentUser", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "password": { "type": "string" }, "preferences": { "additionalProperties": {}, "type": "object" } }, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Usuario actualizado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar perfil propio", "tags": [ "Users" ] } }, "/api/v1/users/{id}": { "delete": { "description": "Elimina un usuario del sistema.", "operationId": "deleteUser", "parameters": [ { "description": "Identificador del usuario", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Usuario eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar usuario", "tags": [ "Users" ] }, "get": { "description": "Devuelve el detalle de un usuario.", "operationId": "getUser", "parameters": [ { "description": "Identificador del usuario", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle de usuario" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Usuario inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Obtener usuario", "tags": [ "Users" ] }, "put": { "description": "Modifica los datos de un usuario.", "operationId": "updateUser", "parameters": [ { "description": "Identificador del usuario", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Datos a actualizar", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Usuario actualizado" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Solicitud inv?lida" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar usuario", "tags": [ "Users" ] } }, "/api/v1/users/{id}/api-key/regenerate": { "post": { "description": "Invalida las claves activas del usuario y devuelve una nueva (solo admin, visible una vez).", "operationId": "regenerateUserAPIKey", "parameters": [ { "description": "Identificador del usuario", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Nueva API key" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Requiere admin" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Usuario inexistente" } }, "security": [ { "bearerAuth": [] } ], "summary": "Regenerar API key de usuario", "tags": [ "Users" ] } }, "/api/v1/users/{id}/roles": { "get": { "operationId": "getUserRoles", "parameters": [ { "description": "User ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Roles" } }, "security": [ { "bearerAuth": [] } ], "summary": "List user roles", "tags": [ "RBAC", "Users" ] }, "put": { "operationId": "putUserRoles", "parameters": [ { "description": "User ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Roles" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace user roles", "tags": [ "RBAC", "Users" ] } }, "/api/v1/version": { "get": { "description": "Devuelve la versi?n sem?ntica del componente.", "operationId": "getVersion", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Versi?n actual" } }, "summary": "Versi?n del servicio", "tags": [ "System" ] } }, "/api/v1/webhooks/deliveries/{id}": { "get": { "operationId": "getWebhookDelivery", "parameters": [ { "description": "UUID de la delivery", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Delivery" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle delivery", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/outbound-deliveries/{id}": { "get": { "operationId": "getWebhookOutboundDelivery", "parameters": [ { "description": "UUID de la outbound delivery", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Delivery" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle outbound delivery", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/outbound-deliveries/{id}/retry": { "post": { "operationId": "retryWebhookOutboundDelivery", "parameters": [ { "description": "UUID de la outbound delivery", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Reencolado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Reintentar outbound delivery", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/subscriptions": { "get": { "operationId": "listWebhookSubscriptions", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar subscriptions outbound", "tags": [ "Webhooks" ] }, "post": { "operationId": "createWebhookSubscription", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Subscription + secret" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear subscription outbound", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/subscriptions/{id}": { "delete": { "operationId": "deleteWebhookSubscription", "parameters": [ { "description": "UUID de la subscription outbound", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar subscription", "tags": [ "Webhooks" ] }, "get": { "operationId": "getWebhookSubscription", "parameters": [ { "description": "UUID de la subscription outbound", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Subscription" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle subscription", "tags": [ "Webhooks" ] }, "patch": { "operationId": "patchWebhookSubscription", "parameters": [ { "description": "UUID de la subscription outbound", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Subscription" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar subscription", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/subscriptions/{id}/deliveries": { "get": { "operationId": "listWebhookOutboundDeliveries", "parameters": [ { "description": "UUID de la subscription outbound", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deliveries outbound", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/subscriptions/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSubscriptionSecret", "parameters": [ { "description": "UUID de la subscription outbound", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Nuevo secret" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Rotar secret subscription", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/subscriptions/{id}/test": { "post": { "operationId": "testWebhookSubscription", "parameters": [ { "description": "UUID de la subscription outbound", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Accepted" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Test subscription (webhook.test)", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/summary": { "get": { "operationId": "webhooksSummary", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "KPIs" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Resumen webhooks", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/triggers": { "get": { "operationId": "listWebhookTriggers", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Listar webhook triggers", "tags": [ "Webhooks" ] }, "post": { "description": "Genera secret whsec_ (plaintext solo en esta respuesta).", "operationId": "createWebhookTrigger", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Trigger + secret" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Crear webhook trigger", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/triggers/{id}": { "delete": { "operationId": "deleteWebhookTrigger", "parameters": [ { "description": "UUID del webhook trigger", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Eliminado" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Eliminar webhook trigger", "tags": [ "Webhooks" ] }, "get": { "operationId": "getWebhookTrigger", "parameters": [ { "description": "UUID del webhook trigger", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Trigger" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Detalle webhook trigger", "tags": [ "Webhooks" ] }, "patch": { "operationId": "patchWebhookTrigger", "parameters": [ { "description": "UUID del webhook trigger", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Trigger" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Actualizar webhook trigger", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/triggers/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "parameters": [ { "description": "UUID del webhook trigger", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Lista" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deliveries de un trigger", "tags": [ "Webhooks" ] } }, "/api/v1/webhooks/triggers/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookTriggerSecret", "parameters": [ { "description": "UUID del webhook trigger", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Trigger + nuevo secret" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sesi?n inv?lida" } }, "security": [ { "bearerAuth": [] } ], "summary": "Rotar secret del trigger", "tags": [ "Webhooks" ] } }, "/health": { "get": { "description": "Devuelve el estado del servicio y dependencias (PostgreSQL, storage, Bifrost).", "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "db": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } }, "description": "Estado actual" } }, "summary": "Health check", "tags": [ "System" ] } }, "/livez": { "get": { "description": "Process is alive (no dependency checks). Used by Kubernetes liveness probes.", "operationId": "getLivez", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Alive" } }, "summary": "Liveness check", "tags": [ "System" ] } }, "/metrics": { "get": { "description": "Métricas Prometheus. Auth: sesión/API key con metrics.view, o Bearer GRATIA_METRICS_SCRAPE_TOKEN.", "operationId": "getMetrics", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Métricas Prometheus" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "No autenticado" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Sin metrics.view" } }, "security": [ { "bearerAuth": [] } ], "summary": "Prometheus metrics", "tags": [ "System" ] } }, "/v1/chat/completions": { "post": { "description": "Proxy OpenAI-compatible hacia Bifrost. Requiere Bearer JWT o API key de usuario (sl_*).", "operationId": "proxyChatCompletions", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "Payload OpenAI chat", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Respuesta del modelo" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Token o API key inv?lidos" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "security": [ { "bearerAuth": [] } ], "summary": "Proxy chat completions", "tags": [ "Chat" ] } }, "/v1/conversations": { "post": { "operationId": "createConversation", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Conversation" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create conversation", "tags": [ "Responses" ] } }, "/v1/conversations/{id}": { "delete": { "operationId": "deleteConversation", "parameters": [ { "description": "Conversation id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Deleted" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete conversation", "tags": [ "Responses" ] }, "get": { "operationId": "getConversation", "parameters": [ { "description": "Conversation id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Conversation" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get conversation", "tags": [ "Responses" ] } }, "/v1/models": { "get": { "description": "Lista de modelos disponibles seg?n Bifrost.", "operationId": "listModels", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Modelos" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Listar modelos", "tags": [ "Models" ] } }, "/v1/models/base": { "get": { "description": "Modelos base soportados por la instalaci?n de Bifrost.", "operationId": "listBaseModels", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Modelos base" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Listar modelos base", "tags": [ "Models" ] } }, "/v1/providers": { "get": { "description": "Recupera los providers registrados en Bifrost.", "operationId": "listProviders", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de providers" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Listado de providers", "tags": [ "Providers" ] }, "post": { "description": "Crea un nuevo provider custom en Bifrost.", "operationId": "createProvider", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Configuraci?n completa del provider", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Provider creado" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Crear provider", "tags": [ "Providers" ] } }, "/v1/providers/keys": { "get": { "description": "Devuelve todas las API keys registradas en Bifrost.", "operationId": "listAllProviderKeys", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de keys" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Listar keys de providers", "tags": [ "Providers" ] } }, "/v1/providers/{name}": { "delete": { "description": "Borra un provider registrado en Bifrost.", "operationId": "deleteProvider", "parameters": [ { "description": "Nombre del provider", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Provider eliminado" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Eliminar provider", "tags": [ "Providers" ] }, "get": { "description": "Devuelve la configuraci?n completa de un provider.", "operationId": "getProvider", "parameters": [ { "description": "Nombre del provider", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle del provider" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Provider inexistente" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Obtener provider", "tags": [ "Providers" ] }, "put": { "description": "Reemplaza la configuraci?n de un provider existente.", "operationId": "updateProvider", "parameters": [ { "description": "Nombre del provider", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Payload completo del provider", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Provider actualizado" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Actualizar provider", "tags": [ "Providers" ] } }, "/v1/providers/{provider}/keys": { "get": { "description": "Obtiene las keys asociadas a un provider espec?fico.", "operationId": "listProviderKeys", "parameters": [ { "description": "Identificador del provider", "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "type": "object" }, "type": "array" } } }, "description": "Colecci?n de keys" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Listar keys por provider", "tags": [ "Providers" ] }, "post": { "description": "Registra una nueva API key en Bifrost.", "operationId": "createProviderKey", "parameters": [ { "description": "Identificador del provider", "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Payload de la key", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Key creada" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Crear key", "tags": [ "Providers" ] } }, "/v1/providers/{provider}/keys/{key_id}": { "delete": { "description": "Elimina una API key de Bifrost.", "operationId": "deleteProviderKey", "parameters": [ { "description": "Identificador del provider", "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "description": "Identificador de la API key", "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Key eliminada" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Eliminar key", "tags": [ "Providers" ] }, "get": { "description": "Devuelve el detalle de una API key.", "operationId": "getProviderKey", "parameters": [ { "description": "Identificador del provider", "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "description": "Identificador de la API key", "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Detalle de la key" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Key inexistente" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Obtener key", "tags": [ "Providers" ] }, "put": { "description": "Reemplaza la configuraci?n de una API key.", "operationId": "updateProviderKey", "parameters": [ { "description": "Identificador del provider", "in": "path", "name": "provider", "required": true, "schema": { "type": "string" } }, { "description": "Identificador de la API key", "in": "path", "name": "key_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Payload completo de la key", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Key actualizada" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "summary": "Actualizar key", "tags": [ "Providers" ] } }, "/v1/responses": { "post": { "description": "LLM passthrough via Bifrost or native agent execution. Bearer JWT or sl_* API key.", "operationId": "createResponse", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "OpenAI Responses create payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Completed response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Token quota exceeded" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create response (OpenAI Responses API)", "tags": [ "Responses" ] } }, "/v1/responses/{id}": { "delete": { "operationId": "deleteResponse", "parameters": [ { "description": "Response id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Deleted" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete response", "tags": [ "Responses" ] }, "get": { "operationId": "getResponse", "parameters": [ { "description": "Response id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Response object" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Not found" }, "502": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string" } }, "type": "object" } } }, "description": "Error al contactar Bifrost" } }, "security": [ { "bearerAuth": [] } ], "summary": "Get response", "tags": [ "Responses" ] } } }, "servers": [ { "description": "default", "url": "/" } ] }