Skip to main content

​
Base URL

​
Authentication

Almost every endpoint takes an API token (pv_ut_…) — not the workspace secret key.Create one in Settings → API keys. It is yours, not the workspace’s: it acts as you, carrying your workspace role resolved at the moment of every call, so it can never do more than you can.The publishable and secret keys live in Settings → Workspace. Those are the widget’s and the CLI’s credentials.
Header only — never a query parameter. URLs end up in proxy logs, browser history and Referer headers.

​
The two exceptions

POST /v1/users and POST /v1/answer take the workspace secret key (sk_…) instead. They are machine paths that run in your backend on a signup hook or a schedule, and tying a production pipeline to one employee’s token would break the day they leave.
So /v1 is not uniform. Every operation states its credential and its required role. Check the operation, not the namespace.
A publishable key ships in your page source where every script can read it, so it authenticates nothing that matters. One that could read /v1/leads would put your pipeline one XSS away.
See Credentials for the full model and Roles for what each role reaches.

​
What the API covers

24 paths, 32 operations. Start with API conventions — the envelope, pagination and error shape are the same everywhere.

​
What you cannot write through the API

Some data is collected by Peeve and is read-only to you. There is no endpoint to submit it, deliberately.
These are read-only on purpose. An endpoint that let leads or survey scores be posted directly would let the numbers be manufactured, which makes the whole dataset worthless — a satisfaction score you can POST measures nothing.

​
What is not in the API

The widget

A script tag, driven with identify and setContext. Its own HTTP calls are internal and are not a supported integration point.

MCP

JSON-RPC, not REST. Takes an API token; the role governs what is reachable.
Internal cron and admin routes, dashboard routes, connector OAuth callbacks and the inbound webhook receivers are not a customer surface and are not documented.

​
Conventions

  • Request and response bodies are JSON.
  • Timestamps are ISO 8601.
  • Placeholder credentials here (pv_ut_xxx, sk_live_xxx) are not real.