> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peeve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URL, authentication, and what the public API covers.

## Base URL

```
https://api.peeve.ai
```

## 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:

```bash theme={null}
-H "Authorization: Bearer sk_live_xxx"
-H "X-Peeve-Key: sk_live_xxx"
```

<Warning>
  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.
</Warning>

See [Authentication](/authentication/overview) for the full key model.

## What the API covers

| Endpoint                                                                 | Purpose                                                                   |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| [`POST /v1/users`](/api/server/users/push-a-user)                        | Create or update your users in Peeve — the contacts the agent recognises. |
| [`GET /api/killswitch`](/api/server/kill-switch/read-the-kill-switch)    | Read whether Peeve is currently serving.                                  |
| [`POST /api/killswitch`](/api/server/kill-switch/toggle-the-kill-switch) | Stop or resume Peeve serving, immediately.                                |

## What is not in the API

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

<CardGroup cols={2}>
  <Card title="The widget" icon="window" href="/widget/install">
    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.
  </Card>

  <Card title="MCP server" icon="plug" href="/mcp/overview">
    JSON-RPC, not REST. Read-only and guide-only.
  </Card>

  <Card title="Agent artifacts" icon="file-code" href="/artifacts/overview">
    Static generated files fetched by URL.
  </Card>
</CardGroup>

## 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.

| Data                              | How it is collected                                                        | Where you see it      |
| --------------------------------- | -------------------------------------------------------------------------- | --------------------- |
| **Leads**                         | The agent qualifies visitors through Peeve's own channels.                 | Dashboard → Leads     |
| **NPS and CSAT**                  | Asked of real end users, in the widget.                                    | Dashboard → Analytics |
| **Session telemetry and signals** | Emitted by the widget as people use your product.                          | Dashboard             |
| **Brain sources**                 | Added under **Brain → Sources**, during onboarding, or by Peeve's crawler. | Dashboard → Brain     |

<Warning>
  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.
</Warning>

The one thing you *do* push is people:
[`POST /v1/users`](/api/server/users/push-a-user). 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.