Referencia de API¶

Este documento proporciona documentacion completa para las APIs del runtime de Symbiont. El proyecto Symbiont expone dos sistemas de API distintos diseñados para diferentes casos de uso y etapas de desarrollo.

Descripcion General¶

Symbiont ofrece dos interfaces de API:

1. API HTTP del Runtime - Una API completa para interaccion directa con el runtime, gestion de agentes y ejecucion de flujos de trabajo
2. API de Revision de Herramientas (Produccion) - Una API completa y lista para produccion para flujos de trabajo de revision y firma de herramientas impulsados por IA

API HTTP del Runtime¶

La API HTTP del Runtime proporciona acceso directo al runtime de Symbiont para ejecucion de flujos de trabajo, gestion de agentes y monitoreo del sistema. Todos los endpoints estan completamente implementados y listos para produccion cuando la caracteristica http-api esta habilitada.

URL Base¶

http://127.0.0.1:8080/api/v1

Autenticacion¶

Las rutas del runtime, salvo las comprobaciones de salud, requieren autenticación Bearer. Configure un archivo privado de claves API o el token de operador heredado SYMBIONT_API_TOKEN.

Authorization: Bearer <your-token>

Endpoints Protegidos: - Todos los endpoints /api/v1/agents/* requieren autenticacion - Solo las comprobaciones de salud son públicas. Los flujos de trabajo y las métricas requieren permisos de administrador.

Endpoints Disponibles¶

Verificacion de Salud¶

GET /api/v1/health

Devuelve el estado actual de salud del sistema e informacion basica del runtime.

Respuesta (200 OK):

{
  "status": "healthy",
  "uptime_seconds": 3600,
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Respuesta (500 Error Interno del Servidor):

{
  "status": "unhealthy",
  "error": "Database connection failed",
  "timestamp": "2024-01-15T10:30:00Z"
}

Endpoints Disponibles¶

Ejecucion de Flujo de Trabajo¶

POST /api/v1/workflows/execute

Un administrador envía código DSL en workflow_id; parameters es la entrada de la ejecución. agent_id permite crear o reemplazar un registro; si se omite, se asigna uno nuevo. Las claves limitadas a un agente reciben 403 ADMIN_REQUIRED y pueden ejecutar su código registrado mediante /agents/{id}/execute. queued confirma la admisión; consulte /agents/{id}/history por execution_id para ver el resultado. Véase el contrato completo.

Si el DSL omite el sandbox, Docker/Tier1 sigue siendo el valor predeterminado del registro. with sandbox = "landlock" selecciona explicitamente el backend nativo supervisado; Landlock no satisface un requisito de nivel de contenedor o VM.

Cuerpo de Solicitud:

{
  "workflow_id": "agent report() { with sandbox = \"docker\" {} }",
  "parameters": {},
  "agent_id": null
}

Respuesta (200 OK):

{
  "status": "queued",
  "workflow_id": "agent report() { with sandbox = \"docker\" {} }",
  "agent_id": "19b183f7-97c4-4e42-9c62-5e9c940bfae3",
  "execution_id": "c7022f13-7140-4a09-8e30-b1941e0cbb32",
  "metadata": {}
}

Gestion de Agentes¶

Todos los endpoints de gestion de agentes requieren autenticacion via el encabezado Authorization: Bearer <token>.

Listar Agentes¶

GET /api/v1/agents
Authorization: Bearer <your-token>

Recupera una lista de todos los agentes activos en el runtime.

Respuesta (200 OK):

[
  "agent-id-1",
  "agent-id-2",
  "agent-id-3"
]

Obtener Estado del Agente¶

GET /api/v1/agents/{id}/status
Authorization: Bearer <your-token>

Obtiene el estado del planificador para un agente especifico. La CPU y la memoria admiten valores nulos; el planificador actual no muestrea por agente y devuelve null tanto para agentes internos como externos. Los clientes no deben presentar esos valores como un uso de cero.

Respuesta (200 OK):

{
  "agent_id": "uuid",
  "state": "Running",
  "last_activity": "2024-01-15T10:30:00Z",
  "resource_usage": {
    "memory_bytes": null,
    "cpu_percent": null,
    "active_tasks": 1
  },
  "execution_mode": "Ephemeral"
}

active_tasks cuenta las tareas que pertenecen al planificador. last_activity no es la marca de tiempo de una muestra de recursos. Fleet Overview muestra Not sampled cuando faltan la CPU y la memoria; Capacidad de los workers proporciona el uso de los workers y la capacidad reservada, muestreados por separado. Esos valores de los workers no son totales por agente.

Nuevos Estados del Agente: - running: El agente esta ejecutando activamente con un proceso en ejecucion - ready: El agente esta inicializado y listo para ejecucion - waiting: El agente esta en cola para ejecucion - failed: La ejecucion del agente fallo o la verificacion de salud fallo - completed: La tarea del agente se completo exitosamente - terminated: El agente fue terminado graciosamente o forzosamente

Crear Agente¶

POST /api/v1/agents
Authorization: Bearer <your-token>

Crea un nuevo agente con la configuracion proporcionada.

Cuerpo de Solicitud:

{
  "name": "my-agent",
  "dsl": "agent definition in DSL format"
}

Respuesta (200 OK):

{
  "id": "uuid",
  "status": "created"
}

Actualizar Agente¶

PUT /api/v1/agents/{id}
Authorization: Bearer <your-token>

Actualiza la configuracion de un agente existente. Al menos un campo debe ser proporcionado.

Cuerpo de Solicitud:

{
  "name": "updated-agent-name",
  "dsl": "updated agent definition in DSL format"
}

Respuesta (200 OK):

{
  "id": "uuid",
  "status": "updated"
}

Eliminar Agente¶

DELETE /api/v1/agents/{id}
Authorization: Bearer <your-token>

Elimina un agente existente del runtime.

Respuesta (200 OK):

{
  "id": "uuid",
  "status": "deleted"
}

Ejecutar Agente¶

POST /api/v1/agents/{id}/execute
Idempotency-Key: <UUID retained for retries>
Authorization: Bearer <your-token>

Envia una invocacion del agente seleccionado. Reutiliza el mismo UUID y la misma peticion para recuperar una finalizacion guardada o un resultado explicito de tipo activo / sin resolver / reconciliado / en conflicto. Consulte los estados de reintento del planificador.

Cuerpo de Solicitud:

{}

Respuesta (200 OK):

{
  "execution_id": "uuid",
  "status": "queued"
}

Obtener Historial de Ejecucion del Agente¶

GET /api/v1/agents/{id}/history
Authorization: Bearer <your-token>

Recupera el historial de ejecucion para un agente especifico.

Respuesta (200 OK):

{
  "history": [
    {
      "execution_id": "uuid",
      "status": "completed",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Heartbeat del Agente¶

POST /api/v1/agents/{id}/heartbeat
Authorization: Bearer <your-token>

Envia un heartbeat desde un agente en ejecucion para actualizar su estado de salud.

Enviar Evento al Agente¶

POST /api/v1/agents/{id}/events
Authorization: Bearer <your-token>

Envia un evento externo a un agente en ejecucion para ejecucion basada en eventos.

Metricas del Sistema¶

GET /api/v1/metrics

Recupera una instantanea de metricas completa cubriendo programador, gestor de tareas, balanceador de carga y recursos del sistema.

Respuesta (200 OK):

{
  "timestamp": "2026-02-16T12:00:00Z",
  "scheduler": {
    "total_jobs": 12,
    "active_jobs": 8,
    "paused_jobs": 2,
    "failed_jobs": 1,
    "total_runs": 450,
    "successful_runs": 445,
    "dead_letter_count": 2
  },
  "task_manager": {
    "queued_tasks": 3,
    "running_tasks": 5,
    "completed_tasks": 1200,
    "failed_tasks": 15
  },
  "load_balancer": {
    "total_workers": 4,
    "active_workers": 3,
    "requests_per_second": 12.5
  },
  "system": {
    "cpu_usage_percent": 45.2,
    "memory_usage_bytes": 536870912,
    "memory_total_bytes": 17179869184,
    "uptime_seconds": 3600
  }
}

La instantanea de metricas tambien puede exportarse a archivos (escritura JSON atomica) o endpoints OTLP usando el sistema MetricsExporter del runtime. Consulta la seccion Metricas y Telemetria a continuacion.

Metricas y Telemetria¶

Symbiont soporta la exportacion de metricas del runtime a multiples backends:

Exportador de Archivos¶

Escribe instantaneas de metricas como archivos JSON atomicos (tempfile + rename):

use symbi_runtime::metrics::{FileMetricsExporter, MetricsExporterConfig};

let exporter = FileMetricsExporter::new("/var/lib/symbi/metrics.json");
exporter.export(&snapshot)?;

Exportador OTLP¶

Envia metricas a cualquier endpoint compatible con OpenTelemetry (requiere la feature metrics):

use symbi_runtime::metrics::{OtlpExporter, OtlpExporterConfig, OtlpProtocol};

let config = OtlpExporterConfig {
    endpoint: "http://localhost:4317".to_string(),
    protocol: OtlpProtocol::Grpc,
    ..Default::default()
};

Exportador Compuesto¶

Fan-out a multiples backends simultaneamente — los fallos de exportacion individuales se registran pero no bloquean otros exportadores:

use symbi_runtime::metrics::CompositeExporter;

let composite = CompositeExporter::new(vec![
    Box::new(file_exporter),
    Box::new(otlp_exporter),
]);

Recoleccion en Segundo Plano¶

El MetricsCollector se ejecuta como un hilo en segundo plano, recopilando periodicamente instantaneas y exportandolas:

use symbi_runtime::metrics::MetricsCollector;

let collector = MetricsCollector::new(exporter, interval);
collector.start();
// ... later ...
collector.stop();

Escaneo de Habilidades (ClawHavoc)¶

El SkillScanner inspecciona el contenido de habilidades de agentes en busca de patrones maliciosos antes de cargarlas. Incluye 40 reglas de defensa ClawHavoc integradas en 10 categorias de ataque:

Consulta el Modelo de Seguridad para la lista completa de reglas y modelo de severidad.

Uso¶

use symbi_runtime::skills::SkillScanner;

let scanner = SkillScanner::new(); // includes all 40 default rules
let result = scanner.scan_skill("/path/to/skill/");

if !result.passed {
    for finding in &result.findings {
        eprintln!("[{}] {}: {} (line {})",
            finding.severity, finding.rule, finding.message, finding.line);
    }
}

Se pueden agregar patrones de denegacion personalizados junto con los predeterminados:

let scanner = SkillScanner::with_custom_rules(vec![
    ("custom-pattern".into(), r"my_dangerous_pattern".into(),
     ScanSeverity::Warning, "Custom rule description".into()),
]);

Configuracion del Servidor¶

El servidor de la API HTTP del Runtime puede configurarse con las siguientes opciones:

• Direccion de enlace predeterminada: 127.0.0.1:8080
• Soporte CORS: Configurable para desarrollo
• Rastreo de solicitudes: Habilitado via middleware Tower
• Feature gate: Disponible tras la caracteristica http-api de Cargo

Referencia de Configuracion de Features¶

Inferencia LLM en la Nube (cloud-llm)¶

Conecta a proveedores de LLM en la nube via OpenRouter para razonamiento de agentes:

cargo build --features cloud-llm

Variables de Entorno: - OPENROUTER_API_KEY — Tu clave de API de OpenRouter (requerida) - OPENROUTER_MODEL — Modelo a usar (por defecto: google/gemini-2.0-flash-001) - OPENROUTER_REFERER — Opcional. Establece la cabecera HTTP-Referer en las solicitudes a OpenRouter (atribucion de aplicacion). Dejala sin definir para trafico no atribuido. - OPENROUTER_TITLE — Opcional. Establece la cabecera X-Title. Consulta atribucion de aplicaciones en OpenRouter.

El proveedor de LLM en la nube se integra con el pipeline execute_actions() del bucle de razonamiento. Soporta respuestas en streaming, reintentos automaticos con retroceso exponencial y seguimiento de uso de tokens.

Modo Agente Autonomo (standalone-agent)¶

Meta-feature que habilita la inferencia LLM en la nube para agentes nativos de la nube:

cargo build --features standalone-agent
# Enables: cloud-llm

Variables de Entorno: - OPENROUTER_API_KEY — Clave de API de OpenRouter

Note: Composio MCP and SymbiBot integration were removed in this version due to security concerns — see SECURITY_AUDIT.md C3 for context.

Motor de Politicas Cedar (cedar)¶

Autorizacion formal usando el lenguaje de politicas Cedar:

cargo build --features cedar

Las politicas Cedar se integran con la fase Gate del bucle de razonamiento, proporcionando decisiones de autorizacion granulares. Consulta el Modelo de Seguridad para ejemplos de politicas.

Configuracion de Base de Datos Vectorial¶

Symbiont incluye LanceDB como backend vectorial embebido por defecto — no se requiere servicio externo. Para despliegues a escala, Qdrant esta disponible como backend opcional.

LanceDB (por defecto):

[vector_db]
enabled = true
backend = "lancedb"
collection_name = "symbi_knowledge"

No se necesita configuracion adicional. Los datos se almacenan localmente junto al runtime.

Qdrant (opcional):

cargo build --features vector-qdrant

[vector_db]
enabled = true
backend = "qdrant"
collection_name = "symbi_knowledge"
url = "http://localhost:6333"

Variables de Entorno: - SYMBIONT_VECTOR_BACKEND — lancedb (por defecto) o qdrant - QDRANT_URL — URL del servidor Qdrant (solo cuando se usa Qdrant)

Primitivas de Razonamiento Avanzado (orga-adaptive)¶

Habilita curacion de herramientas, deteccion de bucles atascados, pre-carga de contexto y convenciones con alcance:

cargo build --features orga-adaptive

Consulta la guia de orga-adaptive para la referencia completa de configuracion.

Estructuras de Datos¶

Tipos Centrales¶

// Workflow execution request
WorkflowExecutionRequest {
    workflow_id: String,
    parameters: serde_json::Value,
    agent_id: Option<AgentId>
}

// Agent status response
AgentStatusResponse {
    agent_id: AgentId,
    state: AgentState,
    last_activity: DateTime<Utc>,
    resource_usage: ResourceUsage
}

// Health check response
HealthResponse {
    status: String,
    uptime_seconds: u64,
    timestamp: DateTime<Utc>,
    version: String
}

// Agent creation request
CreateAgentRequest {
    name: String,
    dsl: String
}

// Agent creation response
CreateAgentResponse {
    id: String,
    status: String
}

// Agent update request
UpdateAgentRequest {
    name: Option<String>,
    dsl: Option<String>
}

// Agent update response
UpdateAgentResponse {
    id: String,
    status: String
}

// Agent deletion response
DeleteAgentResponse {
    id: String,
    status: String
}

// Agent execution request
ExecuteAgentRequest {
    // Empty struct for now
}

// Agent execution response
ExecuteAgentResponse {
    execution_id: String,
    status: String
}

// Agent execution record
AgentExecutionRecord {
    execution_id: String,
    status: String,
    timestamp: String
}

// Agent execution history response
GetAgentHistoryResponse {
    history: Vec<AgentExecutionRecord>
}

Interfaz del Proveedor de Runtime¶

La API implementa un trait RuntimeApiProvider con los siguientes metodos mejorados:

• execute_workflow() - Ejecuta un flujo de trabajo con parametros dados
• get_agent_status() - Recupera estado detallado con metricas de ejecucion en tiempo real
• get_system_health() - Obtiene el estado general de salud del sistema con estadisticas del programador
• list_agents() - Lista todos los agentes (en ejecucion, en cola y completados)
• shutdown_agent() - Apagado gracioso con limpieza de recursos y manejo de timeout
• get_metrics() - Recupera metricas completas del sistema incluyendo estadisticas de tareas
• create_agent() - Crea agentes con especificacion de modo de ejecucion
• update_agent() - Actualiza la configuracion del agente con persistencia
• delete_agent() - Elimina agente con limpieza adecuada de procesos en ejecucion
• execute_agent() - Activa ejecucion con monitoreo y verificaciones de salud
• get_agent_history() - Recupera historial de ejecucion detallado con metricas de rendimiento

API de Programacion¶

Todos los endpoints de programacion requieren autenticacion. Requiere la feature cron.

Listar Programaciones¶

GET /api/v1/schedules
Authorization: Bearer <your-token>

Respuesta (200 OK):

[
  {
    "job_id": "uuid",
    "name": "daily-report",
    "cron_expression": "0 0 9 * * *",
    "timezone": "America/New_York",
    "status": "active",
    "enabled": true,
    "next_run": "2026-03-04T09:00:00Z",
    "run_count": 42
  }
]

Crear Programacion¶

POST /api/v1/schedules
Authorization: Bearer <your-token>

Cuerpo de Solicitud:

{
  "name": "daily-report",
  "cron_expression": "0 0 9 * * *",
  "timezone": "America/New_York",
  "agent_name": "report-agent",
  "policy_ids": ["policy-1"],
  "one_shot": false
}

La cron_expression usa seis campos: sec min hour day month weekday (campo septimo opcional para año).

Respuesta (200 OK):

{
  "job_id": "uuid",
  "next_run": "2026-03-04T09:00:00Z",
  "status": "created"
}

Actualizar Programacion¶

PUT /api/v1/schedules/{id}
Authorization: Bearer <your-token>

Cuerpo de Solicitud (todos los campos opcionales):

{
  "cron_expression": "0 */10 * * * *",
  "timezone": "UTC",
  "policy_ids": ["policy-2"],
  "one_shot": true
}

