HTTP API reference

This chapter lists every REST route LiteBot serves, grouped by mount point, with the method, path, the access it needs and what it does. Use it to find an endpoint and the permission behind it; the chapters linked from each group explain the request and response bodies. The examples use http://127.0.0.1:3345.

Authentication

Most routes need one of two credentials:

When both are present, the JWT is tried first. An API key acts with the role and tenant it was created with. Repeated bad API keys from one IP lock that IP out for a while.

curl -s -X POST http://127.0.0.1:3345/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<password>"}'

{
  "success": true,
  "data": {
    "user": { "id": "...", "username": "admin", "role": "admin", "tenantId": "default", "permissions": ["bots:read", "..."] },
    "token": "<token>",
    "refreshToken": "<refresh-token>",
    "expiresIn": "24h"
  }
}

expiresIn is JWT_EXPIRES_IN (default 24h). Exchange the refresh token for a new access token with POST /api/auth/refresh and {"refreshToken":"..."}.

Create an API key for a server such as a gateway:

curl -s -X POST http://127.0.0.1:3345/api/auth/api-keys \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{"name":"voice-gateway","role":"user","tenantId":"clinic-group"}'

The response carries data.key (lbk_...) once; only a hash is stored. Optional expiresAt takes a date. tenantId is honoured only for a global admin; everyone else gets keys in their own tenant.

Permissions and tenants

Permissions are <resource>:<action>. Resources: bots, documents, collections, admin, api-keys, roles, conversations, campaigns, users, tools. Actions: create, read, update, delete. In the tables, perm means requirePermission on that resource and action; admin means the admin role; login means any valid credential.

Most routes are tenant-scoped: a user or key sees only its own tenant, and another tenant's bot, conversation or campaign answers 404 as if it did not exist. A global admin sees every tenant, or narrows to one with the header X-Tenant-Id: <tenant>; an invalid value answers 400 Invalid X-Tenant-Id header. See Users, roles and tenants.

Responses and errors

Successful JSON responses have the form {"success": true, "data": ...}. Errors have success: false and an error string; some add message or details.

Errors that reach the global handler hide the message in production ("error":"Something went wrong!"). Errors handled inside a route return the route's own message.

Rate limit

Every /api route except /api/documents/* and /api/collections/* shares one per-IP limit: 100 requests per 15 minutes when NODE_ENV=production, 500 per 5 minutes otherwise. API_RATE_LIMIT sets the count. RateLimit-* response headers show the remaining budget. /health is outside /api and not limited.

Pagination

List routes that page take page (from 1) and limit, and return a pagination object:

{ "pagination": { "page": 1, "limit": 20, "total": 134, "totalPages": 7 } }

All /api responses carry Cache-Control: no-store.

Public routes

These take no credential. Restrict who can reach them at your proxy or firewall (see Security).

Auth, API keys and roles

/api/auth and /api/auth/roles.

Users and tenants

Bots

/api/bots. Every route needs a login; bot routes are tenant-scoped. See Bots and Bot configuration reference.

Tools

/api/tools, login required, tenant-scoped. See Tools.

Knowledge base

/api/documents and /api/collections, login required, tenant-scoped, outside the rate limit. See Knowledge base.

Conversations and analytics

See Conversations and analytics.

Campaigns

/api/campaigns, present only when ENABLE_AUTO_DIALER=true. The full table is in Auto-dialer.

Admin and health

/api/admin needs the admin role on every route.

Voice gateway and visual builder

The visual builder routes exist only when ENABLE_VISUAL_EDITOR=true, and they take no credential. They do not touch saved bots, but block them at your proxy if the dashboard is not public.

Where to go next

• Request and response bodies for chat: Chat API
• Voice WebSocket frames: Voice
• Roles, permissions and tenants: Users, roles and tenants
• What to expose and what to block: Security