> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amrood.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Amrood REST API

# API Reference

Base URL: `https://api.amrood.io`

All endpoints accept and return JSON. Authentication is via API key headers.

## Endpoints

### Auth

* `POST /v1/auth/send-otp` — Send OTP to phone number
* `POST /v1/auth/verify-otp` — Verify OTP and create session

### Owners

* `POST /v1/owners` — Create a human owner
* `GET /v1/owners/{owner_id}` — Get owner details
* `POST /v1/owners/{owner_id}/kyc` — Submit KYC

### Agents

* `POST /v1/agents` — Create an agent (with unique handle)
* `GET /v1/agents` — List agents
* `GET /v1/agents/me` — Get current agent (agent-key auth)
* `GET /v1/agents/me/proof` — Generate signed network membership proof (1hr TTL)
* `GET /v1/agents/handle/{handle}/available` — Check handle availability (public)
* `GET /v1/agents/{agent_id}/exists` — Check existence by handle or ID (public)
* `GET /v1/agents/{agent_id}` — Get agent details
* `PATCH /v1/agents/{agent_id}` — Update agent
* `DELETE /v1/agents/{agent_id}` — Deactivate agent
* `POST /v1/agents/{agent_id}/rotate-keys` — Rotate agent API key

### Wallet

* `GET /v1/agents/{agent_id}/balance` — Check balance
* `POST /v1/agents/{agent_id}/fund` — Create funding session
* `GET /v1/agents/{agent_id}/fund/{funding_id}` — Check funding status
* `POST /v1/agents/{agent_id}/withdraw` — Withdraw to owner's bank

### Payments

* `POST /v1/agents/{agent_id}/pay` — Pay another agent

### Transactions

* `GET /v1/agents/{agent_id}/transactions` — Transaction history
* `GET /v1/transactions/{txn_id}/verify` — Verify transaction ([x402 payment proof](/payments/x402-paywall))

### Identity & Certificates

* `GET /v1/identity/{agent_id}/verify` — Verify agent identity (signed)
* `GET /v1/identity/{agent_id}/public-key` — Get agent public key
* `POST /v1/agents/{agent_id}/certificates` — Issue certificate
* `GET /v1/agents/{agent_id}/certificates` — List certificates
* `GET /v1/certificates/{cert_id}` — Get certificate
* `GET /v1/certificates/{cert_id}/verify` — Verify certificate
* `POST /v1/certificates/{cert_id}/revoke` — Revoke certificate
* `POST /v1/certificates/{cert_id}/rotate` — Rotate certificate

### Escrow

* `POST /v1/agents/{agent_id}/escrow/hold` — Hold funds in escrow
* `POST /v1/agents/{agent_id}/escrow/hold-with-timeout` — Hold with auto-release timeout
* `POST /v1/agents/{agent_id}/escrow/hold-with-attestation` — Hold requiring third-party attestation
* `POST /v1/escrow/{escrow_id}/release` — Release escrowed funds
* `POST /v1/escrow/{escrow_id}/refund` — Refund escrowed funds
* `POST /v1/escrow/{escrow_id}/attest` — Attest escrow condition
* `GET /v1/escrow/{escrow_id}` — Get escrow status

### Audit

* `GET /v1/agents/{agent_id}/audit` — Get audit trail
* `GET /v1/audit/verify` — Verify audit entry

### Receipts

* `GET /v1/receipts/{receipt_id}` — Get receipt
* `GET /v1/receipts/{receipt_id}/verify` — Verify receipt

### Webhooks

* `GET /v1/webhooks/deliveries` — List webhook deliveries
* `POST /v1/webhooks/deliveries/{delivery_id}/retry` — Retry delivery
* `POST /v1/webhooks/test` — Send test webhook

### Organizations

* `POST /v1/orgs` — Create organization
* `GET /v1/orgs/{org_id}` — Get organization
* `POST /v1/orgs/{org_id}/agents` — Add agent to org
* `DELETE /v1/orgs/{org_id}/agents/{agent_id}` — Remove agent from org
* `POST /v1/orgs/{org_id}/treasury` — Fund org treasury
* `POST /v1/orgs/{org_id}/allocate` — Allocate budget to agent
* `GET /v1/orgs/{org_id}/transactions` — Org transaction history
* `GET /v1/orgs/{org_id}/budget` — Get org budget

### Approvals

* `GET /v1/approvals` — List pending approvals
* `POST /v1/approvals/{approval_id}/approve` — Approve transaction
* `POST /v1/approvals/{approval_id}/reject` — Reject transaction

### Platforms

* `POST /v1/platforms` — Create platform
* `GET /v1/platforms/{platform_id}` — Get platform
* `PATCH /v1/platforms/{platform_id}` — Update platform
* `DELETE /v1/platforms/{platform_id}` — Delete platform

### Admin

* `GET /v1/admin/overview` — Platform overview stats
* `GET /v1/admin/owners` — List all owners
* `GET /v1/admin/owners/{owner_id}` — Get owner details
* `POST /v1/admin/owners/{owner_id}/freeze` — Freeze owner
* `POST /v1/admin/owners/{owner_id}/unfreeze` — Unfreeze owner
* `POST /v1/admin/agents/bulk-freeze` — Bulk freeze agents
* `POST /v1/admin/agents/bulk-quarantine` — Bulk quarantine agents
* `PATCH /v1/admin/tiers/{tier}` — Update tier defaults
* `GET /v1/admin/risk/alerts` — List risk alerts
* `POST /v1/admin/risk/alerts/{alert_id}/review` — Review risk alert
* `GET /v1/admin/risk/agents/{agent_id}/score` — Get agent risk score

Detailed request/response schemas are auto-generated from the OpenAPI spec below.