API conventions

Every /v1 endpoint shares one envelope, one pagination scheme and one error shape. Read this once and the rest of the reference is per-endpoint specifics.

Two endpoints predate this contract and keep their original flat shapes for compatibility with live callers: POST /v1/users and POST /v1/answer. They are marked as such in the reference.

The envelope

A single object:

{
  "object": "lead",
  "data": { "id": "...", "object": "lead", "status": "qualified" },
  "request_id": "req_xxx"
}

A list:

{
  "object": "list",
  "data": [ { "id": "...", "object": "lead" } ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJ...",
  "request_id": "req_xxx"
}

has_more and next_cursor are always present, even when false and null, so a paging loop is written once and never branches. Every response also carries X-Request-Id (matching request_id) and Cache-Control: no-store — this is workspace data behind a credential, and a shared cache in front of it is how one tenant gets served another’s response.

Quote a request_id to support for any outcome, success or failure. It is the only thing that ties your report to the server-side log line — error messages deliberately never echo the offending row.

Pagination

Keyset cursors only. There is no offset paging.

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

# Next page — pass next_cursor back verbatim
curl "https://api.peeve.ai/v1/sessions?limit=100&cursor=eyJ2IjoxLCJ..." \
  -H "Authorization: Bearer pv_ut_xxx"

async function* allSessions(token) {
  let cursor = null;
  do {
    const url = new URL("https://api.peeve.ai/v1/sessions");
    url.searchParams.set("limit", "200");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    const page = await res.json();

    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

Do not parse or construct a cursor. It is opaque and we stay free to change it. It is also not a security boundary — it carries only a sort value and a row id, both of which you already have. The tenant boundary is your credential.

Why keyset and not offset: the customer this API is for is exporting six months of sessions from a table that is still being written to. With OFFSET, every row inserted ahead of the window shifts everything down — rows are silently skipped, others arrive twice, and the export looks complete. A keyset cursor pins the read to “strictly after this row”, so the walk is stable no matter what lands mid-export. has_more is derived by fetching one row beyond the page, not by a count. A count taken alongside the page is stale the moment it is taken, so it would be a number presented as authoritative that we could not stand behind.

Reusing a cursor under a different sort is rejected

# First page sorted by created_at, then switching to score — refused.
?sort=created_at&cursor=...   →  ok
?sort=score&cursor=...        →  400 invalid_cursor

The cursor simply does not describe a position in the new ordering, so returning data would be quietly wrong rather than an error.

Common list parameters

Every list endpoint accepts these; per-endpoint filters are on each operation.

Parameter	Notes
`limit`	Default 50, maximum 200. Over the max is a `400`, not a silent clamp.
`cursor`	A `next_cursor` from a previous page.
`sort`	Validated against that endpoint’s allowed fields.
`order`	`asc` or `desc`. Default `desc`.
`created_after` / `created_before`	ISO 8601. A backwards window is a `400`.

Strict parameters

An unrecognised query parameter is a 400, not a shrug.The failure this prevents is the expensive one: you write ?since=2026-01-01, get a 200 and a full first page, and conclude your filter worked — then reconcile against a number that was never filtered. Silently ignoring a parameter is indistinguishable from honouring it.

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_parameter",
    "message": "Unknown query parameter 'since'. This endpoint accepts: created_after, created_before, cursor, limit, order, sort.",
    "param": "since"
  },
  "request_id": "req_xxx"
}

The same applies to duplicates — ?status=new&status=won has no obvious meaning, so picking one silently discards the other. On writes, unknown body keys are rejected, not dropped; enums are enums, not free strings; and money is in minor units (cents), never decimals.

Errors

One shape, everywhere:

{
  "error": {
    "type": "invalid_request_error",
    "code": "unknown_parameter",
    "message": "Unknown query parameter 'since'. …",
    "param": "since"
  },
  "request_id": "req_xxx"
}

type — the coarse family. Branch on this; it is stable.
code — the specific machine label.
message — what was expected, in words.
param — the offending query parameter or dotted body path, when there is one.

`type`	Status	Meaning
`authentication_error`	401	Missing, invalid, revoked, or the wrong kind of credential
`invalid_request_error`	400, 403	A bad parameter, or an insufficient role
`not_found_error`	404	No such record in this workspace
`rate_limit_error`	429	Over the ceiling; carries `Retry-After`
`api_error`	500, 503	Our side

404 is deliberately ambiguous

A record belonging to another workspace and a record that does not exist return the identical 404. A distinguishable 403 would turn the endpoint into an existence oracle for other tenants’ ids. The same collapse applies to MCP: a token for a different workspace than the URL gets the same 404 as an unknown workspace.

401 vs 403

401 — the credential is wrong: missing, invalid, revoked, or the wrong kind. The message names what arrived and what was wanted.
403 — the credential is fine; the role does not reach. See Roles.

Rate limits

Every /v1 endpoint shares one bucket per credential, not a bucket per endpoint. Per-endpoint buckets would let a caller multiply their real ceiling by the number of endpoints we happen to have shipped, so the published limit would drift upwards every time we added a route. Ceilings follow your plan — see Rate limits. A rate-limited response carries Retry-After in seconds. A call refused for role reasons is rejected before the limiter charges your workspace: a call that was never allowed should not consume your budget.

Overview

Sessions

Contacts

Users

Leads

Meetings

Hand-offs

Analytics

Configuration

Webhooks

Ask

API conventions

The envelope

Reusing a cursor under a different sort is rejected

Common list parameters

Strict parameters

Errors

404 is deliberately ambiguous

401 vs 403

Rate limits

​The envelope

​Pagination

​Reusing a cursor under a different sort is rejected

​Common list parameters

​Strict parameters

​Errors

​404 is deliberately ambiguous

​401 vs 403

​Rate limits

The envelope

Pagination

Reusing a cursor under a different sort is rejected

Common list parameters

Strict parameters

Errors

404 is deliberately ambiguous

401 vs 403

Rate limits