REST API

The Prova API serves the indexed attestation layer: paginated queries, agent stats, premium forensic endpoints, and webhooks. Public reads need no account.

Base URL

https://prova-api.fly.dev/api/v1

Public endpoints

Endpoint	Description
`GET /health`	Service status and version.
`GET /stats`	Global agent and attestation counts.
`GET /attestations`	Paginated list. Query params: `limit`, `offset`, `agentPda`, `actionType`, `from`, `to`.
`GET /attestations/:id`	Attestation detail by PDA.
`GET /agents/:agentId`	Agent detail.
`GET /agents/:agentId/stats`	Per-agent stats with action-type breakdown.

Examples

# List the latest attestations (public, no key required)
curl "https://prova-api.fly.dev/api/v1/attestations?limit=10"

# Filter by agent and action type
curl "https://prova-api.fly.dev/api/v1/attestations?agentPda=4QxC...&actionType=ToolCall"

# Agent detail + stats
curl "https://prova-api.fly.dev/api/v1/agents/4QxC..."
curl "https://prova-api.fly.dev/api/v1/agents/4QxC.../stats"

Response shape

{
  "data": [
    {
      "pda": "…",
      "agentPda": "4QxC…",
      "actionType": "ToolCall",
      "actionHash": "…",
      "txSignature": "3rJf…",
      "timestamp": "2026-07-15T12:00:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 46213 }
}

Premium endpoints

Premium endpoints are gated by an API key (header x-api-key) and support x402 micropayments for one-off, account-less queries. Generate keys at theprova.xyz/app/api-keys.

Endpoint	Description
`GET /premium/full-history/:agentId`	Full attestation history (up to 1000 receipts).
`GET /premium/forensic-report/:agentId`	Structured forensic report for audits.
`POST /premium/bulk-verify`	Verify up to 1000 attestation IDs in one call.

Authentication

# Premium endpoints require an API key in the x-api-key header:
curl "https://prova-api.fly.dev/api/v1/premium/full-history/4QxC..." \
  -H "x-api-key: prova_..."

Webhooks

Get pushed events instead of polling. Deliveries are signed with HMAC-SHA256 (x-prova-signature header), retried on failure, and logged.

Endpoint	Description
`POST /webhooks`	Create a webhook (API key required).
`GET /webhooks`	List your webhooks (secrets never returned).
`DELETE /webhooks/:id`	Delete a webhook.

# Create a webhook (API key required)
curl -X POST "https://prova-api.fly.dev/api/v1/webhooks" \
  -H "x-api-key: prova_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/hooks/prova", "events": ["attestation.created"] }'

# Deliveries are signed:
#   x-prova-signature: sha256=<HMAC-SHA256 hex of the body>

Rate limits & errors

Rate limit: 100 requests/minute per IP (sliding window). Exceeding it returns 429.
Errors follow { "error": { "message": string } } with standard HTTP status codes.
Premium calls without a valid key return 401; x402-payable requests return 402 with payment instructions.