API Reference
REST API for everything pfai and the web UI do — versioned under /api/v1, JSON over HTTPS, Bearer-token auth.
The ProxifAI API exposes 400+ endpoints under /api/v1 on the same host that serves the web UI. There’s no separate API hostname — point your client at http://localhost:3000/api/v1/... (or whatever BASE_URL resolves to in your deployment) and authenticate with a PAT or a pfai_<execID> workflow token.
Reference structure
| Section | Covers |
|---|---|
| Authentication | Bearer tokens, PATs, workflow tokens, OIDC for browser sessions |
| Conventions | URL shape, content types, pagination, filtering, query semantics |
| Errors | Response shape, status codes, retry guidance |
| Rate limits | Where rate limits exist (gateway only) and how they behave |
Resource pages
Hand-written reference for the most-used resources. Every other endpoint follows the same conventions described above.
| Resource | Base path | Doc |
|---|---|---|
| Issues | /api/v1/issues | Issues API |
| Workflows | /api/v1/workflows | Workflows API |
| Repositories | /api/v1/forge/repos | Repositories (REST table at the bottom) |
| Pull requests | /api/v1/forge/{owner}/{repo}/pulls | Pull Requests |
| Releases | /api/v1/forge/{owner}/{repo}/releases | Releases |
| AI Gateway | /api/v1/llm/v1/{chat/completions,messages} | AI Gateway → Endpoints |
| Triggers | /api/v1/triggers | Triggers |
| Tokens (PATs) | /api/v1/tokens | Authentication → PATs |
What’s not here
- No interactive playground — the API is fully introspectable via the OpenAPI spec at
/api/v1/openapi.json(whenOPENAPI_ENABLED=true); pair it with Bruno, Insomnia, orcurlfor now - No SDK reference — there isn’t an official client SDK yet; both
pfaiand the web frontend hit this same surface directly - No versioning beyond
/api/v1— additive changes don’t bump the version; breaking changes haven’t happened yet, and when they do they’ll ship under/api/v2
Direct API access from the CLI
Every endpoint is reachable via pfai api without leaving the terminal:
pfai api GET /api/v1/issues?status=in_progress
pfai api POST /api/v1/issues '{"title":"Audit auth flow","teamId":"team_42","status":"todo"}'This is useful for endpoints that don’t have a dedicated pfai subcommand yet — e.g. cloud, custom event types, push rules.