API Reference
🌐 Other Languages
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:
- Runtime HTTP API - A complete API for direct runtime interaction, agent management, and workflow execution
- 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/metricsendpoints 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": "1.0.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 processready: Agent is initialized and ready for executionwaiting: Agent is queued for executionfailed: Agent execution failed or health check failedcompleted: Agent task completed successfullyterminated: 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"
}
]
}
Agent Heartbeat
POST /api/v1/agents/{id}/heartbeat
Authorization: Bearer <your-token>
Send a heartbeat from a running agent to update its health status.
Push Event to Agent
POST /api/v1/agents/{id}/events
Authorization: Bearer <your-token>
Push an external event to a running agent for event-driven execution.
System Metrics
GET /api/v1/metrics
Retrieve a comprehensive metrics snapshot covering scheduler, task manager, load balancer, and system resources.
Response (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
}
}
The metrics snapshot can also be exported to files (atomic JSON write) or OTLP endpoints using the runtime’s MetricsExporter system. See the Metrics & Telemetry section below.
Metrics & Telemetry
Symbiont supports exporting runtime metrics to multiple backends:
File Exporter
Writes metric snapshots as atomic JSON files (tempfile + rename):
use symbi_runtime::metrics::{FileMetricsExporter, MetricsExporterConfig};
let exporter = FileMetricsExporter::new("/var/lib/symbi/metrics.json");
exporter.export(&snapshot)?;
OTLP Exporter
Sends metrics to any OpenTelemetry-compatible endpoint (requires the metrics feature):
use symbi_runtime::metrics::{OtlpExporter, OtlpExporterConfig, OtlpProtocol};
let config = OtlpExporterConfig {
endpoint: "http://localhost:4317".to_string(),
protocol: OtlpProtocol::Grpc,
..Default::default()
};
Composite Exporter
Fan-out to multiple backends simultaneously — individual export failures are logged but don’t block other exporters:
use symbi_runtime::metrics::CompositeExporter;
let composite = CompositeExporter::new(vec![
Box::new(file_exporter),
Box::new(otlp_exporter),
]);
Background Collection
The MetricsCollector runs as a background thread, periodically gathering snapshots and exporting them:
use symbi_runtime::metrics::MetricsCollector;
let collector = MetricsCollector::new(exporter, interval);
collector.start();
// ... later ...
collector.stop();
Skill Scanning (ClawHavoc)
The SkillScanner inspects agent skill content for malicious patterns before loading. It ships with 40 built-in ClawHavoc defense rules across 10 attack categories:
| Category | Count | Severity | Examples |
|---|---|---|---|
| Original defense rules | 10 | Critical/Warning | pipe-to-shell, eval-with-fetch, rm-rf-pattern |
| Reverse shells | 7 | Critical | bash, nc, ncat, mkfifo, python, perl, ruby |
| Credential harvesting | 6 | High | SSH keys, AWS creds, cloud config, browser cookies, keychain |
| Network exfiltration | 3 | High | DNS tunnel, /dev/tcp, netcat outbound |
| Process injection | 4 | Critical | ptrace, LD_PRELOAD, /proc/mem, gdb attach |
| Privilege escalation | 5 | High | sudo, setuid, setcap, chown root, nsenter |
| Symlink / path traversal | 2 | Medium | symlink escape, deep path traversal |
| Downloader chains | 3 | Medium | curl save, wget save, chmod exec |
See the Security Model for the full rule list and severity model.
Usage
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);
}
}
Custom deny patterns can be added alongside the defaults:
let scanner = SkillScanner::with_custom_rules(vec![
("custom-pattern".into(), r"my_dangerous_pattern".into(),
ScanSeverity::Warning, "Custom rule description".into()),
]);
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-apiCargo feature
Feature Configuration Reference
Cloud LLM Inference (cloud-llm)
Connect to cloud LLM providers via OpenRouter for agent reasoning:
cargo build --features cloud-llm
Environment Variables:
OPENROUTER_API_KEY— Your OpenRouter API key (required)OPENROUTER_MODEL— Model to use (default:google/gemini-2.0-flash-001)
The cloud LLM provider integrates with the reasoning loop’s execute_actions() pipeline. It supports streaming responses, automatic retries with exponential backoff, and token usage tracking.
Standalone Agent Mode (standalone-agent)
Combines cloud LLM inference with Composio tool access for cloud-native agents:
cargo build --features standalone-agent
# Enables: cloud-llm + composio
Environment Variables:
OPENROUTER_API_KEY— OpenRouter API keyCOMPOSIO_API_KEY— Composio API keyCOMPOSIO_MCP_URL— Composio MCP server URL
Cedar Policy Engine (cedar)
Formal authorization using the Cedar policy language:
cargo build --features cedar
Cedar policies integrate with the reasoning loop’s Gate phase, providing fine-grained authorization decisions. See the Security Model for policy examples.
Vector Database Configuration
Symbiont ships with LanceDB as the default embedded vector backend — no external service required. For scaled deployments, Qdrant is available as an optional backend.
LanceDB (default):
[vector_db]
enabled = true
backend = "lancedb"
collection_name = "symbi_knowledge"
No additional configuration needed. Data stored locally alongside the runtime.
Qdrant (optional):
cargo build --features vector-qdrant
[vector_db]
enabled = true
backend = "qdrant"
collection_name = "symbi_knowledge"
url = "http://localhost:6333"
Environment Variables:
SYMBIONT_VECTOR_BACKEND—lancedb(default) orqdrantQDRANT_URL— Qdrant server URL (only when using Qdrant)
Advanced Reasoning Primitives (orga-adaptive)
Enable tool curation, stuck-loop detection, context pre-fetch, and scoped conventions:
cargo build --features orga-adaptive
See the orga-adaptive guide for full configuration reference.
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 parametersget_agent_status()- Retrieve detailed status with real-time execution metricsget_system_health()- Get overall system health with scheduler statisticslist_agents()- List all agents (running, queued, and completed)shutdown_agent()- Gracefully shutdown with resource cleanup and timeout handlingget_metrics()- Retrieve comprehensive system metrics including task statisticscreate_agent()- Create agents with execution mode specificationupdate_agent()- Update agent configuration with persistencedelete_agent()- Delete agent with proper cleanup of running processesexecute_agent()- Trigger execution with monitoring and health checksget_agent_history()- Retrieve detailed execution history with performance metrics
Scheduling API
All scheduling endpoints require authentication. Requires the cron feature.
List Schedules
GET /api/v1/schedules
Authorization: Bearer <your-token>
Response (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
}
]
Create Schedule
POST /api/v1/schedules
Authorization: Bearer <your-token>
Request Body:
{
"name": "daily-report",
"cron_expression": "0 0 9 * * *",
"timezone": "America/New_York",
"agent_name": "report-agent",
"policy_ids": ["policy-1"],
"one_shot": false
}
The cron_expression uses six fields: sec min hour day month weekday (optional seventh field for year).
Response (200 OK):
{
"job_id": "uuid",
"next_run": "2026-03-04T09:00:00Z",
"status": "created"
}
Update Schedule
PUT /api/v1/schedules/{id}
Authorization: Bearer <your-token>
Request Body (all fields optional):
{
"cron_expression": "0 */10 * * * *",
"timezone": "UTC",
"policy_ids": ["policy-2"],
"one_shot": true
}
Pause / Resume / Trigger Schedule
POST /api/v1/schedules/{id}/pause
POST /api/v1/schedules/{id}/resume
POST /api/v1/schedules/{id}/trigger
Authorization: Bearer <your-token>
Response (200 OK):
{
"job_id": "uuid",
"action": "paused",
"status": "ok"
}
Delete Schedule
DELETE /api/v1/schedules/{id}
Authorization: Bearer <your-token>
Response (200 OK):
{
"job_id": "uuid",
"deleted": true
}
Get Schedule History
GET /api/v1/schedules/{id}/history
Authorization: Bearer <your-token>
Response (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
}
]
}
Get Next Runs
GET /api/v1/schedules/{id}/next?count=5
Authorization: Bearer <your-token>
Response (200 OK):
{
"job_id": "uuid",
"next_runs": [
"2026-03-04T09:00:00Z",
"2026-03-05T09:00:00Z"
]
}
Scheduler Health
GET /api/v1/health/scheduler
Returns scheduler-specific health and statistics.
Channel Adapter API
All channel endpoints require authentication. Connects agents to Slack, Microsoft Teams, and Mattermost.
List Channels
GET /api/v1/channels
Authorization: Bearer <your-token>
Response (200 OK):
[
{
"id": "uuid",
"name": "slack-general",
"platform": "slack",
"status": "running"
}
]
Register Channel
POST /api/v1/channels
Authorization: Bearer <your-token>
Request Body:
{
"name": "slack-general",
"platform": "slack",
"config": {
"webhook_url": "https://hooks.slack.com/...",
"channel": "#general"
}
}
Supported platforms: slack, teams, mattermost.
Response (200 OK):
{
"id": "uuid",
"name": "slack-general",
"platform": "slack",
"status": "registered"
}
Get / Update / Delete Channel
GET /api/v1/channels/{id}
PUT /api/v1/channels/{id}
DELETE /api/v1/channels/{id}
Authorization: Bearer <your-token>
Start / Stop Channel
POST /api/v1/channels/{id}/start
POST /api/v1/channels/{id}/stop
Authorization: Bearer <your-token>
Response (200 OK):
{
"id": "uuid",
"action": "started",
"status": "ok"
}
Channel Health
GET /api/v1/channels/{id}/health
Authorization: Bearer <your-token>
Response (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
}
Identity Mappings
GET /api/v1/channels/{id}/mappings
POST /api/v1/channels/{id}/mappings
Authorization: Bearer <your-token>
Maps platform users to Symbiont identities for agent interactions.
Channel Audit Log
GET /api/v1/channels/{id}/audit
Authorization: Bearer <your-token>
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 paginationlimit(integer): Number of items per pagestatus(string): Filter by review statusauthor(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
- Ensure the runtime is built with the
http-apifeature:cargo build --features http-api - Set the authentication token for agent endpoints:
export API_AUTH_TOKEN="<your-token>" - Start the runtime server:
./target/debug/symbiont-runtime --http-api - Verify the server is running:
curl http://127.0.0.1:8080/api/v1/health - Test authenticated agent endpoint:
curl -H "Authorization: Bearer $API_AUTH_TOKEN" \ http://127.0.0.1:8080/api/v1/agents
Tool Review API
- Obtain API credentials from your Symbiont administrator
- Submit a tool for review using the
/sessionsendpoint - Monitor the review progress via
/sessions/{reviewId} - Download signed tools from
/signing/{reviewId}/download
Support
For API support and questions:
- Review the Runtime Architecture documentation
- Check the Security Model documentation
- File issues on the project’s GitHub repository