Quickstart

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

1. Get your keys

In the Peeve dashboard, open Settings → API keys. Create a publishable key and a secret key.

Both are shown once. Copy them now. The secret key is stored hashed and cannot be retrieved later — if you lose it, 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. Make one server call

Push a user from your backend. This one uses your 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 server

Agent artifacts

Reference

1. Get your keys

2. Set your domain

3. Install the widget

4. Tell Peeve who the user is

5. Make one server call

What to read next

Authentication

Widget JavaScript API

MCP server

Rate limits

​1. Get your keys

​2. Set your domain

​3. Install the widget

​4. Tell Peeve who the user is

​5. Make one server call

​What to read next

Authentication

Widget JavaScript API

MCP server

Rate limits

1. Get your keys

2. Set your domain

3. Install the widget

4. Tell Peeve who the user is

5. Make one server call

What to read next