REST API

Before you start

Authentication

Every endpoint names the dependency that guards it. There are three, and they accept different credentials:

route.auth carries {required, dependency, scope}. The accepted credentials and the exact failure body for each dependency live once, below, under auth_dependencies — look the dependency name up there. The `authorization` and `X-API-Key` headers are deliberately absent from route.params: FastAPI lists them because get_org_user declares them as Header() params, but they are the credential, not an option.

API keys are accepted with the prefixes xc_dev_, xc_live_, xc_test_, xc_stg_, xc_sbx_, xc_prev_. The 46 messaging routes take a Bearer JWT only.

Response envelopes

There is no single wrapper. Each endpoint states which of these it uses, so read that line before writing a client against it.

• success+data158

  {success: true, data: ...}, optionally with `pagination`.

• success+custom114

  Has `success`, but the payload is under other keys too — e.g. {success, contact, messages} or {success, data, recipients}.

• bare-model12

  The Pydantic response_model serialised directly. No `success`, no `data` — the model's fields are the top level.

• bare-object73

  A plain object or array with no envelope, built by the handler or a helper.

• html9

  text/html — including the error responses.

• binary9

  A file or image body (PDF, ICS, PNG, attachment, raw message source).

• text1

  text/plain (the CSV report export).

• redirect2

  A 3xx redirect rather than a body.

• empty1

  Returns None — a 200 with a null JSON body.

Errors

Failures are FastAPI's standard shape — an HTTP status and a detail string. Each endpoint lists the ones its own handler raises; where the message is computed, the expression is shown rather than a made-up sample.

{
  "detail": "Not authenticated — provide Bearer token or X-API-Key"
}

The statuses that carry a distinct meaning across the whole API, rather than one endpoint's own validation:

Where a 402 comes from is answerable in one call: GET /api/v1/salesshift/billing/entitlements returns the resolved plan and every allowance; Plans and self-hosting lists the five places in the product that raise it.

Two paths report a refusal inside a 200 body instead of raising, because both run in loops over many rows and one refused row must not fail the batch. POST /api/v1/salesshift/email/send answers 200 with status: "failed" and provider: "refused", the reason in error; POST /api/v1/salesshift/ai/write-email answers 200 with source: "template" and the reason in reason. A client that reads only the status code will record both as successes.

What the badges mean

• live-callCalled against http://127.0.0.1:8741 during this inventory run; the `verified` block holds the request and the response.
• session-verifiedThe feature was verified working against the live system in the session that produced this inventory, but this specific route was not re-called here.
• code-onlyRead in source for this inventory and not executed. Undemonstrated is not the same as broken — but do not write it up as proven.
• known-unprovenOne of the two items in known_unproven.

Do not upgrade a `code-only` route to a worked example in a doc. Either call it first and update this file, or write it as a reference entry without an 'it works like this' claim.

2 capabilities are built but unproven

Domains

The full entry for every endpoint — parameters, request and response shapes, error cases, a copyable curl — lives on its domain page.

All 379 endpoints

Filter by path, method or words from the summary. Every row links to its full entry.

These pages are generated from app/docs/_inventory.json, last updated on 2026-08-13 and produced by importing the live router objects and walking them, then calling 110 of the routes against a running server — 92 of them in the first pass against http://127.0.0.1:8741, the rest in the later passes the file records. The same file backs endpoints.json and llms.txt.