API Integration
This guide explains the integration surface currently exposed by the Irmaya codebase. It is intended for technical implementers who need to connect internal systems, automate workspace workflows, or operate the dashboard against the backend API.
Overview
Irmaya does not currently present a single public v1 API product in this repository. Instead, the codebase exposes a set of authenticated application routes used by the dashboard and operational workflows.
The most important pattern is:
- authenticated routes under
/api/... - tenant-scoped access for workspace data
- specialized endpoints for conversations, contacts, broadcasts, knowledge base, team management, settings, and setup
Authentication and Access Model
Most application routes in this repo are protected by Clerk authentication plus tenant checks.
In practice, this means integrations should assume:
- the caller must be authenticated
- the request is evaluated in a tenant or workspace context
- some routes require admin or elevated access
- dashboard-facing APIs are not the same thing as a public third-party developer platform
Main API Areas in the Repo
These route families are present in the current codebase and are better references than invented /api/v1/... examples:
Conversations and Messages
/api/chats/api/chats/:chatId/api/chats/:chatId/notes/api/chats/:chatId/reply/api/messages
These support conversation listing, updates, notes, replies, and message retrieval.
Contacts
/api/contacts/api/contacts/:wa_id/api/contacts/:wa_id/activities/api/contacts/import
These support contact management and import workflows.
Broadcasts
/api/broadcasts/api/broadcasts/:id/api/broadcasts/:id/send/api/broadcasts/:id/cancel/api/broadcasts/:id/stats/api/broadcasts/groups/api/broadcasts/templates
These support operational broadcast creation, sending, recipient grouping, and analytics.
Knowledge Base
/api/knowledge-base/api/knowledge-base/text/api/knowledge-base/url/api/knowledge-base/:id
These support the dashboard knowledge base workflows.
Team and Workspace
/api/team/api/team/invite/api/workspace/context/api/workspace/context/switch/api/settings/api/tenant/config
These support workspace context, tenant configuration, and team operations.
Setup and Channel Operations
/api/setup/status/api/setup/connection/api/setup/connection/confirm/api/setup/go-live/api/session/health/api/session/connect/api/session/disconnect/api/tenant/waha-session/api/tenant/waha-status
These support onboarding, connection checks, and WhatsApp session management.
How to Approach Integrations
1. Start from the Actual Workflow
Before integrating, decide which product area you are extending:
- workspace setup
- conversation operations
- contact sync
- broadcasts
- knowledge base ingestion
- tenant configuration
2. Confirm the Route Family
Use the existing backend routes and dashboard behavior as the main references for the request and response shape. The goal is to match the application behavior that already exists rather than designing against an assumed public API contract.
3. Expect Tenant Context
Most useful data routes depend on tenant-aware middleware. Integrations should be designed with workspace isolation in mind rather than assuming globally shared data.
4. Separate Internal and External Surfaces
Some routes are intended for dashboard use, setup flows, or operational tooling. Treat them as application APIs, not automatically as stable public developer contracts.