API Reference

🌐 Other Languages

English 中文简体 Español Português 日本語 Deutsch

This document provides comprehensive documentation for the Symbiont runtime APIs. The Symbiont project exposes two distinct API systems designed for different use cases and development stages.

Overview

Symbiont offers two API interfaces:

  1. Runtime HTTP API - A complete API for direct runtime interaction, agent management, and workflow execution
  2. Tool Review API (Production) - A comprehensive, production-ready API for AI-driven tool review and signing workflows

Runtime HTTP API

The Runtime HTTP API provides direct access to the Symbiont runtime for workflow execution, agent management, and system monitoring. All endpoints are fully implemented and production-ready when the http-api feature is enabled.

Base URL 

http://127.0.0.1:8080/api/v1

Authentication

Agent management endpoints require Bearer token authentication. Set the API_AUTH_TOKEN environment variable and include the token in the Authorization header:

Authorization: Bearer <your-token>

Protected Endpoints:

  • All /api/v1/agents/* endpoints require authentication
  • /api/v1/health, /api/v1/workflows/execute, and /api/v1/metrics endpoints do not require authentication

Available Endpoints

Health Check 

GET /api/v1/health

Returns the current system health status and basic runtime information.

Response (200 OK):

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

Response (500 Internal Server Error):

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

Available Endpoints

Workflow Execution 

POST /api/v1/workflows/execute

Execute a workflow with specified parameters.

Request Body:

{
  "workflow_id": "string",
  "parameters": {},
  "agent_id": "optional-agent-id"
}

Response (200 OK):

{
  "result": "workflow execution result"
}

Agent Management

All agent management endpoints require authentication via the Authorization: Bearer <token> header.

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

Retrieve a list of all active agents in the runtime.

Response (200 OK):

[
  "agent-id-1",
  "agent-id-2",
  "agent-id-3"
]
Get Agent Status 
GET /api/v1/agents/{id}/status
Authorization: Bearer <your-token>

Get detailed status information for a specific agent including real-time execution metrics.

Response (200 OK):

{
  "agent_id": "uuid",
  "state": "running|ready|waiting|failed|completed|terminated",
  "last_activity": "2024-01-15T10:30:00Z",
  "scheduled_at": "2024-01-15T10:00:00Z",
  "resource_usage": {
    "memory_usage": 268435456,
    "cpu_usage": 15.5,
    "active_tasks": 1
  },
  "execution_context": {
    "execution_mode": "ephemeral|persistent|scheduled|event_driven",
    "process_id": 12345,
    "uptime": "00:15:30",
    "health_status": "healthy|unhealthy"
  }
}

New Agent States:

  • running: Agent is actively executing with a running process
  • ready: Agent is initialized and ready for execution
  • waiting: Agent is queued for execution
  • failed: Agent execution failed or health check failed
  • completed: Agent task completed successfully
  • terminated: Agent was gracefully or forcibly terminated
Create Agent 
POST /api/v1/agents
Authorization: Bearer <your-token>

Create a new agent with the provided configuration.

Request Body:

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

Response (200 OK):

{
  "id": "uuid",
  "status": "created"
}
Update Agent 
PUT /api/v1/agents/{id}
Authorization: Bearer <your-token>

Update an existing agent’s configuration. At least one field must be provided.

Request Body:

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

Response (200 OK):

{
  "id": "uuid",
  "status": "updated"
}
Delete Agent 
DELETE /api/v1/agents/{id}
Authorization: Bearer <your-token>

Delete an existing agent from the runtime.

Response (200 OK):

{
  "id": "uuid",
  "status": "deleted"
}
Execute Agent 
POST /api/v1/agents/{id}/execute
Authorization: Bearer <your-token>

Trigger execution of a specific agent.

Request Body:

{}

Response (200 OK):

{
  "execution_id": "uuid",
  "status": "execution_started"
}
Get Agent Execution History 
GET /api/v1/agents/{id}/history
Authorization: Bearer <your-token>

Retrieve the execution history for a specific agent.

Response (200 OK):

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

System Metrics 

GET /api/v1/metrics

Retrieve comprehensive system performance metrics.

Response (200 OK):

{
  "system": {
    "uptime_seconds": 3600,
    "memory_usage": "75%",
    "cpu_usage": "45%"
  },
  "agents": {
    "total": 5,
    "active": 3,
    "idle": 2
  }
}

Server Configuration

The Runtime HTTP API server can be configured with the following options:

  • Default bind address: 127.0.0.1:8080
  • CORS support: Configurable for development
  • Request tracing: Enabled via Tower middleware
  • Feature gate: Available behind http-api Cargo feature

Data Structures

Core Types 

// 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>
}

Runtime Provider Interface

The API implements a RuntimeApiProvider trait with the following enhanced methods:

  • execute_workflow() - Execute a workflow with given parameters
  • get_agent_status() - Retrieve detailed status with real-time execution metrics
  • get_system_health() - Get overall system health with scheduler statistics
  • list_agents() - List all agents (running, queued, and completed)
  • shutdown_agent() - Gracefully shutdown with resource cleanup and timeout handling
  • get_metrics() - Retrieve comprehensive system metrics including task statistics
  • create_agent() - Create agents with execution mode specification
  • update_agent() - Update agent configuration with persistence
  • delete_agent() - Delete agent with proper cleanup of running processes
  • execute_agent() - Trigger execution with monitoring and health checks
  • get_agent_history() - Retrieve detailed execution history with performance metrics

New Scheduler Features

Real Task Execution:

  • Process spawning with secure execution environments
  • Resource monitoring (memory, CPU) with 5-second intervals
  • Health checks and automatic failure detection
  • Support for ephemeral, persistent, scheduled, and event-driven execution modes

Graceful Shutdown:

  • 30-second graceful termination period
  • Force termination for unresponsive processes
  • Resource cleanup and metrics persistence
  • Queue cleanup and state synchronization

Enhanced Context Management

Advanced Search Capabilities:

{
  "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
}

Importance Calculation:

  • Multi-factor scoring with access frequency, recency, and user feedback
  • Memory type weighting and age decay factors
  • Trust score calculation for shared knowledge

Access Control Integration:

  • Policy engine connected to context operations
  • Agent-scoped access with secure boundaries
  • Knowledge sharing with granular permissions

Tool Review API (Production)

The Tool Review API provides a complete workflow for securely reviewing, analyzing, and signing MCP (Model Context Protocol) tools using AI-driven security analysis with human oversight capabilities.

Base URL 

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

Authentication

All endpoints require Bearer JWT authentication:

Authorization: Bearer <your-jwt-token>

Core Workflow

The Tool Review API follows this request/response flow:

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

Review Sessions

Submit Tool for Review 
POST /sessions

Submits an MCP tool for security review and analysis.

Request Body:

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

Response:

{
  "review_id": "uuid",
  "status": "submitted",
  "created_at": "2024-01-15T10:30:00Z"
}
List Review Sessions 
GET /sessions

Retrieves a paginated list of review sessions with optional filtering.

Query Parameters:

  • page (integer): Page number for pagination
  • limit (integer): Number of items per page
  • status (string): Filter by review status
  • author (string): Filter by tool author

Response:

{
  "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
  }
}
Get Review Session Details 
GET /sessions/{reviewId}

Retrieves detailed information about a specific review session.

Response:

{
  "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"
}

Security Analysis

Get Analysis Results 
GET /analysis/{analysisId}

Retrieves detailed security analysis results for a specific analysis.

Response:

{
  "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"
}

Human Review Workflow

Get Review Queue 
GET /review/queue

Retrieves items pending human review, typically high-risk tools requiring manual inspection.

Response:

{
  "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"
  }
}
Submit Review Decision 
POST /review/{reviewId}/decision

Submits a human reviewer’s decision on a tool review.

Request Body:

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

Response:

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

Tool Signing

Get Signing Status 
GET /signing/{reviewId}

Retrieves the signing status and signature information for a reviewed tool.

Response:

{
  "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"]
}
Download Signed Tool 
GET /signing/{reviewId}/download

Downloads the signed tool package with embedded signature and verification metadata.

Response: Binary download of the signed tool package.

Statistics & Monitoring

Get Workflow Statistics 
GET /stats

Retrieves comprehensive statistics and metrics about the review workflow.

Response:

{
  "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
    }
  }
}

Rate Limiting

The Tool Review API implements rate limiting per endpoint type:

  • Submission endpoints: 10 requests per minute
  • Query endpoints: 100 requests per minute
  • Download endpoints: 20 requests per minute

Rate limit headers are included in all responses:

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

Error Handling

The API uses standard HTTP status codes and returns detailed error information:

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

Getting Started

Runtime HTTP API

  1. Ensure the runtime is built with the http-api feature: 
    cargo build --features http-api
  2. Set the authentication token for agent endpoints: 
    export API_AUTH_TOKEN="your-secret-token"
  3. Start the runtime server: 
    ./target/debug/symbiont-runtime --http-api
  4. Verify the server is running: 
    curl http://127.0.0.1:8080/api/v1/health
  5. Test authenticated agent endpoint: 
    curl -H "Authorization: Bearer your-secret-token" \
     http://127.0.0.1:8080/api/v1/agents

Tool Review API

  1. Obtain API credentials from your Symbiont administrator
  2. Submit a tool for review using the /sessions endpoint
  3. Monitor the review progress via /sessions/{reviewId}
  4. Download signed tools from /signing/{reviewId}/download

Support

For API support and questions: