API Overview

The Ilana runtime exposes a REST API for sending chat messages and fetching widget configuration. This is the same API used by the SDK and embed widget under the hood.

Base URL

https://api.getilana.ai

For local development:

http://localhost:3001

Authentication

Authenticated endpoints require an embed token in the Authorization header:

Authorization: Bearer <embed-token>

Embed tokens are JWTs generated when you add a partner domain in the admin portal. Each token is scoped to a specific (botId, domain) pair.

Endpoints

Method	Path	Auth	Description
`POST`	`/chat`	Required	Send a message and get a governed response
`GET`	`/embed-config`	None	Fetch widget display configuration
`GET`	`/health`	None	Health check

Request Format

All POST endpoints accept JSON request bodies:

Content-Type: application/json

Response Format

All responses are JSON. Successful responses return the data directly. Error responses follow a standard shape — see Error Handling.

Rate Limiting

Requests are rate-limited per (botId, domain) pair. When rate limited, the API returns a 429 status with the RATE_LIMITED error code.

Monthly message caps apply based on the organization's plan. When exceeded, the API returns MESSAGE_CAP_EXCEEDED with plan details.