API Reference

The hub exposes a REST API on port 4101 with Swagger UI for interactive exploration.

Interactive Documentation

When the hub is running:

• Swagger UI: http://localhost:4101/api/docs
• OpenAPI spec: http://localhost:4101/api/openapi.json
• Health check: http://localhost:4101/api/health

Route Groups

All routes require authentication via Supabase Auth JWT (passed as Authorization: Bearer <token>) unless noted.

Core Platform

Contacts and conversations are surfaced through the unified inbox and contact-timeline endpoints (see Unified Inbox and Contact Timeline & Notes below) rather than dedicated /api/persons or /api/conversations CRUD routes. Rules are managed via templates plus the rules analytics endpoints.

Note: Contact CRUD (/api/persons), top-level conversation CRUD (/api/conversations), and dedicated rules CRUD (POST/PATCH/DELETE /api/rules) are aspirational and not yet exposed as REST endpoints at this commit. Messaging inbound flows use /api/messaging/conversations and /api/messaging/sms.

Webhooks (no auth required)

Note: An MS Graph change-notification webhook (/webhooks/ms-graph) is aspirational — MS Graph sync currently runs via the connector plugin, not an inbound webhook.

Intentions & Sensors

AI & Agents

Note: /api/workflows, /api/workflows/:id/run, /api/ai/routing-rules, and a dedicated multi-agent /api/agent/orchestrate endpoint are aspirational at this commit.

Federation

Marketplace & Coordination

Governance & Time Bank

Browser Calling

Notifications & Presence

Plugins, Documents & Scheduling

Observability & Streaming

Note: /api/cache/stats, /api/events/store, /api/sse/subscribe, and /api/activity/feed as separate paths are aspirational — use the paths above.

Multi-Tenancy & Developer API

