api reference

dripos is a Mac app first. The backend API exists for account bootstrap, API keys, hosted integration status, OAuth pairing, Stripe OAuth, and email-open sync. The Inbox/person directory, communication timeline, drafts, account signals, and Copilot run against local app/sidecar surfaces. For the full OpenAPI 3.1 spec for public backend routes, see /openapi.json.

CLI

brew tap DripYCx26/drip
brew install drip-cli

dripos <name>                 # search local customer/person history
drip-cli doctor --json        # source health diagnostics used by Settings
drip-cli reply list --json    # pending and historical reply drafts
drip-cli reply send <id>      # send an approved draft through the original channel

The CLI and sidecar read/write local state under ~/.drip-cli/. Source sync and draft state are local unless a specific hosted integration or LLM provider is involved.

HTTP conventions

Base URL: https://api.drippay.dev/v1
Auth: Authorization: Bearer <key> for sk_* and pk_* API keys; Privy sessions for browser dashboard flows.
Content type: application/json
Timestamps: RFC 3339 UTC unless a route documents otherwise.
Errors: JSON { error, code, details? } with stable code strings.

Paths below are relative to /v1.

account bootstrap

method	path	current Mac app use
GET	`/auth/key/verify`	verifies a saved API key without deleting valid non-Privy credentials
POST	`/businesses/register`	creates or completes the signed-in user’s business/workspace
POST	`/dashboard/api-keys`	mints the `sk_` key saved in Keychain as `drip-api-key`
GET	`/dashboard/api-keys`	lists keys for dashboard/settings contexts
DELETE	`/dashboard/api-keys/:id`	revokes a key
POST	`/dashboard/api-keys/:id/rotate`	rotates a key where the dashboard flow exposes rotation

The Mac app creates a key named dripos Mac App with owner-level access, stores the one-time secret in macOS Keychain, and uses it for later backend calls.

hosted integration status

method	path	current Mac app use
GET	`/dashboard/integrations/status`	reads hosted integration state for the Integrations screen and source indicators
DELETE	`/dashboard/integrations/:id`	disconnects hosted marketplace integrations such as Stripe
DELETE	`/dashboard/integrations/comms/:id`	removes hosted communication integration rows

Local token bundles are cleared by native app commands when a provider uses local OAuth storage.

OAuth pairing

Google and Slack use pairing flows so provider tokens end up on the Mac instead of staying in the browser callback session. Fathom pairing support may exist in backend/local code, but it is not a normal first-class Integrations card in the current Mac app.

method	path	purpose
POST	`/oauth/pair/start`	creates a pair code and provider authorize URL
GET	`/oauth/google/callback`	provider redirect target for Google
GET	`/oauth/slack/callback`	provider redirect target for Slack
GET	`/oauth/fathom/callback`	provider redirect target for Fathom
POST	`/oauth/pair/claim`	atomically claims the provider token bundle into the Mac app
POST	`/oauth/refresh`	refreshes a Google access token for local clients

Granola, Circleback, Cal.com, and Calendly use local OAuth/MCP-style flows in the Mac app rather than hosted backend comms install routes. Pocket AI may exist in older local status surfaces, but it is not a normal first-class Integrations card in the current Mac app.

Stripe OAuth

method	path	purpose
POST	`/integrations/stripe/oauth/init`	starts Stripe Connect OAuth from the Mac app
GET	`/integrations/stripe/oauth/callback`	finishes Stripe Connect OAuth and redirects back to the app or dashboard

The current Mac app exposes Stripe OAuth, manage, and disconnect. It does not expose the older Stripe restricted-key paste flow.

email opens

drip-cli polls one backend endpoint to reconcile email-pixel opens into its local database.

method	path	purpose
GET	`/opens-since`	list email opens since a Unix-second watermark

Query parameters:

name	type	required	description
`ts`	integer	yes	returns opens with `opened_at >= ts`
`limit`	integer	no	max rows, default `1000`, cap `5000`

Unknown tokens are ignored locally. Mailbox prefetchers can create synthetic opens, so clients should treat open counts as signal rather than proof of human read.

local native surfaces

These are Tauri/native commands or local sidecar surfaces, not api.drippay.dev routes. They are the current Mac app contract for the Inbox/person detail product.

surface	purpose
`local_people_list`	reads the local person directory from `~/.drip-cli/drip-cli.db`
`comms_timeline_query`	returns unified local message, meeting, Stripe, and timeline events
`reply_draft_create` and reply draft helpers	create, list, approve, reject, send, retry, and repair reply drafts
`local_oauth_status`	reports local source token state for Google, Slack, meeting/scheduling MCP providers, and any legacy local OAuth bundles present in that build
`oauth_store_token_bundle`	writes claimed OAuth token bundles to local storage
`llm_chat`	sends selected local context to Anthropic, OpenAI, or Ollama
`agent_store_*`	stores Copilot thread, step, and pending-intent state locally
`autopilot_config_*`	manages background autopilot config, allowed contacts, model, mode, and send delay
`launchd_install_autopilot`	installs the background launchd runner

The current Inbox and Copilot screens do not compose the legacy dashboard customer endpoints for their normal UI.

legacy dashboard surfaces

The billing/dashboard backend still contains routes such as /dashboard/customers/*, /dashboard/customers/:id/drip-cli-*, and /dashboard/copilot/*. Those are dashboard or legacy integration surfaces. They are not the current Mac app contract for the local Inbox person detail page or Copilot chat.

common errors

HTTP	code	meaning
400	`VALIDATION_ERROR`	request validation failed
401	`INVALID_API_KEY`	missing, malformed, expired, or revoked credential
403	`INSUFFICIENT_ROLE`	credential exists but lacks the required role
404	`NOT_FOUND`	resource is missing or outside this business
409	`CONFLICT`	duplicate or incompatible state
422	`UNPROCESSABLE`	semantically invalid request
429	`RATE_LIMITED`	request was rate limited
503	`LLM_NOT_CONFIGURED`	legacy dashboard Copilot route has no configured LLM

OpenAPI

Machine-readable schema: https://docs.drippay.dev/openapi.json. Regenerate it from the backend with npx tsx scripts/export-openapi.ts; do not hand-edit the generated JSON.

​api reference

​CLI

​HTTP conventions

​account bootstrap

​hosted integration status

​OAuth pairing

​Stripe OAuth

​email opens

​local native surfaces

​legacy dashboard surfaces

​common errors

​OpenAPI