API Overview

The Payre API is a REST API served by Fastify. Default base URL: http://localhost:3000.

Authentication

All endpoints (except /health) require an API key via the X-Payre-Key header:

X-Payre-Key: pyr_sk_your_api_key_here

See Authentication for details.

Endpoints

Method	Path	Description
GET	/health	Health check (public)
POST	/register	Register an agent passport
GET	/agents	List all agents
GET	/agents/:id	Get agent details
PUT	/agents/:id	Update agent
DELETE	/agents/:id	Delete agent
POST	/resolve	Resolve intent to agents
POST	/intent/preview	Parse intent without resolving
POST	/grant	Create a grant
GET	/grant/:id	Get grant details
POST	/grant/:id/revoke	Revoke a grant
GET	/grants	List grants (paginated)
POST	/invoke	Invoke an agent
GET	/invoke/:id	Get invocation details
GET	/receipts/:id	Get receipt
GET	/invocations	List invocations (paginated)
GET	/stats	Dashboard statistics
POST	/api-keys	Create API key
GET	/api-keys	List API keys
DELETE	/api-keys/:id	Deactivate API key

Pagination

List endpoints support pagination:

?page=1&pageSize=20&sortOrder=desc

Response includes:

{
  "data": [...],
  "total": 100,
  "page": 1,
  "pageSize": 20,
  "totalPages": 5
}

Error Format

{
  "status": "error",
  "message": "Human-readable error message"
}

HTTP status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 409 (conflict).