Pausar / Reanudar / Activar Programacion¶

POST /api/v1/schedules/{id}/pause
POST /api/v1/schedules/{id}/resume
POST /api/v1/schedules/{id}/trigger
Authorization: Bearer <your-token>
Idempotency-Key: <invocation-uuid>

La activacion manual requiere un token administrativo y un UUID en Idempotency-Key. Devuelve queued, un resultado guardado o un estado explicito in_progress / unresolved / reconciled / conflict. Reutilice el UUID al reintentar. Pausar y reanudar conservan la respuesta siguiente; una ejecucion no resuelta impide reanudar. Consulte la recuperacion de cron.

Respuesta (200 OK):

{
  "job_id": "uuid",
  "action": "paused",
  "status": "ok"
}

Eliminar Programacion¶

DELETE /api/v1/schedules/{id}
Authorization: Bearer <your-token>

Respuesta (200 OK):

{
  "job_id": "uuid",
  "deleted": true
}

Obtener Historial de Programacion¶

GET /api/v1/schedules/{id}/history
Authorization: Bearer <your-token>

Respuesta (200 OK):

{
  "job_id": "uuid",
  "history": [
    {
      "run_id": "uuid",
      "started_at": "2026-03-03T09:00:00Z",
      "completed_at": "2026-03-03T09:01:23Z",
      "status": "completed",
      "error": null,
      "execution_time_ms": 83000
    }
  ]
}

