API Reference

Complete PIA REST API documentation

Base URL

bash

https://pia.com

For local development: http://localhost:3000

Authentication

Most API endpoints require a PIA agent token. Include it in the Authorization header:

bash

Authorization: Bearer pia_live_xxxxxxxxxxxxx

Core Endpoints

POST/api/verify

Verify an agent action against user's policy

Request Body

json

{
  "action": "SEND_EMAIL",
  "description": "Send meeting reminder to john@example.com",
  "actionData": {
    "to": "john@example.com",
    "subject": "Meeting Reminder",
    "bodyLength": 150
  }
}

Response

json

{
  "decision": "APPROVED",
  "reason": "Email to whitelisted contact approved",
  "auditLogId": "clxxx..."
}

GET/api/agent/authorize

Initiate agent authorization flow (OAuth-style)

Query Parameters

• agent_id: string (required)
• agent_name: string (required)
• permissions: comma-separated (required)
• redirect_uri: string (required)

GET/api/agent/list

List all authorized agents for the current user

Response

json

{
  "agents": [
    {
      "id": "clxxx...",
      "agentId": "email-assistant",
      "agentName": "Email Assistant",
      "permissions": ["READ_EMAIL", "SEND_EMAIL"],
      "createdAt": "2025-12-10T...",
      "expiresAt": "2026-12-10T...",
      "lastUsedAt": "2025-12-10T..."
    }
  ]
}

Error Responses

json

// 401 Unauthorized
{
  "error": "Missing or invalid Authorization header"
}

// 403 Forbidden
{
  "error": "Action not in agent permissions"
}

// 500 Internal Server Error
{
  "error": "Failed to verify action"
}