Each person signs in with Google once; every request then runs as that person, so RLS applies — you see exactly what your account sees in the app. No shared owner session.
| GET | /health | Auth method, people signed in, keeper, page cache |
| GET | /v1/session | Caller's session: identity, expiry, people signed in |
| POST | /v1/session/refresh | Force a token refresh for the caller |
| GET | /v1/session/doctor | Deep per-user health check + remediation |
| GET | /oauth/start | Browser sign-in (Google, PKCE) — per person, no browser profile |
| POST | /v1/oauth/start | Programmatic sign-in: returns the Google URL |
| GET | /v1/oauth/status | Sign-in state, auth method, login URL |
| GET | /v1/me | Auth user + app user row for the caller |
| GET | /AGENTS.md | Agent guide (markdown) |
| GET | /llms.txt | Agent guide (plain text) |
| GET | /v1/agent/manifest | Capabilities, scopes, workflows (JSON) |
| GET | /v1/agent/whoami | Which token and scopes you are using |
| GET | /v1/selfcheck | Read-only capability check: session, reads, action registry |
| GET | /v1/me/tokens | Your own tokens (metadata only) |
| POST | /v1/me/tokens | Mint a token for yourself: {label, scopes, ttl_days} |
| DELETE | /v1/me/tokens/{id} | Revoke one of your tokens |
| GET | /v1/actions | Full action catalog: every action name → current id |
| GET | /v1/admin/actions | Registry health: deployment, freshness, required ids |
| POST | /v1/admin/actions/refresh | Re-discover action ids after a site deploy |
| GET | /v1/admin/users | Everyone who has signed in with Google |
| GET | /v1/admin/tokens | List agent tokens |
| POST | /v1/admin/tokens | Mint a token for any user: {label, scopes, ttl_days} |
| DELETE | /v1/admin/tokens/{id} | Revoke a token |
| GET | /v1/admin/audit?limit=100 | Recent audit entries |
| GET | /healthz | Unauthenticated liveness probe |
| GET | /v1/team | People on the deal: id, name, role, home brand. Brand is display only. |
| POST | /v1/deals | Create a deal via createDealAction. Dry-run by default. Shows duplicate and repeat-customer matches. |
| GET | /v1/deals/{id}/tasks | Open and completed tasks, including the complete descriptor. |
| POST | /v1/deals/{id}/tasks | Add a task. An open deal with no close date needs expectedCloseDate. |
| PATCH | /v1/deals/{id}/tasks/{taskId} | Reschedule or rename. CS and AE tasks use different actions. |
| POST | /v1/deals/{id}/tasks/{taskId}/complete | Mark a task done. |
| POST | /v1/deals/{id}/tasks/{taskId}/reassign | Reassign. Requires confirm. Cross-brand is allowed. |
| DELETE | /v1/deals/{id}/tasks/{taskId} | Delete a task. Requires confirm. Owner refusals are 403. |
| POST | /v1/deals/{id}/notes | Add a note (FormData body). |
| PATCH | /v1/deals/{id}/notes/{noteId} | Edit a note. |
| DELETE | /v1/deals/{id}/notes/{noteId} | Delete a note. Requires confirm. |
| POST | /v1/deals/{id}/files | Upload a file or an AE mockup. The storage token is never returned. |
| PATCH | /v1/deals/{id}/value | Change one product unit price through the draft save. |
| PATCH | /v1/deals/{id}/ae | Change the AE on an open deal. |
| PATCH | /v1/deals/{id}/expected-close-date | Set the expected close date. |
| POST | /v1/deals/{id}/products | Append a product, or one catalogue row when the search matches once. |
| POST | /v1/deals/{id}/products/{index}/archive | Archive a product line. |
| POST | /v1/deals/{id}/products/{index}/restore | Restore an archived product line. |
| DELETE | /v1/deals/{id}/products/{index} | Remove a product line. Requires confirm and lists side effects. |
| GET | /v1/deals/{id}/products/catalog | Search the deal price list. |
| POST | /v1/deals/{id}/stage | Move canonical stage. Closed deals are refused with deal_not_open. Won, Lost and reopen need allowClose and never run on test deals. |
| GET | /v1/deals/{id}/merge-candidates | Suggested or searched duplicates. |
| POST | /v1/deals/{id}/merge | Preview a merge. confirm plus Idempotency-Key closes the duplicate as Lost. |
| POST | /v1/deals/{id}/email | Send from the deal composer, with inline images. HTML is converted. Requires the email scope. |
| GET | /v1/deals/{id}/templates | Composer templates. fill=true substitutes merge fields. |
| GET | /v1/deals/{id}/price-list | Price-list tabs and slugs for this deal. |
| POST | /v1/price-lists/image | Render a price-list card as a PNG. |
| POST | /v1/deals/{id}/upsells/addon | Dry-run an add-on upsell. The live argument list is not recorded. |
| POST | /v1/deals/{id}/upsells/rush | Dry-run a rush-fee upsell. The live argument list is not recorded. |
| POST | /v1/deals/{id}/upsells/{upsellId}/cancel | Dry-run cancelling an upsell. The live argument list is not recorded. |
Sign-in: on a bot or cloud workspace run
npm run login. It prints the Google
URL and accepts the pasted callback; the browser does not need to reach loopback.
--browser
still opens a local tab. Sign-in stores the session and does not mint a token. Mint one per bot with
npm run token -- create --label … --out file (mode 600;
--print to show it).
Admin is never included unless requested. Manage tokens at
/v1/me/tokens.
Writes: deal and money changes replay the app's own Next.js server actions, so they behave
exactly like clicking the button in the UI.
POST /v1/deals/{id}/save defaults to
mode=draft; pass
mode=save to actually Post Deal, and
dryRun: true on any write to inspect the payload first.
Filters: any query key that is not reserved is an equality filter.
Use
filter.<column>=gte.1000,
filter.status=in.(won,lost),
filter.read_at=is.null for other operators. Pagination is
limit /
offset (or
page), ordering is
order=-created_at.
Machine-readable spec:
/openapi.json · Agent guide:
/AGENTS.md