Base URL: https://a2ainfrastructure.com/v1

Authentication: Authorization: Bearer a2a_YOUR_KEY

Content-Type: application/json

POST/v1/evaluate

Stateless safety evaluation. Send a command, get allow/deny back. No pipeline needed. This is the core endpoint.

Request

{
  "command": "rm -rf /",           // string — the command to evaluate
  "context": "my-agent:tier-2"     // string (optional) — free-form context for Gate 2
}

Request

{
  "command": "rm -rf /",           // string — the command to evaluate
  "context": "my-agent:tier-2",    // string (optional) — free-form context for Gate 2
  "groundRules": "Block all destructive ops"  // string (optional) — custom Gate 2 rules
}

Response (blocked)

{
  "allowed": false,
  "gate1": { "allowed": false, "reason": "Gate 1 DENY: matched denylist pattern [rm\\s+-rf\\s+\\/]" },
  "gate2": null,
  "gate3": null,
  "audit_id": "evt_m1a2b3...",
  "backend": "tyga"
}

Response (allowed)

{
  "allowed": true,
  "gate1": { "allowed": true, "reason": null },
  "gate2": { "allowed": true, "reason": null },
  "gate3": { "allowed": true, "reason": null, "patterns": [] },
  "audit_id": "evt_n4c5d6...",
  "backend": "tyga"
}

Response (Gate 3 behavioral block)

{
  "allowed": false,
  "gate1": { "allowed": true, "reason": null },
  "gate2": { "allowed": true, "reason": null },
  "gate3": { "allowed": false, "reason": "Gate 3 DENY: recon-escalation", "patterns": ["recon-escalation"] },
  "audit_id": "evt_p7q8r9...",
  "backend": "tyga"
}

Pipelines

Create Pipeline

POST /v1/pipelines
{
  "name": "my-pipeline",
  "slug": "my-pipeline"          // optional — auto-generated from name
}

// Response: 201
{ "id": "pipe_...", "name": "my-pipeline", "slug": "my-pipeline", ... }

Configure Firewall Gates

After creating a pipeline, configure its firewall via PATCH or the dashboard UI.

PATCH /v1/pipelines/:id
{
  "firewallConfig": {
    "gate2Enabled": true,         // enable LLM judge (Pro+ required)
    "groundRules": "Block destructive filesystem ops, network exfiltration, credential access.",
    "denylistPatterns": [         // custom Gate 1 regex patterns
      "iptables\\s+-F",
      "docker\\s+system\\s+prune",
      "FLUSHALL",
      "rm\\s+-rf\\s+/"
    ]
  }
}

{
  "firewallConfig": {
    "gate2Enabled": true,
    "groundRules": "Infrastructure remediation. Experts: overlay-network, ollama, load-balancer. Safety tiers 0-3.",
    "denylistPatterns": [
      "iptables\\s+-F(?!\\s+--table)",   // flush without --table
      "docker\\s+service\\s+rm\\s+\\*",   // wildcard service delete
      "--replicas\\s+0\\b",              // scale to zero = delete
      "swarm\\s+leave\\s+--force"         // force leave swarm
    ]
  }
}

{
  "firewallConfig": {
    "gate2Enabled": true,
    "groundRules": "AI support chat. Block prompt injection, internal architecture extraction.",
    "denylistPatterns": [
      "ignore.*instructions",
      "ignore.*previous",
      "system\\s*prompt",
      "reveal.*prompt",
      "list.*endpoint",
      "what.*database.*schema"
    ]
  }
}

{
  "firewallConfig": {
    "gate2Enabled": true,
    "groundRules": "Casino bots. Block collusion, bot identity reveals, extreme bets. Gambling compliance.",
    "denylistPatterns": [
      "bet_amount\\s*[:<]\\s*(\\d{6,})",  // extreme bets
      "collude",
      "target_player",
      "I am an AI",
      "I'm a bot",
      "house edge"
    ]
  }
}

Tasks

Submit Task

POST /v1/pipelines/:id/tasks
{
  "command": "python train_model.py --epochs 50"
}

// Response: 201
{
  "taskId": "tsk_8f3a...",
  "status": "running",
  "firewallResult": {
    "gate1": { "allowed": true, "reason": null },
    "gate2": { "allowed": true, "reason": "ML training, no system access" }
  }
}

Task States

