Quickstart

Two things to get working: the widget on your pages, and one server-to-server call. Fifteen minutes.

1. Get your credentials

You need two different things, and they live in two different places. Settings → Workspace — the workspace’s publishable key (pk_…) for the widget, and its secret key (sk_…) for POST /v1/users. Visible to the owner and developers. Settings → API keys — your own API token (pv_ut_…), which is what the rest of the /v1 API and MCP take. It acts as you and carries your workspace role.

Each is shown once. Copy them now. The secret key and your API token are stored hashed and cannot be retrieved later — if you lose one, rotate it.

2. Set your domain

Open Settings → Workspace and set your domain (for example app.example.com). This is what makes your publishable key safe to publish. In production, Peeve compares the request Origin against this domain and rejects anything else. Without a domain set, a production key only works from localhost. See Origins for the exact rule, including the www-insensitive match. Drop the script tag on every page you want the agent to work on.

<script
  src="https://cdn.peeve.ai/widget.js"
  data-publishable-key="pk_live_xxx"
  defer
></script>

That is the whole install. The tag auto-boots — no init() call needed.

Nothing appears yet. The widget stays hidden for end users until your app has been mapped for the first time, so a real visitor never meets an unmapped cursor. Run the baseline capture from the dashboard to map it.

If you prefer a package to a script tag:

npm i @peeve/sdk

import { Peeve } from "@peeve/sdk";

Peeve.init({ publishableKey: "pk_live_xxx" });

Peeve.init injects the same script tag with the same key, and is idempotent — if you already have the tag on the page, it will not add a second one.

4. Tell Peeve who the user is

Once someone signs in, identify them. This is what turns an anonymous visitor into a named contact, and it is what lets the agent give plan-aware answers.

window.peeve.identify({
  id: "user_8412",
  email: "dana@example.com",
  name: "Dana Whitfield",
  plan: "Growth",
});

window.peeve.setContext({ seats: 12, role: "admin" });

identify carries modelled identity and is encrypted at rest. setContext is an open key/value bag for business context — plaintext, non-secret. Put identity in the first, everything else in the second. See Identity and context.

5. Read your data with your API token

The quickest thing to confirm your token works — list your sessions.

curl "https://api.peeve.ai/v1/sessions?limit=5" \
  -H "Authorization: Bearer pv_ut_xxx"

{
  "object": "list",
  "data": [ { "id": "…", "object": "session", "channel": "human", "started_at": "2026-08-17T09:12:00Z" } ],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_xxx"
}

Every /v1 read works this way — same envelope, same pagination, same errors. See API conventions.

A 401 with user_token_required means you sent a secret key. The /v1 data endpoints take your API token (pv_ut_…) from Settings → API keys — the API’s error wording says “user token” for the same credential.

6. Push a user from your backend

This one is different: it uses the workspace secret key, so it must run on a server.

curl https://api.peeve.ai/v1/users \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_8412",
    "email": "dana@example.com",
    "name": "Dana Whitfield",
    "plan": "Growth"
  }'

const res = await fetch("https://api.peeve.ai/v1/users", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PEEVE_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_user_id: "user_8412",
    email: "dana@example.com",
    name: "Dana Whitfield",
    plan: "Growth",
  }),
});

const user = await res.json();

import os, requests

res = requests.post(
    "https://api.peeve.ai/v1/users",
    headers={"Authorization": f"Bearer {os.environ['PEEVE_SECRET_KEY']}"},
    json={
        "external_user_id": "user_8412",
        "email": "dana@example.com",
        "name": "Dana Whitfield",
        "plan": "Growth",
    },
)
user = res.json()

A successful response:

{
  "id": "00000000-0000-4000-8000-000000000000",
  "external_user_id": "user_8412",
  "workspace": "example-corp"
}

If this returns 401 { "error": "a secret key (sk_*) is required" }, you sent a publishable key. The endpoint rejects pk_… outright and emits no CORS headers — it is not callable from a browser, by construction.

Authentication

The full key and origin model.

Widget JavaScript API

Every method the widget exposes on the page.

MCP server

Let Claude, ChatGPT or Cursor discover your product.

Rate limits

The per-plan ceilings, and what happens when you hit one.

Get started

Authentication

Widget

MCP

Webhooks

Reference

1. Get your credentials

2. Set your domain

3. Install the widget

4. Tell Peeve who the user is

5. Read your data with your API token

6. Push a user from your backend

What to read next

Authentication

Widget JavaScript API

MCP server

Rate limits

​1. Get your credentials

​2. Set your domain

​3. Install the widget

​4. Tell Peeve who the user is

​5. Read your data with your API token

​6. Push a user from your backend

​What to read next

Authentication

Widget JavaScript API

MCP server

Rate limits

1. Get your credentials

2. Set your domain

3. Install the widget

4. Tell Peeve who the user is

5. Read your data with your API token

6. Push a user from your backend

What to read next