HTTP API - Lua CLI

Overview

The HTTP API allows you to communicate with your deployed Lua AI agents directly via HTTP requests. This is useful for building custom integrations, mobile apps, backend services, or any application that needs to interact with your agent programmatically.

Stream Endpoint

Real-time streaming responses via SSE

Generate Endpoint

Single response generation

Base URL

https://api.heylua.ai

Authentication

All requests require authentication via Bearer token in the Authorization header. You can use your API key as the token:

Authorization: Bearer YOUR_API_KEY

You can find your API key in the Admin Dashboard under the API Keys section.

Endpoints

Stream Chat Response

Stream a chat response using Server-Sent Events (SSE).

POST /chat/stream/:agentId

Generate Chat Response

Generate a complete chat response (non-streaming).

POST /chat/generate/:agentId

PostProcessors: Only the /generate endpoint supports PostProcessors. Streaming responses (/stream) bypass post-processing because text is sent incrementally before the full response is available.

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	The ID of your deployed agent.

Query Parameters

Parameter	Type	Required	Description
`channel`	string	No	The channel context for the conversation. Options: `web`, `whatsapp`, `email`, `slack`, `facebook`, `instagram`. Defaults to `undefined`.
`identifier`	string	No	A unique identifier for the message. Can be used for tracking purposes.

Request Body

The request body follows the AI SDK 5 UserContent format for messages.

Required Fields

Field	Type	Description
`messages`	`UserContent`	Array of content parts (text, image, or file). This is a single user message that can contain multiple parts.

Optional Fields

Field	Type	Description
`systemPrompt`	string	Override the agent’s default persona/prompt
`runtimeContext`	string	Additional context injected into the agent’s prompt
`clientContext`	object	Client-side context for the request. Currently supports `timezone` — an IANA timezone string (e.g. `"Africa/Nairobi"`) used as the user’s local timezone for date/time-aware responses. When omitted, the agent falls back to the user’s stored profile, country, or UTC.
`options`	object	Normalized per-request model options. `options.reasoning` — `{ effort?, show? }` — overrides the agent’s `modelSettings.reasoning` for this request (the request always wins, field by field). `options.verbosity` — `'low' \| 'medium' \| 'high'` — requests output verbosity (provider support varies). See With Reasoning Options.

Advanced Options (rarely needed)

These options are for advanced use cases and typically not needed for standard integrations:

Field	Type	Description
`navigate`	boolean	Enable navigation responses for web widget (default: `false`)
`skillOverride`	array	Override the agent’s skills with specific sandbox versions
`personaOverride`	string	Override the agent’s persona
`preprocessorOverride`	array	Override preprocessors
`postprocessorOverride`	array	Override postprocessors

Message Content Types

Messages follow the AI SDK 5 UserContent format:

Text Message

{
  "type": "text",
  "text": "Hello, how can you help me today?"
}

Image Message

{
  "type": "image",
  "image": "https://example.com/image.jpg",
  "mediaType": "image/jpeg"
}

File Message

{
  "type": "file",
  "data": "https://example.com/document.pdf",
  "mediaType": "application/pdf"
}

Examples

Basic Text Request

curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What products do you have available?"
      }
    ]
  }'

const response = await fetch('https://api.heylua.ai/chat/generate/my-agent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        type: 'text',
        text: 'What products do you have available?'
      }
    ]
  })
});

const result = await response.json();
console.log(result);

import requests

response = requests.post(
    'https://api.heylua.ai/chat/generate/my-agent',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [
            {
                'type': 'text',
                'text': 'What products do you have available?'
            }
        ]
    }
)

print(response.json())

Streaming Request

curl -X POST "https://api.heylua.ai/chat/stream/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Tell me about your services"
      }
    ]
  }'

const response = await fetch('https://api.heylua.ai/chat/stream/my-agent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        type: 'text',
        text: 'Tell me about your services'
      }
    ]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n\n').filter(line => line.trim());
  
  for (const line of lines) {
    const data = JSON.parse(line);
    console.log(data);
  }
}

import requests

response = requests.post(
    'https://api.heylua.ai/chat/stream/my-agent',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [
            {
                'type': 'text',
                'text': 'Tell me about your services'
            }
        ]
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))

With Image Attachment

curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What can you tell me about this product?"
      },
      {
        "type": "image",
        "image": "https://example.com/product-photo.jpg",
        "mediaType": "image/jpeg"
      }
    ]
  }'

With System Prompt Override

Use systemPrompt to temporarily override the agent’s persona for a specific request:

curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Help me with my order"
      }
    ],
    "systemPrompt": "You are a friendly customer support agent. Be concise and helpful."
  }'

With Runtime Context

Use runtimeContext to inject additional context into the agent’s prompt:

curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What are my recent orders?"
      }
    ],
    "runtimeContext": "Current user: John Doe (ID: 12345). VIP customer since 2020."
  }'

With Timezone

Use clientContext.timezone to tell the agent the user’s local IANA timezone for date/time-aware responses. When omitted, the agent falls back to the user’s stored profile, country, or UTC:

curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "What time should I schedule my call for tomorrow morning?"
      }
    ],
    "clientContext": {
      "timezone": "Africa/Nairobi"
    }
  }'

