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 ~300 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.
Team channel	The team-scoped connection row that contributes an allowed Amazon profile. This is the current source for profile access; legacy account-connection rows are not the active-profile source.
Account / account group	An Amazon advertising account grouping used by connection and compatibility surfaces. It is not the request’s current scope anchor.
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.
Dynamic dashboard artifact	A team + country-scoped dashboard DSL artifact, with a planner, preview runner, and execution history. Its preview resolves an active profile from the allowed set.
Persona / audience run	A DSP audience-targeting expression and its Persona Builder insight, optionally persisted as a run snapshot; combined-audience create/delete are separate approval-backed mutations.
Reach forecast	A DSP reach, performance, or deduplicated-reach forecast request/result with normalized efficiency metrics and a deterministic recommendation.
Chat session	A conversation. A regular chat answers; an action chat can also propose changes.
Action request	An approval-backed proposed action — normally an action-chat mutation or local report-schedule change — recorded as pending, shown as an approval card, and dispatched only after approval. It is not the unit of every database write.
Report	A generated analysis — predefined or custom AI report, with schedule settings stored in Pulsy’s database.
Notification	Proactive and unified notification records: scoped lifecycle events, suggested actions, comments, invitations, report, support, and system alerts.

The chain most scope-sensitive data calls walk: you → current team + country → team channels → allowed profiles → active profile → DSP advertiser / AMC context when needed. If a link is missing, the call can’t resolve that 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. The resolver chooses a caller-preferred profile if it is allowed, then the team’s derived main profile if allowed, then the highest-ranked allowed connection using a deterministic connected/direct-access/type/profile sort. A fresh session may still ask you to pick one before returning numbers.
Unresolved scope fails closed. No resolved team → 400 TEAM_CONTEXT_REQUIRED. A scope-bound route with a team but missing country commonly returns 409 CURRENT_SCOPE_INCOMPLETE; the action-chat submit path fails fast with 400 COUNTRY_CONTEXT_REQUIRED. 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.
Opt-in action tools stay opt-in. Persona Builder and Reach Planning action-chat tools are not registered unless their environment flags are enabled, and both require a country scope. Their model/API contracts can exist even when those live action tools are disabled.

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)

~300 endpoints across 58 router modules, 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, proactive events.
Reports — weekly, custom AI reports, complex reports, templates/schedules, comments and locale helpers.
Agent / campaigns — agent-campaigns, optimize-cycle, diagnose-runs, action-requests/apply, Persona Builder, Reach Planning, and AMC.
Dashboards / notifications — dynamic dashboard artifacts and previews, inbox, proactive notifications, and unified notifications.
Home / support / channels / memory.
Crawling, vendor-sale-report, admin/events/Auth0 webhook, Prefect dashboard, profile/channel reconciliation, and 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.