Public API

CraftBot exposes a REST API at https://api.<your-domain>/api/v1. All write endpoints require authentication; read endpoints obey the calling role’s permissions.

Authentication

CraftBot issues short-lived JWT access tokens via POST /api/v1/auth/login (15-minute lifetime) and pairs them with an opaque refresh token stored in Redis (7-day lifetime). Refresh via POST /api/v1/auth/refresh.

Send the access token on every request:


Authorization: Bearer <access-token>

There is no long-lived API-token surface today. Programmatic clients should log in via the standard /auth/login endpoint and rotate their refresh token before it expires.

Response envelope

Every response (success or error) is wrapped in a consistent envelope by the global response interceptor + exception filter.

Success — non-paginated:


{
  "success": true,
  "data": { ... }
}

Success — paginated (controllers that return { items, total, page, limit } are auto-unwrapped):


{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 150, "page": 1, "limit": 20 }
}

Error — see Error catalog for the full envelope and the codes the platform emits.

Rate limits

The default global throttler allows 100 requests per minute per client (60-second window). Webhook receivers and other tenant-scoped routes may apply their own per-tenant throttle on top of the global one.

A request that exceeds the budget receives HTTP 429 Too Many Requests with code: "THROTTLER_LIMIT_EXCEEDED".

Endpoint surfaces

All routes live under the /api/v1 prefix. The full list — with request and response shapes — is in Swagger; the table below names the high-traffic surfaces only.

Surface	Notes
`/api/v1/auth/*`	Login, refresh, logout, password reset.
`/api/v1/conversations/*`	List, fetch, send message, whisper, assign, close.
`/api/v1/contacts/*`	Search, fetch, update attributes.
`/api/v1/recipes/*`	List, draft load / save (ETag-guarded), publish, versions.
`/api/v1/channels/*`	Configure WhatsApp numbers and email servers.
`/api/v1/analytics/*`	KPI snapshots, time-series, agent performance.
`/api/v1/users/`, `/api/v1/teams/`, `/api/v1/roles/*`	Identity admin.

Webhooks (inbound)

CraftBot exposes webhook receivers per channel:


POST /api/v1/webhooks/whatsapp/:channelId

This is the URL you configure in Meta Business Manager. See Channels → Webhook setup.

OpenAPI / Swagger

In non-production environments the API serves a Swagger UI at /api/docs and the raw OpenAPI JSON at /api/docs-json. Both are disabled when NODE_ENV=production.

Versioning

The current version is v1. Breaking changes will introduce v2 alongside (no in-place breaking changes). Deprecated v1 endpoints carry a Deprecation header for at least 6 months before removal.