PENDING → VALIDATING → APPROVED → EXECUTING → COMPLETED | FAILED | ABORTED

Workspaces

Create Workspace with Scoped Agents

POST /v1/workspaces
{
  "name": "production-orchestration",
  "scopeManifest": {
    "agents": [
      { "role": "architect", "name": "planner", "scope": ["plan", "delegate", "review"] },
      { "role": "expert", "name": "builder", "scope": ["docker.build", "git.pull"] },
      { "role": "expert", "name": "tester", "scope": ["pytest", "read:reports/"] }
    ]
  }
}

Update Scope Manifest

PATCH /v1/workspaces/:id
{
  "scopeManifest": { "agents": [ ... ] }
}

{
  "name": "monitoring-cluster",
  "scopeManifest": {
    "agents": [
      { "role": "architect", "name": "architect",
        "scope": ["plan", "correlate", "decide", "review"] },
      { "role": "expert", "name": "redis",
        "scope": ["redis.metrics", "redis.diagnostics", "redis.remediate:tier-0,1"] },
      { "role": "expert", "name": "mongodb",
        "scope": ["mongodb.metrics", "mongodb.diagnostics", "mongodb.remediate:tier-0,1"] },
      { "role": "expert", "name": "web",
        "scope": ["web.metrics", "web.diagnostics", "web.remediate:tier-0,1"] },
      { "role": "expert", "name": "dns",
        "scope": ["dns.metrics", "dns.diagnostics"] }  // diagnose only, no remediation
    ]
  }
}
// Redis expert can't restart MongoDB. DNS expert can only diagnose.
// Architect plans but never executes directly.

{
  "name": "tax-advisory",
  "scopeManifest": {
    "agents": [
      { "role": "architect", "name": "tax-architect",
        "scope": ["classify", "delegate", "merge", "review"] },
      { "role": "expert", "name": "income-tax", "scope": ["income-tax.*"] },
      { "role": "expert", "name": "crypto-tax", "scope": ["crypto-tax.*"] },
      { "role": "expert", "name": "corporate-tax", "scope": ["corporate-tax.*"] },
      { "role": "expert", "name": "expat-tax",
        "scope": ["expat-tax.*", "cross-border.*"] },  // can query across domains
      { "role": "expert", "name": "document-generator",
        "scope": ["tool.document.*"] }  // read-only tool, can't override advice
    ]
  }
}
// Crypto expert can't answer pension questions.
// Expat expert can query income + corporate for cross-border advice.
// Tool agents can read but not override expert analysis.

{
  "name": "npc-engine",
  "scopeManifest": {
    "agents": [
      { "role": "architect", "name": "npc-conductor", "scope": ["plan", "delegate"] },
      { "role": "expert", "name": "combat", "scope": ["combat.*", "damage.*"] },
      { "role": "expert", "name": "trade", "scope": ["trade.*", "price.*", "inventory.*"] },
      { "role": "expert", "name": "quest", "scope": ["quest.*", "reward.*"] },
      { "role": "expert", "name": "social", "scope": ["reputation.*", "gossip.*"] }
    ]
  }
}
// Combat agent can't set prices. Trade agent can't alter quests.
// Social agent can't override combat difficulty.

Channels

Create Channel with Policy

POST /v1/channels
{
  "name": "agent-messaging",
  "policy": {
    "maxMessageSize": 50000,
    "allowedTopics": ["diagnostic", "remediation", "alert"]
  }
}

Update Policy

PATCH /v1/channels/:id
{
  "policy": {
    "maxMessageSize": 100000,
    "allowedTopics": ["diagnostic", "remediation", "alert", "audit"]
  }
}

{
  "name": "monitoring-bus",
  "policy": {
    "maxMessageSize": 50000,
    "allowedTopics": ["dispatch", "report", "remediate", "alert"]
  }
}
// HMAC-signed: no agent can spoof another's findings.
// Credentials stripped from inter-agent messages.
// Full transcript audit for post-incident forensics.

{
  "name": "bot-chat-table",
  "policy": {
    "maxMessageSize": 500,      // short messages only
    "allowedTopics": ["table_chat", "emote"]
  }
}
// Bot can never reveal it's AI, discuss house strategy,
// or use language that violates gambling regulations.
// Every message recorded for regulator audit.

