01
Overview
The PV API is a JSON REST API. All requests use HTTPS, and request and response bodies are JSON. Your base URL is provided with your API credentials; examples below use $PV_API_URL.
New to PV? Start with the Documentation.
API ReferenceAPI Reference
API Reference
v1
Endpoints, parameters, and responses for the PV REST API.
Last updated: October 3, 2026
02
Authentication
Authenticate every request with your API key as a bearer token. Requests without a valid key return 401.
Header
Authorization: Bearer $PV_API_KEY03
Create an agent
POST/agents
Body
namestring · required
A unique name for the agent.
instructionsstring · required
What the agent should do and how.
modelstring
Model to use. Defaults to "auto" (PV picks per step).
permissionsstring[]
Scopes the agent may use. Defaults to none.
Response · 201
{
"id": "agt_123",
"name": "invoice-reconciler",
"model": "auto",
"permissions": ["integrations:accounting:read", "files:write"],
"created_at": "2026-10-03T09:00:00Z"
}04
List and get agents
05
Delete an agent
DELETE/agents/{agent_id}
Deletes the agent. Running tasks are cancelled; past tasks and audit entries are kept. Returns 204.
06
Create a task
POST/tasks
Body
agent_idstring · required
The agent that should run the task.
inputstring · required
The goal or instructions for this task.
metadataobject
Your own key–value data, returned with the task.
Response · 202
{
"id": "tsk_456",
"agent_id": "agt_123",
"status": "queued",
"created_at": "2026-10-03T09:01:00Z"
}07
Get a task
GET/tasks/{task_id}
Returns the task with its current status: queued, running, succeeded, failed, or cancelled. When finished, output holds the result.
Response · 200
{
"id": "tsk_456",
"status": "succeeded",
"output": "Reconciled 128 invoices. 3 mismatches flagged.",
"started_at": "2026-10-03T09:01:02Z",
"finished_at": "2026-10-03T09:04:40Z"
}08
Stream task events
GET/tasks/{task_id}/events
Opens a server-sent events stream of the task's progress. Event types are step, tool_call, output, and completed. The stream closes after completed.
09
Cancel a task
POST/tasks/{task_id}/cancel
Stops a queued or running task. Returns the task with status cancelled.
10
Audit logs
GET/audit-logs
Query
agent_idstring
Only entries for this agent.
task_idstring
Only entries for this task.
sinceISO 8601 timestamp
Only entries after this time.
11
Pagination
List endpoints accept limit (1–100, default 20) and cursor. Pass the next_cursor from a response to get the next page; it is null on the last page.
12
Errors
Errors use standard HTTP status codes and a consistent body:
{
"error": {
"code": "not_found",
"message": "No task with id tsk_999."
}
}Status codes
400invalid_request
The request body or parameters are invalid.
401unauthorized
The API key is missing or invalid.
403forbidden
The key or agent lacks the required permission.
404not_found
The resource does not exist.
429rate_limited
Too many requests. Retry after the Retry-After header.
500server_error
Something went wrong on our side. Safe to retry.