Obtener Proximas Ejecuciones¶

GET /api/v1/schedules/{id}/next?count=5
Authorization: Bearer <your-token>

Respuesta (200 OK):

{
  "job_id": "uuid",
  "next_runs": [
    "2026-03-04T09:00:00Z",
    "2026-03-05T09:00:00Z"
  ]
}

Salud del Programador¶

GET /api/v1/health/scheduler

Devuelve salud y estadisticas especificas del programador.

API de Adaptadores de Canal¶

Todos los endpoints de canal requieren autenticacion. Conecta agentes a Slack, Microsoft Teams y Mattermost.

Listar Canales¶

GET /api/v1/channels
Authorization: Bearer <your-token>

Respuesta (200 OK):

[
  {
    "id": "uuid",
    "name": "slack-general",
    "platform": "slack",
    "status": "running"
  }
]

Registrar Canal¶

POST /api/v1/channels
Authorization: Bearer <your-token>

Cuerpo de Solicitud:

{
  "name": "slack-general",
  "platform": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/...",
    "channel": "#general"
  }
}

Plataformas soportadas: slack, teams, mattermost.

Respuesta (200 OK):

{
  "id": "uuid",
  "name": "slack-general",
  "platform": "slack",
  "status": "registered"
}

Obtener / Actualizar / Eliminar Canal¶

