Agents

All endpoints require a Bearer token (Authorization: Bearer aira_live_xxxxx) unless marked as public. Base URL: https://api.airaproof.com/api/v1

Register Agent

POST /api/v1/agents
Authorization: Bearer aira_live_xxxxx

Registers a new agent identity. The agent_slug becomes the permanent identifier and cannot be changed after creation.

Request Body

Field	Type	Required	Description
`agent_slug`	string	Yes	Unique slug (lowercase alphanumeric and hyphens only, e.g. `claims-processor`)
`name`	string	Yes	Human-readable name
`description`	string	No	What this agent does
`capabilities`	string[]	No	List of declared capabilities (e.g. `["tool_call", "transaction", "communication"]`)
`metadata`	object	No	Arbitrary key-value metadata

Example Request

curl -X POST https://api.airaproof.com/api/v1/agents \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_slug": "procurement-agent",
    "name": "Procurement Agent",
    "description": "Handles vendor selection and purchase order approval",
    "capabilities": ["tool_call", "transaction", "decision"],
    "metadata": {
      "team": "operations",
      "environment": "production"
    }
  }'

Response (201 Created)

{
  "agent_slug": "procurement-agent",
  "name": "Procurement Agent",
  "description": "Handles vendor selection and purchase order approval",
  "capabilities": ["tool_call", "transaction", "decision"],
  "status": "active",
  "owner_id": "org_01J9A...",
  "created_at": "2026-03-24T10:00:00.000Z",
  "request_id": "req_01J9A..."
}

Error Codes

Status	Code	Description
400	`INVALID_SLUG`	Slug must be lowercase alphanumeric with hyphens, 3-64 chars
409	`SLUG_TAKEN`	An agent with this slug already exists

List Agents

GET /api/v1/agents?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated list of agents owned by your organization.

Response (200 OK)

{
  "agents": [
    {
      "agent_slug": "procurement-agent",
      "name": "Procurement Agent",
      "status": "active",
      "current_version": "1.2.0",
      "action_count": 1847,
      "created_at": "2026-03-24T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5
  }
}

Get Agent

GET /api/v1/agents/{agent_slug}
Authorization: Bearer aira_live_xxxxx

Returns full agent detail including version history.

Response (200 OK)

{
  "agent_slug": "procurement-agent",
  "name": "Procurement Agent",
  "description": "Handles vendor selection and purchase order approval",
  "capabilities": ["tool_call", "transaction", "decision"],
  "status": "active",
  "owner_id": "org_01J9A...",
  "current_version": "1.2.0",
  "versions": [
    {
      "version": "1.2.0",
      "instruction_hash": "sha256:a1b2c3d4...",
      "published_at": "2026-03-20T08:00:00.000Z",
      "changelog": "Added multi-currency support"
    },
    {
      "version": "1.1.0",
      "instruction_hash": "sha256:e5f6g7h8...",
      "published_at": "2026-03-10T12:00:00.000Z",
      "changelog": "Improved vendor scoring"
    }
  ],
  "metadata": {
    "team": "operations",
    "environment": "production"
  },
  "created_at": "2026-03-24T10:00:00.000Z"
}

Update Agent

PUT /api/v1/agents/{agent_slug}
Authorization: Bearer aira_live_xxxxx

Updates mutable agent fields. The slug cannot be changed.

Request Body

Field	Type	Required	Description
`name`	string	No	Updated name
`description`	string	No	Updated description
`capabilities`	string[]	No	Updated capabilities
`metadata`	object	No	Updated metadata (replaces existing)

Response (200 OK)

Returns the updated agent object.

Publish Version

POST /api/v1/agents/{agent_slug}/versions
Authorization: Bearer aira_live_xxxxx

Publishes a new version of the agent. Each version captures the instruction hash so actions can be traced back to the exact instruction set.

Request Body

Field	Type	Required	Description
`version`	string	Yes	Semantic version (e.g. `1.3.0`)
`instruction_hash`	string	Yes	SHA-256 hash of the agent's instruction set
`changelog`	string	No	What changed in this version

Example Request

curl -X POST https://api.airaproof.com/api/v1/agents/procurement-agent/versions \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.3.0",
    "instruction_hash": "sha256:b9c8d7e6f5...",
    "changelog": "Added compliance checks for EU procurement directives"
  }'

Response (201 Created)

{
  "agent_slug": "procurement-agent",
  "version": "1.3.0",
  "instruction_hash": "sha256:b9c8d7e6f5...",
  "changelog": "Added compliance checks for EU procurement directives",
  "published_at": "2026-03-24T11:00:00.000Z"
}

Error Codes

Status	Code	Description
409	`VERSION_EXISTS`	This version number has already been published
422	`AGENT_DECOMMISSIONED`	Cannot publish versions for a decommissioned agent

List Versions

GET /api/v1/agents/{agent_slug}/versions
Authorization: Bearer aira_live_xxxxx

Returns all published versions for the agent, ordered by publish date descending.

Decommission Agent

POST /api/v1/agents/{agent_slug}/decommission
Authorization: Bearer aira_live_xxxxx

Permanently decommissions an agent. This blocks all future action notarization for this agent. Existing records are preserved. This action is irreversible.

Request Body

Field	Type	Required	Description
`reason`	string	Yes	Reason for decommissioning

Response (200 OK)

{
  "agent_slug": "procurement-agent",
  "status": "decommissioned",
  "decommissioned_at": "2026-03-24T12:00:00.000Z",
  "reason": "Replaced by procurement-agent-v2"
}

Transfer Ownership

POST /api/v1/agents/{agent_slug}/transfer
Authorization: Bearer aira_live_xxxxx

Transfers agent ownership to another organization. The transfer is cryptographically signed and recorded in the agent's audit trail.

Request Body

Field	Type	Required	Description
`target_org_id`	string	Yes	Organization ID to transfer to
`signature`	string	Yes	Cryptographic signature authorizing the transfer

Response (200 OK)

{
  "agent_slug": "procurement-agent",
  "previous_owner": "org_01J9A...",
  "new_owner": "org_01J9B...",
  "transferred_at": "2026-03-24T13:00:00.000Z",
  "transfer_receipt_id": "rct_01J9C..."
}

Error Codes

Status	Code	Description
400	`INVALID_SIGNATURE`	Transfer signature verification failed
404	`TARGET_ORG_NOT_FOUND`	Target organization does not exist

Agent Actions

GET /api/v1/agents/{agent_slug}/actions?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated list of all actions notarized by this agent.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`action_type`	string	Filter by action type
`status`	string	Filter by status

Public Agent Identity (Public)

GET /api/v1/agents/public/{agent_slug}

Public endpoint — no authentication required. Returns the agent's public identity page for external verification.

Response (200 OK)

{
  "agent_slug": "procurement-agent",
  "name": "Procurement Agent",
  "description": "Handles vendor selection and purchase order approval",
  "capabilities": ["tool_call", "transaction", "decision"],
  "status": "active",
  "current_version": "1.3.0",
  "owner_verified": true,
  "action_count": 1847,
  "created_at": "2026-03-24T10:00:00.000Z"
}

On this page