Skip to main content

​
Base URL

​
Authentication

Every endpoint in this reference is server-to-server and authenticated with a secret key (sk_…). Send it as a bearer token, or in the Peeve header:
A secret key is a bearer credential with full workspace authority. It belongs on your server only — never in a browser, in client-side code, or in a repository.These endpoints send no CORS headers and reject publishable (pk_…) keys, so they are not callable from a page by construction.
See Authentication for the full key model.

​
What the API covers

​
What is not in the API

Peeve’s other surfaces are not REST endpoints, and each has its own section:

The widget

Installed with a script tag and driven from the page with identify and setContext. The HTTP calls it makes are internal to the widget and are not a supported integration point.

MCP server

JSON-RPC, not REST. Read-only and guide-only.

Agent artifacts

Static generated files fetched by URL.

​
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.
The one thing you do push is people: POST /v1/users. That is the contacts API — it tells Peeve who your users are, so the agent recognises them. It does not create leads. 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 keys in these examples (sk_live_xxx) are not real. Substitute your own.