APIs Reference
APIs, webhooks & MCP.

PV builds and runs your agents. These interfaces let your systems and AI tools work with them:

• REST APIs: start tasks, check their results, handle approvals and read audit logs.
• Webhooks: get notified the moment a task finishes or an agent needs a decision.
• MCP: let AI assistants that support the Model Context Protocol use your PV agents as tools, and let your agents use your own MCP servers.

Access is set up per project: we enable the endpoints, webhook events and MCP tools your project needs and send you the details with your credentials. New to PV? Start with the Documentation.

All requests use HTTPS and JSON. Your base URL and API key come with your project; examples use $PV_API_URL and $PV_API_KEY. Send the key as a bearer token. Requests without a valid key return 401.

Authorization: Bearer $PV_API_KEY

Keys are scoped to your organisation and the permissions agreed for your project. Keep them out of source control and client-side code, and ask us to rotate a key at any time.

Returns the agents PV runs for your organisation, with their status (active or paused). Agents are built and configured by our team, so there are no create or delete endpoints. Ask us for a new agent or a change.

{
  "data": [
    {
      "id": "agt_123",
      "name": "invoice-processor",
      "description": "Reads supplier invoices and files them in the ERP.",
      "status": "active"
    }
  ],
  "next_cursor": null
}

A task moves through queued, running, awaiting_approval, and ends as succeeded, failed or cancelled. When it finishes, output holds the result. To avoid polling, use webhooks.

{
  "id": "tsk_456",
  "status": "succeeded",
  "output": "Filed 42 invoices. 3 need review.",
  "started_at": "2026-10-04T09:01:02Z",
  "finished_at": "2026-10-04T09:04:40Z"
}

Stops a queued, running or waiting task. Returns the task with status cancelled.

Steps you’ve marked as sensitive, such as a payment or a message to a customer, pause the task and create an approval. Approve or reject it here, in the PV Platform, or from your own tools through the approval.requested webhook.

Every action an agent takes: what it did, when, and in which system.

Give us an HTTPS endpoint and choose the events you want. We send a POST with a JSON body for each event.

{
  "id": "evt_789",
  "type": "task.succeeded",
  "created_at": "2026-10-04T09:04:40Z",
  "data": {
    "task_id": "tsk_456",
    "agent_id": "agt_123",
    "output": "Filed 42 invoices. 3 need review.",
    "metadata": { "batch": "2026-10-04" }
  }
}

Verify every request. Each one carries a PV-Signature header: an HMAC-SHA256 of the raw body using your webhook secret. Compare it before trusting the payload.

import crypto from "node:crypto";

function isFromPV(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Reply with any 2xx within 10 seconds. Failed deliveries are retried with increasing delays for up to 24 hours. Use the event id to ignore duplicates.

The Model Context Protocol (MCP) is an open standard for connecting AI applications to tools and data. PV supports it in both directions.

Use your PV agents from your AI assistant. Add the PV MCP server to any MCP-compatible assistant your team uses, and it can start tasks and check results for you.

URL:            $PV_API_URL/mcp
Transport:      Streamable HTTP
Authorization:  Bearer $PV_API_KEY

Let your agents use your MCP servers. If your systems already have MCP servers, we connect your agents to them, read-only unless you approve more. If they don’t, we can build one.

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.

Errors use standard HTTP status codes and a consistent body:

{
  "error": {
    "code": "not_found",
    "message": "No task with id tsk_999."
  }
}