Skip to main content
Peeve exposes more than one way in. This page maps a goal to the right one so you do not build against the wrong surface.

​
By goal

​
The widget endpoints

The endpoints under /api/* are what the widget calls from your site. They are documented in full under API reference → Widget endpoints, and you can call them directly — they are publishable-key and origin gated, and they work from any page on your domain. Two things to know before you build on them:
They serve the widget first. They are shaped around what the widget needs each turn, not around being a general-purpose REST API, and they change with the widget. If you build a custom surface on them, pin your expectations to the response fields you actually read and tolerate new ones appearing.
Most of them fail open. An unknown key, a disallowed origin, or a rate-limited request is answered with a harmless empty success rather than an error status, because a widget must never surface a console error inside a customer’s app. That means a 200 does not always mean the call did something. Check the body — stored, captured, show, ok — not the status code. See Errors for the per-endpoint table.

​
The agent loop, in one picture

If you are building your own surface rather than using the widget, this is the shape of it. Each turn is one request. You send the goal and a fresh scan of what is on screen; Peeve returns the next one to four steps. The agent can only reference elements you sent it — it cannot invent a target. Writes are the part that matters. Any click on an element you marked write: true comes back as a confirm step instead, and the batch stops there. You show the confirmation, the user approves, and the next turn proceeds. This is enforced on the server, so it holds whether or not the model cooperates.

​
What is not documented here

  • Internal cron and admin routes (/api/cron/*, /api/admin/*) — bearer-gated operational endpoints, not a customer surface.
  • Dashboard routes — the dashboard uses server actions and cookie-authenticated routes such as /api/search. They are not an API and are not stable.
  • Connector OAuth callbacks (/api/connectors/*) — driven by the dashboard’s connect flows, not called directly.
  • Inbound webhook receivers (/api/webhooks/*, /api/stripe/webhook) — configured by Peeve when you connect a channel. Not a customer surface.