Customs OS API

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.

checking session…

Meta & session

GET/healthAuth method, people signed in, keeper, page cache
GET/v1/sessionCaller's session: identity, expiry, people signed in
POST/v1/session/refreshForce a token refresh for the caller
GET/v1/session/doctorDeep per-user health check + remediation
GET/oauth/startBrowser sign-in (Google, PKCE) — per person, no browser profile
POST/v1/oauth/startProgrammatic sign-in: returns the Google URL
GET/v1/oauth/statusSign-in state, auth method, login URL
GET/v1/meAuth user + app user row for the caller

Agent & access

GET/AGENTS.mdAgent guide (markdown)
GET/llms.txtAgent guide (plain text)
GET/v1/agent/manifestCapabilities, scopes, workflows (JSON)
GET/v1/agent/whoamiWhich token and scopes you are using
GET/v1/selfcheckRead-only capability check: session, reads, action registry
GET/v1/me/tokensYour own tokens (metadata only)
POST/v1/me/tokensMint a token for yourself: {label, scopes, ttl_days}
DELETE/v1/me/tokens/{id}Revoke one of your tokens
GET/v1/actionsFull action catalog: every action name → current id
GET/v1/admin/actionsRegistry health: deployment, freshness, required ids
POST/v1/admin/actions/refreshRe-discover action ids after a site deploy
GET/v1/admin/usersEveryone who has signed in with Google
GET/v1/admin/tokensList agent tokens
POST/v1/admin/tokensMint a token for any user: {label, scopes, ttl_days}
DELETE/v1/admin/tokens/{id}Revoke a token
GET/v1/admin/audit?limit=100Recent audit entries
GET/healthzUnauthenticated liveness probe

Deals

GET/v1/deals?brand=FK&stage=won&limit=25&order=-won_atList or search deals
GET/v1/deals/{id}Deal by id
GET/v1/deals/{id}/notesDeal notes
GET/v1/deals/{id}/attachmentsDeal attachments
GET/v1/deals/{id}/quoteQuote attached to a deal
POST / PATCH / DELETE/v1/deals[/{id}]Write deal rows (RLS applies)

Customers & contacts

GET/v1/customers?q=acme&order=-lifetime_gpList or search customers
GET/v1/customers/{id}Customer by id
GET/v1/customers/{id}/dealsCustomer deals
GET/v1/customers/{id}/contactsCustomer contacts
GET/v1/customers/tableServer-computed customers table payload
GET/v1/contacts?q=janeList or search contacts
GET/v1/contacts/{id}Contact by id

Quotes

GET/v1/quotes?status=NEEDS_ACTION&brand=FKList or search quotes
GET/v1/quotes/{id}Quote with line items
GET/v1/quotes/{id}/line-itemsQuote line items
GET/v1/quotes/intake-formPrice list / categories used by the intake form

Other tables

GET/v1/brandsBrands
GET/v1/usersUsers
GET/v1/users/{id}User by id
GET/v1/notifications?unread=trueNotifications
POST/v1/notifications/{id}/readMark notification read
GET/v1/deal-attachments?deal_id=eq.{id}All deal attachments
GET/v1/db/{table}Generic select over the allowed tables

Site API replay

GET/v1/app/notificationsNotification feed with items
GET/v1/app/notifications/statusUnread badges
GET/v1/app/sms/pulseSMS pulse
GET/v1/app/inbox/pulseInbox pulse
GET/v1/app/inbox/emailMailboxes and email threads
GET/v1/app/changelog/statusChangelog status
GET/v1/app/approvals/headerApprovals header

Deal writes (server actions)

GET/v1/deals/{id}/formCurrent field values, select options + draft / save / pitch action ids
POST/v1/deals/{id}/saveSave draft (default), Post Deal or request 3D pitching
GET/v1/actionsFind any action by name (ids rotate per deploy)
POST/v1/actions/invokeCall any client server action by name or id with JSON args
GET/v1/actions/formDiscover a page's form, fields, select options and bound action ids
POST/v1/actions/formReplay any form-mounted server action

Deal workflow (2.3.0)

GET/v1/teamPeople on the deal: id, name, role, home brand. Brand is display only.
POST/v1/dealsCreate a deal via createDealAction. Dry-run by default. Shows duplicate and repeat-customer matches.
GET/v1/deals/{id}/tasksOpen and completed tasks, including the complete descriptor.
POST/v1/deals/{id}/tasksAdd 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}/completeMark a task done.
POST/v1/deals/{id}/tasks/{taskId}/reassignReassign. 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}/notesAdd 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}/filesUpload a file or an AE mockup. The storage token is never returned.
PATCH/v1/deals/{id}/valueChange one product unit price through the draft save.
PATCH/v1/deals/{id}/aeChange the AE on an open deal.
PATCH/v1/deals/{id}/expected-close-dateSet the expected close date.
POST/v1/deals/{id}/productsAppend a product, or one catalogue row when the search matches once.
POST/v1/deals/{id}/products/{index}/archiveArchive a product line.
POST/v1/deals/{id}/products/{index}/restoreRestore 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/catalogSearch the deal price list.
POST/v1/deals/{id}/stageMove 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-candidatesSuggested or searched duplicates.
POST/v1/deals/{id}/mergePreview a merge. confirm plus Idempotency-Key closes the duplicate as Lost.
POST/v1/deals/{id}/emailSend from the deal composer, with inline images. HTML is converted. Requires the email scope.
GET/v1/deals/{id}/templatesComposer templates. fill=true substitutes merge fields.
GET/v1/deals/{id}/price-listPrice-list tabs and slugs for this deal.
POST/v1/price-lists/imageRender a price-list card as a PNG.
POST/v1/deals/{id}/upsells/addonDry-run an add-on upsell. The live argument list is not recorded.
POST/v1/deals/{id}/upsells/rushDry-run a rush-fee upsell. The live argument list is not recorded.
POST/v1/deals/{id}/upsells/{upsellId}/cancelDry-run cancelling an upsell. The live argument list is not recorded.

Money tab

GET/v1/deals/{id}/moneyMoney components + card-fee invoice preview
POST/v1/deals/{id}/money/invoiceGenerate balance invoice + share link
GET/v1/deals/{id}/money/invoice/paid-stateIs the balance invoice paid
GET/v1/deals/{id}/commsComms tab composers and threads

Email

GET/v1/email/mailboxesMailboxes and send-from addresses
GET/v1/email/threads?box=inbox&q=List email threads
GET/v1/email/threads/{mailbox:threadId}Read a thread's messages
POST/v1/email/sendSend a new email
POST/v1/email/replyReply in a thread
GET / POST/v1/email/scheduledList or schedule emails
DELETE/v1/email/scheduled/{id}Cancel a scheduled email

SMS

GET/v1/sms/inboxLines and SMS threads
POST/v1/sms/sendSend on a thread or on a deal
POST/v1/sms/threads/startOpen the SMS thread for a deal

Server-rendered pages

GET/v1/commissionsCommission draft, lines, people, totals
GET/v1/refundsRefund queue and counts
GET/v1/analytics/pipelinePipeline analytics
GET/v1/deals/hero-chartDeals hero chart
GET/v1/pages/{path}?component=NameAny page, decoded RSC props
POST/v1/pages/cache/clearClear page cache
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