API
POST /chat
Endpoint
POST /chatAuthentication: Required — Authorization: Bearer <embed-token>
Request Body
{
"botId": string, // Required — agent ID
"input": string, // Required — user message
"conversationId"?: string // Optional — for multi-turn conversations
}| Field | Type | Required | Description |
|---|---|---|---|
botId | string | Yes | The agent ID |
input | string | Yes | The user's message text |
conversationId | string | No | Pass the ID from a previous response to continue the conversation |
Response (200 OK)
{
"conversationId": "conv-abc-123",
"response": "We offer three plans: Free, Starter, and Growth...",
"intentDetected": "pricing_inquiry",
"metadata": {
"capabilityAllowed": true,
"schemaEnforced": false,
"schemaFallbackUsed": false
}
}| Field | Type | Description |
|---|---|---|
conversationId | string | Conversation ID for follow-up messages |
response | string | The AI-generated response |
intentDetected | string | undefined | Classified intent name |
metadata | object | Governance enforcement metadata |
metadata
| Field | Type | Description |
|---|---|---|
capabilityAllowed | boolean | Whether the intent was allowed by the Capability Profile |
enforcementReason | string | undefined | Why the request was restricted (see below) |
schemaEnforced | boolean | Whether output schema enforcement was applied |
schemaFallbackUsed | boolean | Whether a fallback response replaced the original |
schemaValidationError | string | undefined | Schema validation error details |
enforcementReason Values
| Value | Meaning |
|---|---|
DENY_LIST | Intent is on the Capability Profile deny list |
NOT_IN_ALLOW_LIST | Intent is not in the allow list |
no_intent_match | Could not classify any intent from the input |
schema_fallback | Response failed schema validation; fallback used |
Example
curl -X POST https://api.getilana.ai/chat \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"botId": "bot-abc-123",
"input": "What pricing plans do you offer?"
}'Error Responses
See Error Handling for the full error response format and codes.
Common errors for this endpoint:
| Status | Code | Cause |
|---|---|---|
| 400 | INVALID_REQUEST | Missing or malformed request body |
| 401 | UNAUTHORIZED | Missing or invalid token |
| 403 | FORBIDDEN | Domain not allowed for this bot |
| 404 | NOT_FOUND | Bot not found |
| 429 | RATE_LIMITED | Too many requests |
| 429 | MESSAGE_CAP_EXCEEDED | Monthly message cap reached |