GET    /api/v1/channels/{id}
PUT    /api/v1/channels/{id}
DELETE /api/v1/channels/{id}
Authorization: Bearer <your-token>

Iniciar / Detener Canal¶

POST /api/v1/channels/{id}/start
POST /api/v1/channels/{id}/stop
Authorization: Bearer <your-token>

Respuesta (200 OK):

{
  "id": "uuid",
  "action": "started",
  "status": "ok"
}

Salud del Canal¶

GET /api/v1/channels/{id}/health
Authorization: Bearer <your-token>

Respuesta (200 OK):

{
  "id": "uuid",
  "connected": true,
  "platform": "slack",
  "workspace_name": "my-team",
  "channels_active": 3,
  "last_message_at": "2026-03-03T15:42:00Z",
  "uptime_secs": 86400
}

Mapeo de Identidades¶

GET  /api/v1/channels/{id}/mappings
POST /api/v1/channels/{id}/mappings
Authorization: Bearer <your-token>

Mapea usuarios de plataforma a identidades de Symbiont para interacciones con agentes.

Registro de Auditoria del Canal¶

GET /api/v1/channels/{id}/audit
Authorization: Bearer <your-token>

Funciones del Programador¶

Ejecucion Real de Tareas: - Generacion de procesos con entornos de ejecucion seguros - Monitoreo de recursos (memoria, CPU) con intervalos de 5 segundos - Verificaciones de salud y deteccion automatica de fallos - Soporte para modos de ejecucion efimeros, persistentes, programados y basados en eventos

