Skip to main content

API Reference

Complete API documentation for CitadelMesh components

Overview​

This section provides comprehensive API documentation for all CitadelMesh components, including:

  • Protobuf Schemas - Message type definitions and usage
  • OPA Policies - Policy rules and evaluation APIs
  • MCP Tools - Available MCP server tools and parameters
  • Agent Runtime - BaseAgent, EventBus, and Telemetry APIs
  • REST APIs - Gateway and microservice endpoints

Protocol APIs​

Safety & Policy APIs​

Agent APIs​

MCP Tool APIs​

Service APIs​

API Conventions​

Authentication​

All service-to-service communication uses SPIFFE/SPIRE mTLS:

from spiffe import WorkloadApiClient

# Fetch workload SVID
client = WorkloadApiClient('/run/spire/sockets/agent.sock')
svid = client.fetch_x509_svid()

# Use SVID for mTLS
response = requests.post(
    'https://safety-service:5100/api/policy',
    cert=(svid.cert, svid.private_key),
    verify=svid.bundle
)

Request Format​

All API requests follow CloudEvents specification:

{
  "specversion": "1.0",
  "type": "citadel.command.door_unlock",
  "source": "spiffe://citadel.mesh/security-agent",
  "id": "a7b3c9d4-e8f2-4a5b-9c7d-1e3f5a8b2c6d",
  "time": "2025-10-01T14:23:45Z",
  "datacontenttype": "application/protobuf",
  "data": "<base64-encoded-protobuf>"
}

Response Format​

All responses include:

  • HTTP status code (200, 400, 403, 500)
  • JSON or Protobuf payload
  • Trace context headers
{
  "success": true,
  "data": {...},
  "timestamp": "2025-10-01T14:23:45Z",
  "trace_id": "a7b3c9d4-e8f2-4a5b-9c7d-1e3f5a8b2c6d"
}

Error Handling​

Errors follow standard format:

{
  "error": {
    "code": "POLICY_DENIED",
    "message": "Door unlock denied by policy",
    "details": {
      "policy_path": "citadel/security/allow_door_unlock",
      "reason": "Outside allowed hours (6 AM - 10 PM)",
      "timestamp": "2025-10-01T23:15:30Z"
    }
  }
}

Rate Limiting​

  • Policy evaluations: 100 requests/second per agent
  • MCP tool calls: 10 requests/second per tool
  • Gateway API: 1000 requests/second total

Code Generation​

Protobuf Code Generation​

Generate client code in your language:

Python:

python -m grpc_tools.protoc \
  --python_out=. \
  --grpc_python_out=. \
  --proto_path=proto \
  proto/citadel/v1/*.proto

TypeScript:

protoc \
  --plugin=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=src/generated \
  --proto_path=proto \
  proto/citadel/v1/*.proto

.NET:

dotnet add package Grpc.Tools
# Then reference .proto files in .csproj

OpenAPI/Swagger​

REST API specifications available at:

  • Gateway API: http://localhost:7070/swagger
  • Safety Service: http://localhost:5100/swagger

Testing APIs​

Using curl​

# Test policy evaluation
curl -X POST http://localhost:5100/api/safety/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "path": "citadel/security/allow_door_unlock",
    "input": {
      "role": "security_officer",
      "time": 14,
      "door_zone": "lobby"
    }
  }'

Using Python​

import requests

response = requests.post(
    'http://localhost:5100/api/safety/evaluate',
    json={
        'path': 'citadel/security/allow_door_unlock',
        'input': {
            'role': 'security_officer',
            'time': 14,
            'door_zone': 'lobby'
        }
    }
)

print(response.json())

Using TypeScript​

const response = await fetch('http://localhost:5100/api/safety/evaluate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    path: 'citadel/security/allow_door_unlock',
    input: {
      role: 'security_officer',
      time: 14,
      door_zone: 'lobby'
    }
  })
});

const result = await response.json();
console.log(result);

Versioning​

APIs follow semantic versioning:

  • Protocol version: v1 (in proto/citadel/v1/)
  • REST API version: v1 (in /api/v1/ paths)
  • Breaking changes: Require new major version
  • Backward compatibility: Maintained within major version

SDK Support​

Official SDKs​

  • Python SDK: citadelmesh-sdk (PyPI)
  • .NET SDK: CitadelMesh.Client (NuGet)
  • TypeScript SDK: @citadelmesh/client (npm)

Installation​

# Python
pip install citadelmesh-sdk

# .NET
dotnet add package CitadelMesh.Client

# TypeScript
npm install @citadelmesh/client

Support & Feedback​

🏰 Explore the API reference to integrate with CitadelMesh.

Last updated: October 2025