API Reference

What this API reference covers

This is a practical route map for the current project, not a generated OpenAPI spec. The goal is to show how the OrcaPulse backend is organized today so teams can quickly understand where major capabilities live.

The current server already exposes a broad API surface for lead operations, workflows, assistants, calls, messaging, integrations, webhooks, OAuth, and realtime behavior.

Server shape and route groups

The backend mounts route groups under `/api/...` from the main Express server. This includes core product resources like workflows, leads, assistants, calls, templates, and credits, plus specialized route groups for CRM OAuth, webhooks, social media, WhatsApp, inbound telephony, and OpenAI realtime handling.

The health and root endpoints also expose a lightweight server-level overview when public API info is enabled.

• Core route roots: `/api/workflows`, `/api/leads`, `/api/assistants`, `/api/calls`, `/api/integrations`, `/api/credits`, `/api/sms-templates`, and `/api/email-templates` are all live route groups.
• Operational route roots: `/api/webhook-integration`, `/api/webhooks`, `/api/openai-realtime`, `/api/social-media`, `/api/whatsapp`, and `/api/crm` support system orchestration around the main product.
• Support route roots: `/api/auth`, `/api/support`, `/api/contact`, `/api/dashboard`, `/api/admin`, and `/api/logs` cover user, support, and admin flows.

Auth and access patterns

Most product APIs are protected. Resource-heavy route groups like integrations, workflows, leads, assistants, and many admin or support paths use authentication middleware before handlers run.

Public reachability is mainly reserved for callback and webhook style routes that must be hit by outside systems, such as contact form submission, inbound webhook endpoints, OAuth callbacks, and certain telephony or payment webhook surfaces.

• Protected examples: integrations, workflows, leads, assistants, admin, support, SMTP config, and most CRM actions.
• Public examples: `/api/contact`, receive webhook URLs, OAuth callback routes, payment webhooks, and inbound call or messaging webhook routes.
• Special middleware cases: the credits webhook uses raw-body middleware before JSON parsing because signature validation depends on the original payload.

Core product APIs

The core product API surface is centered around workflows, leads, assistants, calls, templates, and integrations. These are the main resources OrcaPulse uses to run lead operations day to day.

For example, workflows support create, read, update, delete, status changes, test runs, and assistant assignment. Leads support manual creation, uploads, recall management, execution control, duplicate stats, and lead lookup. Integrations support provider discovery, connection management, CRM sync actions, and phone or voice resource lookup.

• Workflow APIs: `/api/workflows` includes CRUD, status updates, test execution, and assistant linkage endpoints.
• Lead APIs: `/api/leads` includes manual upload, bulk operations, recall management, duplicate stats, execution stop or resume, and lookup endpoints.
• Integration APIs: `/api/integrations` includes provider listing, connection management, CRM lead fetch, CRM lead sync, and CRM field lookup.
• Assistant and call APIs: `/api/assistants`, `/api/assistant-test`, and `/api/calls` cover assistant setup, test sessions, call history, retry flows, and transcript access.

Integration and channel APIs

OrcaPulse also exposes dedicated route groups for channels and provider integrations. This includes CRM OAuth endpoints, WhatsApp account and template management, social-media OAuth and conversation handling, SMTP configuration, email provider wiring, inbound number management, and related platform-specific operations.

These route groups are what connect the product’s workflow layer to actual external systems.

• CRM OAuth APIs: `/api/crm` includes provider auth flows, callbacks, disconnect, lead fetch, and field introspection routes.
• Social and messaging APIs: `/api/social-media` and `/api/whatsapp` handle auth, webhooks, integrations, messages, conversations, and channel-specific setup.
• Provider config APIs: `/api/smtp`, `/api/email-provider`, and `/api/phone-numbers` manage outbound communication infrastructure.

Public webhook and contact edges

Several externally reachable routes are designed as ingestion edges into the system. The most visible examples are the public contact form endpoint, receive webhook URLs for universal lead capture, credits webhooks, call-status webhooks, and social or WhatsApp webhook handlers.

These routes are important because they are how outside systems and public site visitors enter the OrcaPulse backend without already being authenticated app users.

• Contact edge: `/api/contact` accepts website form submissions.
• Webhook edge: `/api/webhook-integration/receive/:token` accepts public external payloads for lead creation.
• Provider webhook edge: `/api/webhooks`, `/api/calls/webhook`, `/api/whatsapp/webhook`, and social-media webhook routes handle provider callbacks and events.

Realtime and call surface

The backend is not only a REST API. It also exposes a realtime and telephony-oriented surface through OpenAI realtime routes, media-stream WebSocket handling, assistant-test WebSocket sessions, inbound call routes, call-status webhooks, recording callbacks, and transcript retrieval paths.

This matters because OrcaPulse’s API surface includes both traditional CRUD resources and event-driven runtime communication layers.

• OpenAI realtime routes: `/api/openai-realtime` includes incoming-call and callback handlers plus telemetry access.
• WebSocket endpoints: the server registers websocket paths for media streams and assistant test sessions.
• Call data routes: `/api/calls` exposes call history, retry, transcript, recording, and lead-specific call lookup.

Next steps

After API Reference, the next useful docs page is usually Automation Connectors, because it explains how these APIs and integrations come together as operational building blocks.