With Reasoning Options

Use options.reasoning to control how much the model reasons for this specific request. It works on both /chat/generate and /chat/stream, and overrides the agent’s modelSettings.reasoning default — the request always wins, field by field (setting only effort doesn’t clear an agent-level show: false):

curl -X POST "https://api.heylua.ai/chat/generate/my-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Walk me through the tradeoffs of these two contract options."
      }
    ],
    "options": {
      "reasoning": { "effort": "high", "show": false }
    }
  }'

Field	Type	Description
`reasoning.effort`	`'off' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'max'`	How much the model reasons before responding. Any value is safe to send for any model — Lua clamps it to the nearest behavior the resolved model supports, never erroring. Unrecognized values are ignored and defaults apply.
`reasoning.show`	boolean	Whether the reasoning trace is surfaced in the response. Default `true`. `false` suppresses reasoning from both the stream and the generate response.
`verbosity`	`'low' \| 'medium' \| 'high'`	Requested output verbosity (provider support varies).

Leaving options.reasoning unset falls back to the agent’s modelSettings.reasoning, then to the platform default — adaptive reasoning where the model supports it, low effort otherwise. See Model Selection → Reasoning Effort.

With Channel Context

Specify the channel for channel-specific behavior:

curl -X POST "https://api.heylua.ai/chat/generate/my-agent?channel=whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "text",
        "text": "Send me the order confirmation"
      }
    ]
  }'

Response Format

Generate Response

The generate endpoint returns a complete response object:

{
  "text": "Here are the products we have available...",
  "toolCalls": [],
  "usage": {
    "promptTokens": 150,
    "completionTokens": 200,
    "totalTokens": 350
  }
}

Stream Response

The stream endpoint returns Server-Sent Events (SSE) with JSON chunks:

{"type":"text-delta","textDelta":"Here "}

{"type":"text-delta","textDelta":"are "}

{"type":"text-delta","textDelta":"the products..."}

{"type":"finish","finishReason":"stop"}

Reasoning visibility. The default stream format above never carries the model’s reasoning trace. Reasoning is only streamed on the AI SDK UI message stream — opt in with ?protocol=ui on /chat/stream, where it arrives as reasoning parts. Setting reasoning.show: false (per request via options.reasoning, or per agent via modelSettings.reasoning) suppresses reasoning everywhere: from the UI message stream and from the generate response.

Error Responses

Status Code	Description
`400`	Invalid request payload
`401`	Unauthorized - Invalid or missing token
`423`	Agent is disabled for this user
`500`	Internal server error

Error Response Format:

{
  "type": "error",
  "message": "Error description",
  "statusCode": 400
}

Navigate Option

The navigate option is specifically for web widget integrations. When enabled, it allows the agent to send navigation commands that direct users to specific pages on your website.

{
  "messages": [{ "type": "text", "text": "Show me pricing" }],
  "navigate": true
}

When navigate is true, the agent can include navigation components in its response that trigger the onNavigate callback in the LuaPop widget.

Learn More About Navigation

See the Navigate Component documentation for details on how navigation works with the web widget.

Best Practices

Use Streaming for Better UX

For user-facing applications, use the /chat/stream endpoint to provide real-time feedback as the response is generated.

Include Channel Context

When building integrations, specify the channel parameter to help the agent format responses appropriately for the platform.

Use Runtime Context Wisely

The runtimeContext field is great for injecting user-specific information or session context without modifying the agent’s core persona.

Handle Streaming Properly

When using the stream endpoint, ensure you properly handle the SSE format and parse each JSON chunk separately.

Use Cases

Mobile Apps

Build native mobile experiences with your Lua agent

Custom Integrations

Integrate with internal tools and systems

Voice Assistants

Power voice interfaces with AI responses

Automation

Trigger agent responses from workflows

Channels

Pre-built channel integrations

Chat Widget

Embeddable web widget

Navigate Component

Web navigation feature

LuaAgent

Agent configuration

​Overview

Stream Endpoint

Generate Endpoint

​Base URL

​Authentication

​Endpoints

​Stream Chat Response

​Generate Chat Response

​Path Parameters

​Query Parameters

​Request Body

​Required Fields

​Optional Fields

​Message Content Types

​Text Message

​Image Message

​File Message

​Examples

​Basic Text Request

​Streaming Request

​With Image Attachment

​With System Prompt Override

​With Runtime Context

​With Timezone

​With Reasoning Options

​With Channel Context

​Response Format

​Generate Response

​Stream Response

​Error Responses

​Navigate Option

Learn More About Navigation

​Best Practices

​Use Cases

Mobile Apps

Custom Integrations

Voice Assistants

Automation

​Related

Channels

Chat Widget

Navigate Component

LuaAgent

Overview

Base URL

Authentication

Endpoints

Stream Chat Response

Generate Chat Response

Path Parameters

Query Parameters

Request Body

Required Fields

Optional Fields

Message Content Types

Text Message

Image Message

File Message

Examples

Basic Text Request

Streaming Request

With Image Attachment

With System Prompt Override

With Runtime Context

With Timezone

With Reasoning Options

With Channel Context

Response Format

Generate Response

Stream Response

Error Responses

Navigate Option

Best Practices

Use Cases

Related