Apagado Gracioso: - Periodo de terminacion graciosa de 30 segundos - Terminacion forzada para procesos que no responden - Limpieza de recursos y persistencia de metricas - Limpieza de cola y sincronizacion de estado

Gestion de Contexto Mejorada¶

Capacidades de Busqueda Avanzada:

{
  "query_type": "keyword|temporal|similarity|hybrid",
  "search_terms": ["term1", "term2"],
  "time_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "memory_types": ["factual", "procedural", "episodic"],
  "relevance_threshold": 0.7,
  "max_results": 10
}

Calculo de Importancia: - Puntuacion multi-factor con frecuencia de acceso, recencia y retroalimentacion del usuario - Ponderacion por tipo de memoria y factores de decaimiento por edad - Calculo de puntuacion de confianza para conocimiento compartido

Integracion de Control de Acceso: - Motor de politicas conectado a operaciones de contexto - Acceso con alcance de agente con limites seguros - Comparticion de conocimiento con permisos granulares

API de Revision de Herramientas (Produccion)¶

La API de Revision de Herramientas proporciona un flujo de trabajo completo para revisar, analizar y firmar herramientas MCP (Protocolo de Contexto de Modelo) de forma segura utilizando analisis de seguridad impulsado por IA con capacidades de supervision humana.