Note: Self-hosted OAuth2 authorization server (/api/oauth/apps, /api/oauth/authorize, /api/oauth/token) and the API key (/api/keys) endpoints are aspirational. The /api/oauth/:providerId/* routes are the OAuth2 client flow for third-party providers.

Search, Export & Preferences

Monitoring, Billing & Security

Note: /api/billing/*, /api/feature-flags, /api/sessions, and /api/analytics REST endpoints are aspirational at this commit. Billing today flows through Stripe directly from the web app.

Data Lineage, Tools, Audio & Devices

Note: /api/lineage/:entityType/:entityId is aspirational — the lineage route file exists but does not yet register HTTP handlers at this commit.

Unified Inbox

All endpoints require auth. Backed by InboxService.

GET /api/inbox query params:

PUT /api/inbox/read / /api/inbox/archive body:

{ "itemIds": ["uuid", "..."] }

PUT /api/inbox/starred body:

{ "itemIds": ["uuid", "..."], "starred": true }

Voice & Phone Lines

All endpoints require auth unless noted. Backed by PhoneLineService, VoicemailService, TranscriptionService.

PUT /api/calling/lines/:id body:

{
  "label": "Office",
  "isDefault": true,
  "settings": {
    "businessHours": { "start": "09:00", "end": "17:00", "timezone": "America/New_York" },
    "voicemailGreetingUrl": "https://...",
    "forwardingNumber": "+1...",
    "recordingEnabled": true,
    "dndSchedule": {
      "enabled": true,
      "days": [6, 7],
      "startTime": "22:00",
      "endTime": "08:00",
      "vipContactIds": []
    }
  }
}

POST /api/calling/transfer body:

{ "callSid": "CA...", "targetNumber": "+1...", "type": "warm|cold", "announceMessage": "..." }

POST /api/calling/park body: { "callSid": "CA...", "slot": 5 } (slot optional, auto-assigned if omitted)

POST /api/calling/ivr-flows body:

{
  "name": "Main Menu",
  "phoneLineId": "uuid",
  "isActive": true,
  "flowDefinition": {
    "entryNodeId": "node-1",
    "nodes": [{ "id": "node-1", "type": "greeting|menu|route_to_number|route_to_voicemail|time_check|play_message", "label": "...", "data": {}, "position": { "x": 0, "y": 0 } }],
    "edges": [{ "id": "edge-1", "source": "node-1", "target": "node-2", "digit": "1" }]
  }
}

Email

All endpoints require auth. Backed by EmailService (MS Graph).

GET /api/email/threads query params: folderId, unread, starred, search, page, limit

POST /api/email/send body:

{
  "to": [{ "name": "...", "email": "..." }],
  "cc": [], "bcc": [],
  "subject": "...",
  "bodyHtml": "<p>...</p>",
  "bodyText": "...",
  "signatureId": "uuid",
  "attachmentIds": []
}

POST /api/email/reply body:

{ "messageId": "uuid", "bodyHtml": "...", "replyAll": false, "cc": [], "bcc": [], "attachmentIds": [] }

POST /api/email/forward body:

{ "messageId": "uuid", "to": [{ "name": "...", "email": "..." }], "bodyHtml": "..." }

PUT /api/email/threads/starred body: { "threadIds": ["uuid"], "starred": true }

POST /api/email/move body: { "messageIds": ["uuid"], "targetFolderId": "uuid" }

POST /api/email/signatures body: { "name": "Work", "bodyHtml": "<p>...</p>", "isDefault": false }

Email AI

All endpoints require auth. Backed by EmailAIService.

Responses:

/summarize → { summary: { keyPoints: string[], actionItems: string[], ... } }

/suggest-replies → { replies: [{ subject: string, bodyHtml: string }, ...] }

/priority → { priority: { score: number, factors: string[] } }

/follow-ups → { followUps: [{ messageId, commitment, dueDate }, ...] }

Video Meetings

All endpoints require auth unless noted. Backed by MeetingService (Twilio Video).

POST /api/video/meetings body:

{
  "title": "Sprint Review",
  "scheduledStart": "2026-04-10T14:00:00Z",
  "scheduledEnd": "2026-04-10T15:00:00Z",
  "calendarEventId": "uuid",
  "settings": { "recording": true, "waitingRoom": false, "maxParticipants": 10, "locked": false }
}

GET /api/video/meetings query params: status (scheduled|active|ended), search, page, limit

POST /api/video/meetings/:id/join body: { "identity": "display-name" } (optional)

POST /api/video/meetings/:id/invite body:

{ "emails": ["alice@example.com"], "phoneNumbers": ["+1..."], "message": "Join us!" }

Contact Timeline & Notes

All endpoints require auth. Backed by ContactTimelineService.

GET /api/contacts/:id/timeline query params: types (comma-separated: call,sms,email,video,voicemail,note), startDate, endDate, limit, offset

POST /api/contacts/:id/notes body: { "body": "Met at conference..." }

PUT /api/contacts/notes/:noteId body: { "body": "Updated text" }

POST /api/contacts/merge body: { "primaryId": "uuid", "mergedId": "uuid" }

PUT /api/contacts/:id/relationship body: { "label": "partner|close_friend|friend|colleague|acquaintance|family|vip|blocked" }

GET /api/dashboard/recent-contacts query: limit (default 5)

Push Notifications

All endpoints require auth. Backed by PushNotificationService (Firebase Cloud Messaging).

POST /api/push/register body:

{
  "deviceId": "device-uuid",
  "fcmToken": "FCM_TOKEN_STRING",
  "platform": "android",
  "deviceName": "Pixel 8"
}

Response 201: full token record.

DELETE /api/push/unregister body: { "deviceId": "device-uuid" } — returns 204.

Projects & Tasks

All endpoints require auth. Backed by ProjectService.

POST /api/projects body:

{
  "title": "Q2 Marketing Campaign",
  "description": "...",
  "status": "active",
  "area": "work",
  "targetDate": "2026-06-30T00:00:00Z",
  "tags": ["marketing"]
}

POST /api/projects/:id/milestones body:

{ "title": "Launch email blast", "dueDate": "2026-05-01T00:00:00Z", "description": "..." }

POST /api/projects/:id/tasks body:

{ "title": "Write copy", "status": "todo", "priority": "high", "dueDate": "2026-04-20T00:00:00Z", "assignedTo": "uuid" }

PUT /api/projects/:id/tasks/:taskId/status body: { "status": "todo|in_progress|done|cancelled" }

POST /api/projects/:id/time-entries body:

{ "taskId": "uuid", "durationMinutes": 90, "notes": "Wrote first draft", "loggedAt": "2026-04-10T14:00:00Z" }

Authentication

All authenticated endpoints expect a Supabase Auth JWT:

curl -H "Authorization: Bearer <supabase-jwt>" \
     http://localhost:4101/api/persons

For the demo user (demo@made-open.dev), obtain a token via:

curl -X POST http://localhost:54321/auth/v1/token?grant_type=password \
  -H "apikey: <supabase-anon-key>" \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@made-open.dev","password":"demopassword"}'