API Endpoints

Heka exposes a REST API via FastAPI. The interactive docs are available at:

• Swagger UI: https://heka-operator.fly.dev/docs
• ReDoc: https://heka-operator.fly.dev/redoc
• OpenAPI JSON: https://heka-operator.fly.dev/openapi.json

Endpoint groups

Authentication (/auth)

Method	Path	Description
POST	/auth/register	Register a new operator
POST	/auth/login	Login, returns JWT token

Campaigns (/campaigns)

Method	Path	Description
GET	/campaigns	List all campaigns
GET	/campaigns/board	Campaign board view (funnel cards)
POST	/campaigns/drafts	Create a draft campaign
POST	/campaigns/send	Blast send to campaign audience
GET	/campaigns/{id}	Get campaign details
PATCH	/campaigns/{id}	Update campaign fields
DELETE	/campaigns/{id}	Delete a campaign
POST	/campaigns/{id}/approve	Approve draft for sending
POST	/campaigns/{id}/archive	Archive campaign
POST	/campaigns/{id}/unarchive	Unarchive campaign
POST	/campaigns/{id}/duplicate	Duplicate a campaign
POST	/campaigns/{id}/launch	Launch campaign pipeline
POST	/campaigns/{id}/test-send	Test send to allowlisted numbers
GET	/campaigns/{id}/status	Campaign execution status
GET	/campaigns/{id}/phases	List pipeline phases
GET	/campaigns/{id}/phases/{phase}	Get phase details
PUT	/campaigns/{id}/phases/{phase}/skill	Update phase agent instructions
POST	/campaigns/{id}/contacts/{wa_id}/phase	Move contact to phase

See also: Tracked Sending for the new tracked send endpoints.

Campaign resources (/campaigns/{id}/resources)

Method	Path	Description
GET	/campaigns/{id}/resources	List campaign resources
POST	/campaigns/{id}/resources	Add a resource (JSON or multipart)
PUT	/campaigns/{id}/resources/{rid}	Update a resource
DELETE	/campaigns/{id}/resources/{rid}	Delete a resource

Contacts (/contacts)

Method	Path	Description
GET	/contacts	List contacts (with search, filters)
POST	/contacts/bulk-tag	Bulk tag contacts
PATCH	/contacts/{wa_id}/context	Update contact context JSON
PATCH	/contacts/{wa_id}/name	Update contact display name
PATCH	/contacts/{wa_id}/stage	Update contact lead stage
POST	/contacts/{wa_id}/tags	Add tag to contact
DELETE	/contacts/{wa_id}/tags/{tag_id}	Remove tag from contact
GET	/contacts/{wa_id}/related	List related contacts
POST	/contacts/{wa_id}/related	Add related contact
PUT	/contacts/{wa_id}/related/{rc_id}	Update related contact
DELETE	/contacts/{wa_id}/related/{rc_id}	Delete related contact

Conversations (/conversations)

Method	Path	Description
GET	/conversations	List active conversations
GET	/conversations/closed	List closed conversations
GET	/conversations/{wa_id}/timeline	Message timeline for contact
POST	/conversations/{wa_id}/messages	Send a text message
POST	/conversations/{wa_id}/media	Send a media message
POST	/conversations/{wa_id}/ownership	Set ownership (agent/human)
POST	/conversations/{wa_id}/close	Close conversation
POST	/conversations/{wa_id}/close-session	Close session
POST	/conversations/{wa_id}/dismiss	Dismiss from inbox
POST	/conversations/{wa_id}/undismiss	Undismiss

Handoffs (/api/handoffs)

Method	Path	Description
GET	/api/handoffs	List pending handoff requests
POST	/api/handoffs/{wa_id}/accept	Accept handoff (operator takes over)
POST	/api/handoffs/{wa_id}/release	Release handoff (back to AI)

Templates (/templates)

Method	Path	Description
GET	/templates	List all templates (cached from Meta)
POST	/templates	Create a new template on Meta
DELETE	/templates/{name}	Delete a template
POST	/templates/{name}/duplicate	Duplicate a template
GET	/templates/{name}/status	Check template approval status

Segments (/segments)

Method	Path	Description
GET	/segments	List all segments
POST	/segments	Create a segment
GET	/segments/{id}	Get segment details
PUT	/segments/{id}	Update segment
DELETE	/segments/{id}	Delete segment
GET	/segments/{id}/count	Count contacts matching segment

Tags (/tags)

Method	Path	Description
GET	/tags	List all tags
POST	/tags	Create a tag

Tenant (/tenant)

Method	Path	Description
GET	/tenant/canned-responses	List canned responses
POST	/tenant/canned-responses	Create canned response
PUT	/tenant/canned-responses/{id}	Update canned response
DELETE	/tenant/canned-responses/{id}	Delete canned response
GET	/tenant/documents	List tenant documents
POST	/tenant/documents	Add tenant document
PUT	/tenant/documents/{id}	Update tenant document
DELETE	/tenant/documents/{id}	Delete tenant document

Media (/media)

Method	Path	Description
POST	/media/upload	Upload media to R2
GET	/media/{sha256}	Serve media by hash

Push notifications (/push)

Method	Path	Description
GET	/push/vapid-public-key	Get VAPID public key
POST	/push/subscribe	Subscribe to push notifications

Webhook (/webhook)

Method	Path	Description
GET	/webhook	Meta verification challenge
POST	/webhook	Inbound message/status webhook