URL Base¶

https://your-symbiont-instance.com/api/v1

Autenticacion¶

Todos los endpoints requieren autenticacion JWT Bearer:

Authorization: Bearer <your-jwt-token>

Flujo de Trabajo Principal¶

La API de Revision de Herramientas sigue este flujo de solicitud/respuesta:

graph TD
    A[Submit Tool] --> B[Security Analysis]
    B --> C{Risk Assessment}
    C -->|Low Risk| D[Auto-Approve]
    C -->|High Risk| E[Human Review Queue]
    E --> F[Human Decision]
    F --> D
    D --> G[Code Signing]
    G --> H[Signed Tool Ready]

Endpoints¶

Sesiones de Revision¶

Enviar Herramienta para Revision¶

POST /sessions

Envia una herramienta MCP para revision y analisis de seguridad.

Cuerpo de Solicitud:

{
  "tool_name": "string",
  "tool_version": "string",
  "source_code": "string",
  "metadata": {
    "description": "string",
    "author": "string",
    "permissions": ["array", "of", "permissions"]
  }
}

Respuesta:

{
  "review_id": "uuid",
  "status": "submitted",
  "created_at": "2024-01-15T10:30:00Z"
}

Listar Sesiones de Revision¶

GET /sessions

Recupera una lista paginada de sesiones de revision con filtrado opcional.

Parametros de Consulta: - page (integer): Numero de pagina para paginacion - limit (integer): Numero de elementos por pagina - status (string): Filtrar por estado de revision - author (string): Filtrar por autor de herramienta

Respuesta:

