API Reference

Base URL: https://api.apaaiprotocol.org

Authentication

All requests require an API key in the header:

x-apaaikey: your_api_key_here

Get your API key from Settings → API Keys.

Actions

Create Action

Track a new action from your AI agent.

POST /actions

Body:

{
  "type": "string",           // Required: Action type (e.g., "send_email")
  "actor": {
    "kind": "agent" | "user" | "system",  // Required
    "name": "string",          // Required: Agent/user name
    "provider": "string"       // Optional: AI provider (e.g., "openai")
  },
  "target": "string",          // Optional: Target resource
  "params": {}                 // Optional: Action parameters
}

Response:

{
  "actionId": "string",
  "status": "approved" | "requires_approval" | "rejected",
  "policyIds": ["string"],     // Matched policy IDs
  "decision": {
    "status": "string",
    "checks": ["string"]       // Required evidence checks
  }
}

Get Action

Retrieve details of a specific action.

GET /actions/:id

List Actions

Get all actions for your organization.

GET /actions?status=pending&limit=50

Query Parameters:

• status (optional): Filter by status
• limit (optional): Max results (default: 50)

Evidence

Submit Evidence

Add evidence to support an action.

POST /actions/:actionId/evidence

Body:

{
  "checks": [
    {
      "name": "string",         // Required: Check name
      "pass": boolean,          // Required: Did check pass?
      "note": "string",         // Optional: Additional context
      "meta": {}                // Optional: Metadata
    }
  ]
}

Example:

curl -X POST https://api.apaaiprotocol.org/actions/act_123/evidence \
  -H "x-apaaikey: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "checks": [
      {
        "name": "security_scan",
        "pass": true,
        "note": "No threats detected"
      }
    ]
  }'

Policies

Create Policy

Define rules for action approval.

POST /policy

Body:

{
  "name": "string",            // Required
  "description": "string",     // Optional
  "mode": "enforce" | "observe",  // Required
  "rules": [
    {
      "when": {
        "actionType": "string"  // Match actions of this type
      },
      "require": ["string"]    // Optional: Required evidence checks
    }
  ],
  "status": "active" | "archived"  // Optional: default "active"
}

Modes:

• enforce: Actions require manual approval
• observe: Actions auto-approve (monitoring only)

Example:

curl -X POST https://api.apaaiprotocol.org/policy \
  -H "x-apaaikey: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Approval Required",
    "mode": "enforce",
    "rules": [
      {
        "when": { "actionType": "send_email" },
        "require": ["content_review"]
      }
    ]
  }'

List Policies

Get all policies for your organization.

GET /policy

Update Policy

Update an existing policy.

PUT /policy/:id

Approvals

List Pending Approvals

Get actions requiring manual approval.

GET /approvals/pending

Approve Action

Approve a pending action.

POST /approvals/:approvalId/approve

Reject Action

Reject a pending action.

POST /approvals/:approvalId/reject

Error Responses

All endpoints return standard error formats:

{
  "error": "ERROR_CODE",
  "message": "Human-readable message"
}

Common Error Codes:

• 401: Invalid or missing API key
• 402: Usage limit exceeded
• 404: Resource not found
• 429: Rate limit exceeded
• 500: Server error

Rate Limits

• Free tier: 1,000 actions/month
• Pro tier: 100,000 actions/month
• Enterprise: Unlimited

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Need help? support@apaaiprotocol.org