API overview

Pi Durable Platform serves everything from one origin, its APP_URL:

• The management API under /v1, plus /auth/* and the probes /healthz and /readyz: everything the web app does, and the agent routes apps use. It's described by an OpenAPI 3 document that covers every route; a test in the product's repository fails if a served route is missing from it. The reference is generated from that document.
• The OAuth endpoints under /oauth/ and /.well-known/: the authorization server apps use with OAuth Connect. They speak OAuth, not the /v1 envelope, so they aren't in the OpenAPI document. See OAuth endpoints.

The agent gateway (port 8099, AGENTS_GATEWAY_ADDR) is a separate listener for agent runtimes only, and isn't an API for apps.

ConventionsCopy Anchor Link

• Authentication: a browser session (cookie) reaches every operation its person may use. Bearer credentials (service account keys pdp_sa_…, personal API keys pdp_…, OAuth Connect tokens pdpat_…) reach the agent routes and a few readings; see which routes take which credentials.
• Browser writes need X-CSRF-Token (from GET /v1/me) and a same-origin Origin.
• Responses are {"data": …}; errors are {"error": {"code", "message"}}. Every response carries X-Request-ID.
• Edits use revisions: ETag on reads, If-Match on PATCH and settings PUTs (428 if missing, 412 if stale).
• Lists of users, teams, service accounts and audit entries page with cursor and limit, and search with q.
• Not allowed reads as not found for agents, threads and teams the caller may not see.
• Rate limit: REQUESTS_PER_MINUTE per person or service account, 429 rate_limited with Retry-After.

The API may change between releases before 1.0. Each release's notes list changes.

The referenceCopy Anchor Link

The sidebar's Management API groups operations by area: health, sign-in, me, teams, admin, API keys, service accounts, agents (with threads and templates), models and usage, MCP servers, and OAuth consent and connected apps. Each page shows the operation's parameters, bodies, responses and example requests against https://agents.example.com. There's no "try it" button: the docs never call an install.

The reference is generated from openapi/pi-durable-platform.yaml, a copy of the product's api/openapi.yaml at v0.1.0.