NEXUS Bridge API

REST API for the NEXUS multi-agent orchestration platform. Dispatch tasks to 12 specialized agents with governance enforcement, MCDM routing, and quality assurance built into every request.

Base URLhttp://localhost:5679

Authentication

All endpoints require Bearer token authentication. The token is configured in your vault.env file.

Authorization: Bearer $BRIDGE_TOKEN

POST /dispatch Dispatch task to an agent via MCDM routing

The primary endpoint. Accepts a task, applies governance policies, scores agents via TOPSIS/AHP, and dispatches to the optimal executor. Returns the agent response with quality score.

Request Body

Parameter	Type	Description
task	string (required)	The task description to dispatch
agent	string	Force specific agent (nexus, atlas, forge, bolt, oracle, shield, judge, scout, spark, ghost)
role	string	Agent role filter (builder, runner, executor, refactorer, security, reviewer)
context	object	Additional context for synaptic packet enrichment

Example Request

{
  "task": "Audit the authentication module for vulnerabilities",
  "agent": "shield",
  "role": "security",
  "context": {
    "priority": "high",
    "scope": "auth-gateway MCP server"
  }
}

Example Response

{
  "status": "completed",
  "agent": "shield",
  "codename": "SHIELD",
  "mcdm_score": 0.96,
  "quality_score": 0.93,
  "governance": {
    "policies_checked": 22,
    "risk_level": "MEDIUM",
    "hitl_required": false,
    "audit_signature": "Ed25519:a3f8c2..."
  },
  "result": "No vulnerabilities found in auth-gateway...",
  "synaptic_context_kb": 4.1,
  "duration_ms": 3420
}

POST /fan-out Dispatch to multiple agents simultaneously

SENTINEL fan-out: sends the same task to multiple agents in parallel and aggregates results. Useful for benchmarking, consensus, and multi-perspective analysis.

Request Body

{
  "task": "Evaluate the security posture of the bridge",
  "agents": ["shield", "forge", "oracle"],
  "merge_strategy": "best_score"  // or "consensus", "all"
}

POST /handoff Agent-to-agent context handoff

Transfers context from one agent to another with synaptic packet preservation. Enables multi-stage workflows where one agent's output feeds another's input.

Request Body

{
  "from_agent": "atlas",
  "to_agent": "forge",
  "context": { "research_summary": "..." },
  "task": "Implement based on research findings"
}

POST /approve Approve HITL-gated high-risk tasks

When a task's risk level triggers the Human-In-The-Loop gate, it enters pending_approval status. Use this endpoint to approve or reject.

Request Body

{
  "dispatch_id": "d-2026-0213-1432",
  "decision": "approve"  // or "reject"
}

GET /health System health check

Response

{
  "status": "healthy",
  "version": "3.7",
  "uptime_hours": 72.5,
  "checks": { "pass": 99, "fail": 0, "warn": 1 },
  "agents_online": 12,
  "mcp_servers": 20
}

GET /metrics Per-agent dispatch metrics and quality scores

Response

{
  "total_dispatches": 1247,
  "avg_quality": 0.92,
  "agents": {
    "shield": { "dispatches": 89, "avg_quality": 0.94 },
    "forge":  { "dispatches": 312, "avg_quality": 0.91 },
    // ... all 12 agents
  }
}

GET /agents List all registered agents and their specs

Returns the full agent registry with capabilities, cost tiers, and current status. Data sourced from agent spec manifests in governance/specs/agents/.

GET /status Current dispatch queue and pending approvals

Returns active dispatches, queued tasks, and any pending HITL approval requests.

GET /.well-known/agent.json A2A Agent Card discovery endpoint

Google A2A protocol discovery. Returns agent cards for all 12 agents, enabling interoperability with external A2A-compatible systems. No authentication required.

GET /openapi.yaml OpenAPI 3.1 specification

Returns the complete OpenAPI specification. Compatible with Swagger UI, Postman, and other API tools. Spec file: governance/specs/openapi-bridge.yaml