REST API reference
Complete reference for all WP-PFAgent REST API endpoints. Base URL: /wp-json/pfw-agent/v1/
Authentication
All endpoints require WordPress authentication. Send X-WP-Nonce header with a nonce from wp_create_nonce('wp_rest').
Contract & discovery
| Method | Route | Description |
|---|---|---|
| GET | /contract | Full agent contract (routes, tools, providers, capabilities) |
| GET | /contract/openapi | OpenAPI 3.1 document for all endpoints |
Provider management
| Method | Route | Description |
|---|---|---|
| GET | /provider-presets | Catalog of all known provider presets |
| GET | /provider-credentials | List credential statuses per preset |
| POST | /provider-credentials/{provider} | Save/update API key + settings |
| DELETE | /provider-credentials/{provider} | Delete stored credential |
| POST | /provider-credentials/{provider}/rotate | Rotate credential |
| POST | /provider-credentials/{provider}/test | Test connection |
| GET | /provider-models/{provider} | Discover/cache models (?force=true to bypass cache) |
| POST | /provider-models/{provider}/manual | Save manually-entered model IDs |
| POST | /provider-models/{provider}/save | Persist wizard-confirmed model config |
| POST | /provider-health/{provider} | Full health check (discovery + validation) |
| POST | /provider-runtime/{provider}/smoke | Smoke test (one-sentence generation) |
Agent runtime
| Method | Route | Description |
|---|---|---|
| GET | /agent-runtime/tools | List declared tools with schemas |
| GET | /agent-runtime/internal-docs | Generated internal docs |
| POST | /agent-runtime/fix-suggestions | Diagnostic suggestions for tool errors |
| POST | /agent-runtime/turn-v2 | Run user message through agent loop |
| POST | /agent-runtime/resume-v2 | Resume after side-effect decision |
| GET | /agent-runtime/progress | Poll live progress during a turn |
| GET | /agent-runtime/permission-rules | Read permission rules |
| PUT | /agent-runtime/permission-rules | Save permission rules |
| GET | /agent-runtime/support-export | Full support export |
| GET | /agent-runtime/metrics | Aggregate metrics (?windowHours=N) |
| GET | /agent-runtime/beta-readiness | Evaluate beta readiness |
Chat sessions
| Method | Route | Description |
|---|---|---|
| GET | /chat-sessions | List user's sessions (paginated) |
| POST | /chat-sessions | Create session (label, optional workflowId) |
| POST | /chat-sessions/purge | Purge sessions older than N days (default 7) |
| GET | /chat-sessions/{id} | Get full session with messages |
| PATCH | /chat-sessions/{id} | Update label/workflowId |
| DELETE | /chat-sessions/{id} | Delete session + cascading data |
Turn response format
A successful turn returns:
{
"status": "ok",
"result": {
"kind": "success",
"final_text": "I've created the workflow for you.",
"usage": {"tokens_in": 1200, "tokens_out": 300, "cost_usd": 0.0045}
}
}When confirmation is needed:
{
"status": "ok",
"result": {
"kind": "needs_confirmation",
"pending_tool_call": {
"tool_name": "workflow_apply",
"arguments": {...},
"side_effect": "write",
"summary": "Create a new workflow 'Order Alert'"
}
}
}Then call /resume-v2 with {verdict: "approve"} or {verdict: "reject"}.