{
  "name": "tax-expert-comms",
  "policy": {
    "maxMessageSize": 50000,
    "allowedTopics": ["tax_query", "cross_domain", "merge_response", "disclaimer"]
  }
}
// Raw rule IDs and confidence scores stripped from inter-expert messages.
// Merge step audited in OCSF — which experts, which rules, which jurisdictions.
// One manipulated merge = regulatory action, so every step is logged.

Usage

Response

{
  "plan": "pro",
  "usage": { "tasks": 1247 },
  "limits": {
    "maxPipelines": 10,
    "maxWorkspaces": 10,
    "maxChannels": 10,
    "maxTasksPerMonth": 25000,
    "features": {
      "dualGateFirewall": true,
      "ocsfAudit": true,
      "webhooks": true
    }
  }
}

Authentication

All API requests require a Bearer token with an a2a_ prefixed API key.

curl -X POST https://a2ainfrastructure.com/v1/evaluate \
  -H "Authorization: Bearer a2a_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo hello"}'

API Key Permissions

Errors

Workspace Agents & Scope Enforcement

Manage agents within workspaces. Each agent has a role (architect/expert/observer) and scope rules that control what commands they can execute.

Add Agent

POST /v1/workspaces/:id/agents
{
  "name": "overlay-network",
  "role": "expert",                   // architect | expert | observer
  "scope": ["docker.network.*", "iptables.list", "ip.route"]
}

Enforce Scope

POST /v1/workspaces/:id/enforce
{
  "agent": "overlay-network",
  "command": "docker network inspect bridge"
}

// Response: allowed
{ "allowed": true, "reason": null, "agent": { "name": "overlay-network", "role": "expert" } }

// Response: blocked (scope violation)
{ "allowed": false, "reason": "Scope violation: \"systemctl stop docker\" not permitted by [docker.network.*, iptables.list]" }

Channel Messages (HMAC-Signed)

Send HMAC-SHA256 signed messages between agents through channels. Messages are policy-filtered (blocks sensitive data) and persisted for audit.

Send Message (HMAC Envelope)

POST /v1/channels/:id/messages
{
  "payload": { "from": "agent-1", "to": "agent-2", "content": "Task complete", "topic": "status" },
  "ts": "1715270400",                // Unix timestamp (seconds)
  "sig": "a3f2c1..."                 // HMAC-SHA256 of ts:payload with channel secret
}

// Response: 201 (allowed)
{ "message_id": "...", "from": "agent-1", "to": "agent-2", "hmacVerified": true, "contentHash": "sha256..." }

// Response: 403 (policy block — e.g., contains API key)
{ "error": "Message blocked by channel policy", "reason": "Blocked: contains sensitive data" }

// Response: 401 (HMAC verification failed)
{ "error": "HMAC verification failed: Envelope expired" }

Message History

GET /v1/channels/:id/messages?limit=50

{ "messages": [{ "from": "agent-1", "content": "Task complete", "hmacVerified": true, "createdAt": "..." }, ...] }

Semantic Search (Vector)

Search blocked attack patterns and audit trail using semantic similarity. Powered by Redis Stack HNSW with MiniLM-L6-v2 embeddings (384-dim, cosine).

GET /v1/search/attacks?q=privilege%20escalation&k=5

{ "results": [{ "key": "a2a:attacks:123", "score": 0.92, "document": { "text": "sudo -l", "gate": "gate3", "reason": "recon-escalation" } }, ...] }

GET /v1/search/audit?q=credential%20access&k=10

{ "results": [{ "key": "a2a:audit:456", "score": 0.88, "document": { "command": "cat /etc/shadow", "allowed": false } }, ...] }

Gate 3: Behavioral Firewall

Detects multi-command attack sequences using a Redis sliding window. Runs after Gate 1 + Gate 2 for Pro+ plans.

Detected Patterns

Outbound Webhooks

Register webhook endpoints to receive real-time events. Payloads are HMAC-SHA256 signed with your webhook secret.

Event Types

Payload Format

// Headers
X-A2A-Signature: sha256=abc123...    // HMAC-SHA256 of body with your webhook secret
X-A2A-Event: evaluation.blocked
X-A2A-Delivery: uuid

// Body
{
  "event": "evaluation.blocked",
  "timestamp": "2026-05-10T...",
  "data": { "command": "rm -rf /", "allowed": false, "gate1": { ... } }
}