{
  "sessions": [
    {
      "review_id": "uuid",
      "tool_name": "string",
      "status": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "has_next": true
  }
}

Obtener Detalles de Sesion de Revision¶

GET /sessions/{reviewId}

Recupera informacion detallada sobre una sesion de revision especifica.

Respuesta:

{
  "review_id": "uuid",
  "tool_name": "string",
  "tool_version": "string",
  "status": "string",
  "analysis_results": {
    "risk_score": 85,
    "findings": ["array", "of", "security", "findings"],
    "recommendations": ["array", "of", "recommendations"]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Analisis de Seguridad¶

Obtener Resultados de Analisis¶

GET /analysis/{analysisId}

Recupera resultados detallados de analisis de seguridad para un analisis especifico.

Respuesta:

{
  "analysis_id": "uuid",
  "review_id": "uuid",
  "risk_score": 85,
  "analysis_type": "automated",
  "findings": [
    {
      "severity": "high",
      "category": "code_injection",
      "description": "Potential code injection vulnerability detected",
      "location": "line 42",
      "recommendation": "Sanitize user input before execution"
    }
  ],
  "rag_insights": [
    {
      "knowledge_source": "security_kb",
      "relevance_score": 0.95,
      "insight": "Similar patterns found in known vulnerabilities"
    }
  ],
  "completed_at": "2024-01-15T10:45:00Z"
}

Flujo de Trabajo de Revision Humana¶

Obtener Cola de Revision¶

GET /review/queue

Recupera elementos pendientes de revision humana, tipicamente herramientas de alto riesgo que requieren inspeccion manual.

Respuesta:

{
  "pending_reviews": [
    {
      "review_id": "uuid",
      "tool_name": "string",
      "risk_score": 92,
      "priority": "high",
      "assigned_to": "reviewer@example.com",
      "escalated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "queue_stats": {
    "total_pending": 5,
    "high_priority": 2,
    "average_wait_time": "2h 30m"
  }
}

Enviar Decision de Revision¶

POST /review/{reviewId}/decision

Envia la decision de un revisor humano sobre una revision de herramienta.

Cuerpo de Solicitud:

{
  "decision": "approve|reject|request_changes",
  "comments": "Detailed review comments",
  "conditions": ["array", "of", "approval", "conditions"],
  "reviewer_id": "reviewer@example.com"
}

Respuesta:

{
  "review_id": "uuid",
  "decision": "approve",
  "processed_at": "2024-01-15T12:00:00Z",
  "next_status": "approved_for_signing"
}

Firma de Herramientas¶

Obtener Estado de Firma¶

GET /signing/{reviewId}

Recupera el estado de firma e informacion de firma para una herramienta revisada.

Respuesta:

{
  "review_id": "uuid",
  "signing_status": "completed",
  "signature_info": {
    "algorithm": "RSA-SHA256",
    "key_id": "signing-key-001",
    "signature": "base64-encoded-signature",
    "signed_at": "2024-01-15T12:30:00Z"
  },
  "certificate_chain": ["array", "of", "certificates"]
}

Descargar Herramienta Firmada¶

GET /signing/{reviewId}/download

Descarga el paquete de herramienta firmada con firma incrustada y metadatos de verificacion.

Respuesta: Descarga binaria del paquete de herramienta firmada.

Estadisticas y Monitoreo¶

Obtener Estadisticas de Flujo de Trabajo¶

GET /stats

Recupera estadisticas y metricas completas sobre el flujo de trabajo de revision.

Respuesta:

{
  "workflow_stats": {
    "total_reviews": 1250,
    "approved": 1100,
    "rejected": 125,
    "pending": 25
  },
  "performance_metrics": {
    "average_review_time": "45m",
    "auto_approval_rate": 0.78,
    "human_review_rate": 0.22
  },
  "security_insights": {
    "common_vulnerabilities": ["sql_injection", "xss", "code_injection"],
    "risk_score_distribution": {
      "low": 45,
      "medium": 35,
      "high": 20
    }
  }
}

Limitacion de Velocidad¶

La API de Revision de Herramientas implementa limitacion de velocidad por tipo de endpoint:

• Endpoints de envio: 10 solicitudes por minuto
• Endpoints de consulta: 100 solicitudes por minuto
• Endpoints de descarga: 20 solicitudes por minuto

Los encabezados de limite de velocidad se incluyen en todas las respuestas:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

Manejo de Errores¶

La API utiliza codigos de estado HTTP estandar y devuelve informacion detallada del error:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Tool source code is required",
    "details": {
      "field": "source_code",
      "reason": "missing_required_field"
    }
  }
}

Subcomandos de CLI¶

Mas alla de la superficie HTTP de larga duracion, symbi expone varios subcomandos exclusivos de CLI para operaciones puntuales. El catalogo completo esta en symbi --help; los mas relevantes para la integracion y la aplicacion de politicas son:

symbi schemapin¶

Fijacion de integridad TOFU (Trust-On-First-Use) para configuraciones de servidores MCP. Esta diseñado para invocarse desde hooks SessionStart de modo que el hash de configuracion de un servidor MCP no pueda cambiar silenciosamente entre sesiones sin que el operador lo apruebe.

# Verificar el hash fijado para uno o todos los servidores MCP en .mcp.json
symbi schemapin verify [--mcp-server <NAME>] [--config <PATH>]

# Fijar el hash de configuracion actual para un servidor
symbi schemapin pin --mcp-server <NAME> [--config <PATH>] [--force]

# Listar cada servidor fijado bajo ~/.symbiont/schemapin/mcp/
symbi schemapin list

# Eliminar un registro de fijacion
symbi schemapin unpin --mcp-server <NAME>

Las fijaciones se almacenan bajo ~/.symbiont/schemapin/mcp/ como registros JSON. verify sale con 0 si coincide, distinto de cero si no coincide o falta la fijacion — adecuado para usarse en scripts previos a la sesion.

symbi policy¶

Evaluacion de politicas Cedar contra eventos de llamada a herramientas. Lee un solo evento como JSON, decide allow / deny contra un directorio de politicas y sale con un codigo de estado adecuado para scripting.

# Evaluar un evento leido desde stdin
echo '{"principal":"Agent::\"dev\"", "action":"write", "resource":{...}}' \
  | symbi policy evaluate --stdin --policies ./policies

# Evaluar un evento leido desde un archivo
symbi policy evaluate --input event.json --policies ./policies

# Emitir solo JSON estructurado (adecuado para uso programatico)
symbi policy evaluate --stdin --policies ./policies --json

La salida predeterminada es el veredicto escueto en stdout con detalle estructurado en stderr; pase --json para colapsar todo a JSON en stdout. Esta es la misma logica de decision Cedar que el runtime usa en linea — util para pruebas de politicas en CI (shift-left) y para depurar denegaciones fuera de un runtime en ejecucion.

symbi agents-md¶

Regenera AGENTS.md a partir de los archivos agents/*.symbi actuales (los .dsl heredados tambien se reconocen). Se ejecuta automaticamente durante symbi init; invoquelo manualmente despues de agregar o editar definiciones de agentes.

symbi agents-md generate --dir . --output AGENTS.md

Primeros Pasos¶

API HTTP del Runtime¶

1. Compila el binario symbi (la feature http-api esta activa por defecto en el crate del binario):

   cargo build --release
   

2. Inicia el runtime — la API escucha en :8080 y HTTP Input en :8081:

   ./target/release/symbi up --http-bind 0.0.0.0
   

Para un proyecto con esqueleto generado y el flujo Docker recomendado, consulta Primeros Pasos.

1. Verifica que el servidor este ejecutandose:

   curl http://127.0.0.1:8080/api/v1/health
   

2. Prueba un endpoint autenticado — symbi up imprime el bearer token generado al iniciar (o configura uno explicitamente con --http.token):

   curl -H "Authorization: Bearer $SYMBI_HTTP_TOKEN" \
        http://127.0.0.1:8080/api/v1/agents
   

API de Revision de Herramientas¶

1. Obten credenciales de API de tu administrador de Symbiont
2. Envia una herramienta para revision usando el endpoint /sessions
3. Monitorea el progreso de revision via /sessions/{reviewId}
4. Descarga herramientas firmadas desde /signing/{reviewId}/download

Soporte¶

Para soporte de API y preguntas: - Revisa la documentacion de Arquitectura del Runtime - Consulta la documentacion del Modelo de Seguridad - Presenta issues en el repositorio GitHub del proyecto

Una invocacion reconciliada devuelve HTTP 409 y su resolution de operador firmada por separado; nunca devuelve una finalizacion de runtime fabricada. El historial de cron conserva el estado Reconciled, el error y la auditoria originales y el objeto de resolucion. El trabajo permanece pausado hasta que se reanude explicitamente. Consulte la reconciliacion por el operador.