Reference

This reference is model-first: start from the resources and the rules, and the endpoints become predictable. The exhaustive per-endpoint reference (request / response shapes for ~260 endpoints) is pending a source-of-truth decision — see the note at the end.

Core resources and how they relate

Resource	What it is
Account user	You, as Pulsy knows you — the canonical record of who you are and what you belong to.
Team	The workspace you act in. Membership is single-tier; exactly one team is current.
Country	Paired with your team to form your current scope. Data is read within a team + country pair.
Account / account group	The Amazon advertising account grouping your profiles hang off.
Profile	An Amazon advertising profile — the unit you pull ad data for. You have an allowed set and one active profile at a time.
Advertiser	The DSP (programmatic) advertiser identity, used for DSP and AMC data.
AMC context	The resolved brand + instance + advertiser + marketplace needed to query Amazon Marketing Cloud.
Chat session	A conversation. A regular chat answers; an action chat can also propose changes.
Action request	A proposed change to a campaign — recorded as pending, shown as an approval card, applied only after approval. The unit of every write.
Report	A generated analysis — predefined or custom AI report.

The chain most data calls walk: you → team + country → account/group → allowed profiles → active profile → AMC context. If a link is missing, the call can’t resolve a scope.

Scope, tenancy, and the rules you can predict from

Current scope = team + country, resolved from your account on each request — not read from a header you pass. Switching team or country is its own action.
Allowed vs. active profile. A request runs against exactly one active profile (your preferred if allowed, else the account’s main, else a stable fallback). A fresh session may ask you to pick one before returning numbers.
Unresolved scope fails closed. No resolved team → 400 TEAM_CONTEXT_REQUIRED; team but missing required country → 409 CURRENT_SCOPE_INCOMPLETE. Empty results often mean “scope not resolved,” not “no data.”
404 hides existence. Reading something that isn’t yours returns 404, not 403 — Pulsy won’t confirm it exists. (A few legacy surfaces still return 403.)
Cross-scope is deliberately not a thing. One request answers within one scope; to get different numbers, change the scope.

Auth schemes

Three coexist (which, if any, becomes partner-facing is a deferred decision):

Auth0 Bearer — user requests; validated via /userinfo with a short cache.
X-API-Key / ADMIN_API_KEY — admin, crawling, memory, and MCP mounts.
X-Dashboard-Key — the internal Prefect dashboard.

The endpoint map (groups)

~260 endpoints across ~50 routers, grouped:

Identity / teams / connect — me, teams, channels, invitations, Amazon & Shopify account-connect (OAuth).
Chat — /pulsy/action-chats (the live SSE surface); /pulsy/chats (legacy PSM); chatrooms, presets, favorites.
Reports — weekly, custom AI reports, complex reports, templates/schedules.
Agent / campaigns — agent-campaigns, optimize-cycle, diagnose-runs, action-requests/apply, AMC.
Home / inbox / notifications / support.
Memory — admin API (X-API-Key).
Crawling, vendor-sale-report, admin/events/Auth0 webhook, Prefect dashboard, MCP mounts — internal/ops surfaces.

The per-endpoint reference

There is no static OpenAPI export in ai-api today (the spec is generated at runtime, behind HTTP Basic). So the exhaustive request/response reference is deferred pending a source-of-truth decision — export an openapi.json from a running instance, or hand-author from the FastAPI routers. Tracked in _internal/needs-johnny.md. When settled, this section fills in, grouped as above, with placeholder-only examples (the common case plus the one edge case people trip on).

Available now

Data model — what Pulsy knows (the six analysts).
Capabilities — read vs. write and the gates.
Glossary — Amazon-advertising and PulseAd terms.