API Reference

API Reference

REST API

All API routes use the /api/v1/ prefix.

Health Check

GET /api/health

Returns the service health status.

MCP Endpoint

POST /api/mcp

MCP (Model Context Protocol) endpoint for Agent communication.

MCP Well-Known

GET /api/mcp/.well-known

Returns MCP server capabilities and supported protocols.

Governance Decision

POST /api/v1/govern

Submit a governance decision request. Returns ALLOW/DENY/ASK_USER/DEFER.

Request Body:

{
  "action": "string",
  "agent_id": "string",
  "context": {},
  "safety_level": "development|staging|production"
}

Response:

{
  "decision": "ALLOW|DENY|ASK_USER|DEFER",
  "confidence": 0.95,
  "reason": "string",
  "policy_path": ["Rule", "Mode", "SafetyGate"]
}

---

MCP Protocol

Tools

MAREF exposes governance tools via MCP:

Tool	Description
govern	Submit governance decision
get_status	Get current governance state
list_agents	List registered agents
get_trust_score	Get agent trust score

Resources

Resource Template	Description
maref://audit/{id}	Audit log entry
maref://agent/{id}	Agent configuration
maref://trust/{id}	Trust score history

---

A2A Protocol

Agent Cards

MAREF agents publish standardized capability cards:

{
  "agent_id": "string",
  "name": "string",
  "capabilities": ["governance", "orchestration", "execution"],
  "trust_state": "QIAN",
  "version": "0.30.0"
}

Message Format

{
  "message_id": "uuid",
  "from": "agent_id",
  "to": "agent_id",
  "type": "task|response|heartbeat",
  "payload": {},
  "timestamp": "ISO8601"
}

---

Sidecar API

Observability Endpoints

Endpoint	Description
GET /metrics	Prometheus metrics export
GET /traces	OpenTelemetry trace data
GET /logs	Structured audit logs

---

← Back to Home