API reference

Unified communication infrastructure for Sunhub Blues.

Build against one gateway for conversations, outbound messages, inbound events, workflows, market accounts, contacts, and communication connectors.

Base URLhttps://api.sunhubapp.com/v1

AuthAPI key or workspace session

RealtimeWebSocket + durable event replay

Quickstart

Create an API key from the app, call the gateway, then use the same key for server-side integrations.

GET/v1/gatewaypublic

GET/v1/gateway/meAPI key

Use /gateway to discover the API surface and /gateway/me to verify credentials.

Authentication

Browser users authenticate through the workspace/session path. External systems and channel adapters use API keys.

Server-side integrations

Send API keys in X-Sunhub-Api-Key or as a bearer token.

Browser app

Do not embed API keys in Lovable or browser code. Use user/session auth for frontend requests.

Messages

Use the v3 app API for the unified inbox. Each conversation row is a person thread and may contain iMessage, SMS, WhatsApp, and email messages.

GET/v3/conversations

GET/v3/conversations/{conversation_id}/messages

POST/v3/messages

Channel message resolves to iMessage when verified, with SMS fallback when needed.

Inbound events

All provider adapters normalize inbound messages into one channel-agnostic pipeline. This is for servers, agents, and webhooks, not browser UI.

POST/v3/inbound_eventsscope: inbound:write

POST/v3/provider_events/{provider}scope: inbound:write

POST/v3/connectors/{connector_id}/gmail/watchscope: connectors:write

Inbound messages are only shown when the contact exists and Sunhub initiated the conversation on that channel group. Gmail provider events should use push/history sync; worker polling is only a fallback.

Realtime

Subscribe once and merge durable events into the active thread.

WS/v1/app/realtime/ws

GET/v1/app/events?since={server_time}

Handle message.created, message.updated, job.updated, workflow.run.updated, and identity.verification.updated.

Market

Import and manage companies, contacts, segments, stages, custom fields, and target audiences.

GET/v1/app/market/accounts

POST/v1/app/market/import

GET/v1/app/people/{person_id}/profile

Workflows

Workflows are graphs with backend validation, dry-run previews, pacing, branches, waits, and channel-specific send nodes.

GET/v1/app/workflows/templates

POST/v1/app/workflows/{workflow_id}/validate

POST/v1/app/workflows/{workflow_id}/dry-run

POST/v1/app/workflows/{workflow_id}/start

Integrations

Connectors sit behind the gateway. Keep provider credentials out of the frontend.

Gmail

OAuth, multiple accounts, thread-scoped inbound sync.

WhatsApp

Evolution API webhooks, QR reconnect, debug backfill.

RingCentral SMS

Line discovery, outbound SMS, inbound SMS webhook path.

iMessage

Local Mac agent for send, local Messages DB for inbound sync.

Zoho CRM

Read-only Accounts, Contacts, Leads, Deals, custom-field metadata, CRM badges, and scheduled reconciliation.

GET/v3/integrations/zoho/statusscope: connectors:read

GET/v3/integrations/zoho/auth-urlscope: connectors:write

POST/v3/integrations/zoho/syncIdempotency-Key

GET/v3/integrations/zoho/modules

GET/v3/companies/{company_id}/crm

GET/v3/contacts/{contact_id}/crm

GET/v3/opportunities

A Zoho record link never marks a company won. Only a closed-won Deal or the explicit mark-won API changes lifecycle to Won.

API keys

API keys are created from the app and shown once. Store them in server-side environments only.

GET/v1/app/api-keys

POST/v1/app/api-keys

POST/v1/app/api-keys/{api_key_id}/revoke

Errors

Responses use standard HTTP status codes. Error payloads return a useful detail, error, or validation object where available.

401

Missing or invalid authentication.

403

Authenticated but missing required role or API key scope.

404

Resource was not found in the current organization.

422

Payload failed validation.

Resources

Interactive Swagger reference

OpenAPI JSON

ReDoc reference