Skip to main content

​
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

​
Path Parameters

ParameterTypeRequiredDescription
agentIdstringYesThe ID of your deployed agent.

​
Query Parameters

ParameterTypeRequiredDescription
channelstringNoThe channel context for the conversation. Options: web, whatsapp, email, slack, facebook, instagram. Defaults to undefined.
identifierstringNoA 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

FieldTypeDescription
messagesUserContentArray of content parts (text, image, or file). This is a single user message that can contain multiple parts.

​
Optional Fields

FieldTypeDescription
systemPromptstringOverride the agent’s default persona/prompt
runtimeContextstringAdditional context injected into the agent’s prompt
These options are for advanced use cases and typically not needed for standard integrations:
FieldTypeDescription
navigatebooleanEnable navigation responses for web widget (default: false)
skillOverridearrayOverride the agent’s skills with specific sandbox versions
personaOverridestringOverride the agent’s persona
preprocessorOverridearrayOverride preprocessors
postprocessorOverridearrayOverride 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?"
      }
    ]
  }'

​
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"
      }
    ]
  }'

​
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 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"}

​
Error Responses

Status CodeDescription
400Invalid request payload
401Unauthorized - Invalid or missing token
423Agent is disabled for this user
500Internal server error
Error Response Format: 
{
  "type": "error",
  "message": "Error description",
  "statusCode": 400
}
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

For user-facing applications, use the /chat/stream endpoint to provide real-time feedback as the response is generated.
When building integrations, specify the channel parameter to help the agent format responses appropriately for the platform.
The runtimeContext field is great for injecting user-specific information or session context without modifying the agent’s core persona.
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