API reference

Base URL: local http://localhost:8083. All endpoints except /health and /pricing-plan need Authorization: Bearer <token>.

Interactive docs: /docs (Swagger) and /openapi.json on a running instance — always the source of truth over this page.

| ✅ | free-tier allowed  ·  | 💳 | needs premium (require_premium_company → 402)  ·  | 👤 | admin only  ·  | 🛠 | super-admin only |

Public

Method	Path	Notes
GET	/health	status, auth mode, stripe state
GET	/pricing-plan	plan name, price note, free/premium feature lists

Me & workspace — me.py

Method	Path		Notes
GET	/me	✅	current user + role
GET	/company	✅	workspace: name, industry, stages, is_premium, dormancy_days
PUT	/company	💳 👤	update name / industry / stages / dormancy threshold

Contacts — contacts.py (prefix /contacts)

Method	Path		Notes
GET	/contacts	✅	list; query params for search / stage / assignee
GET	/contacts/{id}	✅	one contact
GET	/contacts/{id}/interactions	✅	that contact's timeline
POST	/contacts	💳	create (only first_name required)
PUT	/contacts/{id}	💳	update fields / custom metadata
POST	/contacts/{id}/stage	💳	move to a stage (counts as activity)
POST	/contacts/{id}/interactions	💳	log an interaction (counts as activity)
DELETE	/contacts/{id}	💳	delete (cascades interactions + follow-ups)

Pipeline — pipeline.py

Method	Path		Notes
GET	/pipeline	✅	{ stages: [...], columns: [{ stage, contacts: [...] }] }, contacts sorted by recent activity

Follow-ups — followups.py (prefix /follow-ups)

Method	Path		Notes
GET	/follow-ups?state=	✅	list; state = pending / overdue / completed
POST	/follow-ups	💳	schedule one
POST	/follow-ups/{id}/complete	💳	mark done
POST	/follow-ups/{id}/reopen	💳	undo a completion
GET	/follow-ups/{id}/calendar.ics	✅	download as an .ics file

Agenda — agenda.py

Method	Path		Notes
GET	/agenda	✅	{ overdue: [...], today: [...], dormant: [...], counts: {...} }

Reports — reports.py (prefix /reports)

Method	Path		Notes
GET	/reports/conversion	✅	conversion / pipeline stats

Team — team.py (prefix /team)

Method	Path		Notes
GET	/team	👤	agents in the workspace
POST	/team	💳 👤	add an agent by email
POST	/team/assign	💳 👤	(re)assign a contact / routing

Sequences — sequences.py (prefix /sequences)

Method	Path		Notes
GET	/sequences	👤	list
GET	/sequences/runs	👤	fired steps (SequenceRun rows)
POST	/sequences	💳 👤	create
POST	/sequences/{id}/toggle	💳 👤	activate / deactivate
POST	/sequences/{id}/enroll	💳 👤	enroll a contact manually

Billing — billing.py (prefix /billing)

Method	Path		Notes
GET	/billing/status	👤	plan, subscription status
POST	/billing/checkout	👤	start Stripe Checkout
POST	/billing/portal	👤	Stripe customer portal link
POST	/billing/dev-upgrade	👤	"simulate payment" — flip to premium (Stripe-disabled builds)
POST	/billing/dev-downgrade	👤	flip back to free (testing)

Webhooks — webhooks.py

Method	Path	Notes
POST	/webhooks/stripe	Stripe events; checkout.session.completed → premium

Admin (super-admin) — admin.py (prefix /admin)

Method	Path		Notes
GET	/admin/companies	🛠	every workspace, cross-tenant
POST	/admin/companies/{id}/toggle-premium	🛠	flip any workspace's plan