API Reference

Complete reference for the Agent Action Firewall REST API. All endpoints require authentication via API key.

🚀

Try it live!

Use our interactive API Playground to test endpoints directly in your browser.

Base URL

https://api.agentactionfirewall.com

Authentication

Agent endpoints use an API key in the X-Agent-Key header. Admin endpoints require a Supabase JWT in the Authorization header:

Bash

# Agent endpoints (e.g. POST /v1/actions)
X-Agent-Key: YOUR_API_KEY
X-Agent-Id: your-agent-id

# Admin endpoints (e.g. /admin/*, /v1/dry-run)
Authorization: Bearer $SUPABASE_JWT

Actions API

Submit Action

Submit a new action for policy evaluation.

HTTP

POST /v1/actions
Content-Type: application/json

{
  "tool": "http_proxy",
  "operation": "POST",
  "params": {
    "url": "https://api.example.com/endpoint",
    "method": "POST",
    "body": { "key": "value" }
  },
  "idempotency_key": "optional-unique-key"
}

Response

JSON

{
  "id": "act_abc123",
  "status": "allowed",
  "decision": {
    "decision": "allow",
    "reason": "Action matches allowed pattern",
    "risk_level": "low"
  },
  "created_at": "2024-12-25T12:00:00Z"
}

Status Values

allowed - Action approved by policy, proceed with execution
denied - Action blocked by policy
pending_approval - Action requires human approval

Get Action

Retrieve the current status of an action.

HTTP

GET /v1/actions/:id

Response

JSON

{
  "id": "act_abc123",
  "status": "succeeded",
  "tool": "http_proxy",
  "operation": "POST",
  "decision": {
    "decision": "allow",
    "reason": "Action matches allowed pattern",
    "risk_level": "low"
  },
  "execution": {
    "id": "exec_xyz789",
    "status": "succeeded",
    "attempts": 1,
    "started_at": "2024-12-25T12:00:01Z",
    "completed_at": "2024-12-25T12:00:02Z",
    "result": { "statusCode": 200 }
  },
  "created_at": "2024-12-25T12:00:00Z",
  "updated_at": "2024-12-25T12:00:02Z"
}

List Actions

List actions with optional filtering and pagination.

HTTP

GET /v1/actions?status=pending_approval&limit=10&offset=0

Approvals API

List Pending Approvals

HTTP

GET /v1/approvals?status=pending

Approve Action

HTTP

POST /v1/approvals/:id/approve
Content-Type: application/json

{
  "comment": "Approved for production deployment"
}

Deny Action

HTTP

POST /v1/approvals/:id/deny
Content-Type: application/json

{
  "reason": "Not authorized for this environment"
}

Policies API

List Policies

HTTP

GET /admin/policies

Create Policy

HTTP

POST /admin/policies
Content-Type: application/json

{
  "name": "Block External APIs",
  "description": "Block all external API calls except whitelisted domains",
  "content": "package firewall\n\ndefault allow = false\n...",
  "priority": 100
}

Simulate Policy

Test a policy against sample input without saving.

HTTP

POST /admin/policies/:id/simulate
Content-Type: application/json

{
  "input": {
    "action": {
      "tool": "http_proxy",
      "operation": "GET",
      "params": { "url": "https://api.github.com" }
    }
  }
}

Audit API

List Audit Events

HTTP

GET /admin/audit?start_date=2024-12-01&end_date=2024-12-31

Export Proof Pack

HTTP

GET /admin/audit/actions/:id/proof-pack

Error Responses

All errors follow a consistent format:

JSON

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": {
    "field": "tool",
    "issue": "Required field missing"
  }
}

Common Error Codes

400 - Bad Request: Invalid parameters
401 - Unauthorized: Invalid or missing API key
403 - Forbidden: Insufficient permissions
404 - Not Found: Resource does not exist
429 - Too Many Requests: Rate limit exceeded
500 - Internal Server Error

Rate Limits

Endpoint Type	Limit	Window
Actions	100 requests	1 minute
Admin	50 requests	1 minute
Webhooks	1000 requests	1 minute

NLP Policies API

NLP policies use LLM-based semantic analysis for content safety, PII detection, and intent classification. Learn more about NLP policies.

List NLP Policies

HTTP

GET /admin/nlp-policies

Create NLP Policy

HTTP

POST /admin/nlp-policies
Content-Type: application/json

{
  "name": "Content Safety Check",
  "description": "Detect harmful content in agent actions",
  "type": "content_safety",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "threshold": 0.7,
  "enabled": true
}

Policy Types

content_safety - Detect harmful, toxic, or inappropriate content
pii_detection - Identify personally identifiable information
intent_classification - Classify agent intent for suspicious behavior
custom - Custom prompt for domain-specific analysis

Get NLP Policy

HTTP

GET /admin/nlp-policies/:id

Update NLP Policy

HTTP

PATCH /admin/nlp-policies/:id
Content-Type: application/json

{
  "threshold": 0.8,
  "enabled": false
}

Delete NLP Policy

HTTP

DELETE /admin/nlp-policies/:id

Test NLP Policy

Test a policy against sample content without affecting real actions.

HTTP

POST /admin/nlp-policies/:id/test
Content-Type: application/json

{
  "content": "Please send $5000 to account 123456789 for John Smith"
}

Response

JSON

{
  "policy_id": "nlp_abc123",
  "decision": "deny",
  "risk_score": 0.85,
  "reasoning": "Content contains potential PII including account numbers and personal names.",
  "details": {
    "detected_issues": ["account_number", "personal_name"],
    "confidence": 0.92
  },
  "latency_ms": 245
}

Evaluate Content (Batch)

Evaluate content against all enabled NLP policies.

HTTP

POST /admin/nlp-policies/evaluate
Content-Type: application/json

{
  "content": "Action content to evaluate",
  "action_id": "optional-action-reference"
}

Get Policy Templates

List available pre-built NLP policy templates.

HTTP

GET /admin/nlp-policies/templates

SDKs

TypeScript SDK - Official TypeScript/JavaScript SDK