Back to Docs

API Reference

Complete reference for the APAAI REST API

REST APIhttps://api.apaai.cloud

Authentication

All API requests require authentication using an API key in the request header.

x-apaaikey: your_api_key_here
Get your API key
Go to Settings → API Keys to create and manage your API keys.

Actions

Track and manage AI agent actions

POST/actions

Propose a new action for policy evaluation.

Request Body

1{
2  "type": "send_email",
3  "actor": {
4    "kind": "agent",
5    "name": "marketing-bot",
6    "provider": "openai"
7  },
8  "target": "user@example.com",
9  "params": {
10    "subject": "Welcome!",
11    "body": "Thanks for signing up"
12  }
13}

Response

1{
2  "actionId": "act_abc123",
3  "status": "approved",
4  "policyIds": ["pol_xyz789"],
5  "decision": {
6    "status": "approved",
7    "checks": []
8  }
9}
approvedAction can proceed
pending_approvalNeeds human review
rejectedBlocked by policy
GET/actions/:id

Retrieve details of a specific action by ID.

GET/actions

List all actions for your organization.

Query Parameters

statusFilter by status (approved, pending_approval, rejected)
limitMax results (default: 50)
cursorPagination cursor

Evidence

Submit evidence to fulfill policy requirements

POST/actions/:actionId/evidence

Submit evidence checks to satisfy policy requirements for a pending action.

Request Body

1{
2  "checks": [
3    {
4      "name": "security_scan",
5      "pass": true,
6      "note": "No threats detected",
7      "meta": {
8        "scanner": "clamav",
9        "version": "1.0.0"
10      }
11    }
12  ]
13}

Example

1curl -X POST https://api.apaai.cloud/actions/act_123/evidence \
2  -H "x-apaaikey: your_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "checks": [
6      {
7        "name": "content_review",
8        "pass": true,
9        "note": "Content approved by reviewer"
10      }
11    ]
12  }'

Policies

Define rules for actions

POST/policy

Create a new policy.

Request Body

1{
2  "name": "Email Approval Required",
3  "description": "All emails require human approval",
4  "mode": "enforce",
5  "rules": [
6    {
7      "when": {
8        "actionType": "send_email"
9      },
10      "require": ["content_review"]
11    }
12  ],
13  "status": "active"
14}
Enforce Mode

Actions require manual approval before proceeding.

Observe Mode

Actions auto-approve but are logged for monitoring.

GET/policy

List all policies for your organization.

PUT/policy/:id

Update an existing policy.

DELETE/policy/:id

Archive a policy (soft delete).

Approvals

Manage pending action approvals

GET/approvals/pending

List actions awaiting manual approval.

POST/approvals/:approvalId/approve

Approve a pending action.

1curl -X POST https://api.apaai.cloud/approvals/apr_123/approve \
2  -H "x-apaaikey: your_key"
POST/approvals/:approvalId/reject

Reject a pending action.

1curl -X POST https://api.apaai.cloud/approvals/apr_123/reject \
2  -H "x-apaaikey: your_key" \
3  -H "Content-Type: application/json" \
4  -d '{"reason": "Content violates guidelines"}'

Webhooks

Receive real-time notifications

Configure webhooks in Settings → Webhooks to receive notifications when actions need approval.

Webhook Events

action.pending_approvalaction.approvedaction.rejectedaction.expired

Example Payload

1{
2  "event": "action.pending_approval",
3  "actionId": "act_abc123",
4  "type": "send_email",
5  "actor": {
6    "kind": "agent",
7    "name": "marketing-bot"
8  },
9  "params": {
10    "subject": "Welcome!",
11    "recipient_count": 1
12  },
13  "approvalUrl": "https://app.apaai.cloud/approve/act_abc123",
14  "timestamp": "2024-01-15T10:30:00Z"
15}

Error Handling

All error responses follow a consistent format:

1{
2  "error": "ERROR_CODE",
3  "message": "Human-readable description"
4}

Status Codes

400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
402Payment Required - Usage limit exceeded
404Not Found - Resource does not exist
409Conflict - Resource already exists
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Rate Limits

1,000
actions/month
Free
100,000
actions/month
Pro
Unlimited
actions/month
Enterprise

Rate Limit Headers

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

Need Help?

Quick Start
Get started in 10 minutes
Email Support
support@apaai.cloud