Skip to main content
Developer API

Build with LuluClaw

Integrate AI assistants into your product with a simple REST API. Send chat messages, manage bots programmatically, or embed a ready-made widget in any website.

Authentication

All API requests require a bearer token. Generate your API key from the Account settings in your dashboard. Keys are prefixed with lulu_sk_ and scoped to your workspace.

Include your key in the Authorization header of every request:

http
Authorization: Bearer lulu_sk_your_key_here
Keep your keys safe. Never expose API keys in client-side code or public repositories. Use environment variables or a server-side proxy.

Bot Chat API

Send messages to your hosted assistant and receive responses. Conversations are tracked by session ID, allowing multi-turn threads.

Send a message

POST/api/v1/chat

Request body

FieldTypeDescription
message*stringThe user message to send (max 4,000 characters).
session_idstringConversation thread identifier (max 128 chars). Omit to start a new thread.
bot_idstringTarget a specific bot. Defaults to your workspace's primary bot.

Response

200 OK
{
  "reply": "Our return policy allows returns within 30 days...",
  "session_id": "user-abc-session-1",
  "credits_used": 1,
  "credits_remaining": 249
}
FieldTypeDescription
replystringThe assistant's response text.
session_idstringThread ID to pass in subsequent requests.
credits_usednumberCredits consumed by this request.
credits_remainingnumber | nullRemaining credit balance, or null if unavailable.

Examples

cURL
curl -X POST https://luluclaw.com/api/v1/chat \
  -H "Authorization: Bearer lulu_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is our return policy?",
    "session_id": "user-abc-session-1"
  }'
javascript
const res = await fetch("https://luluclaw.com/api/v1/chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer lulu_sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "What is our return policy?",
    session_id: "user-abc-session-1",
  }),
});

const data = await res.json();
console.log(data.reply);
python
import requests

resp = requests.post(
    "https://luluclaw.com/api/v1/chat",
    headers={"Authorization": "Bearer lulu_sk_..."},
    json={
        "message": "What is our return policy?",
        "session_id": "user-abc-session-1",
    },
)

data = resp.json()
print(data["reply"])

Bot Management API

Create, configure, and manage your bots programmatically. All management endpoints require the same bearer token authentication.

Create a bot

POST/api/v1/bots
FieldTypeDescription
name*stringDisplay name for the bot.
system_prompt*stringThe system prompt that defines the bot's behavior.
modelstringLLM model identifier. Defaults to "gpt-4o-mini".
channelsstring[]Array of channel types: "telegram", "discord", "slack".
cURL
curl -X POST https://luluclaw.com/api/v1/bots \
  -H "Authorization: Bearer lulu_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "system_prompt": "You are a helpful support agent.",
    "model": "gpt-4o-mini",
    "channels": ["telegram"]
  }'

List bots

GET/api/v1/bots

Returns an array of all bots in your workspace with their current status, configuration, and channel connections.

cURL
curl https://luluclaw.com/api/v1/bots \
  -H "Authorization: Bearer lulu_sk_..."

Update a bot

PATCH/api/v1/bots/:bot_id

Update any bot configuration field. Only include the fields you want to change. The bot will reload automatically.

Restart a bot

POST/api/v1/bots/:bot_id/restart

Force-restart a bot process. Useful after configuration changes or if the bot becomes unresponsive.

cURL
curl -X POST https://luluclaw.com/api/v1/bots/:bot_id/restart \
  -H "Authorization: Bearer lulu_sk_..."

Delete a bot

DELETE/api/v1/bots/:bot_id

Permanently delete a bot and disconnect all its channels. This action cannot be undone.

Embeddable Widget

Add an AI chat widget to any website with a single script tag. The widget connects to your LuluClaw bot and handles the conversation UI automatically.

Quick start

Paste this snippet before the closing </body> tag. Replace the data-bot-id with your bot ID from the dashboard.

html
<script
  src="https://cdn.luluclaw.com/widget/v1.js"
  data-bot-id="bot_abc123"
  data-theme="light"
  data-position="bottom-right"
  async
></script>

Configuration options

FieldTypeDescription
data-bot-id*stringYour bot's unique identifier.
data-theme"light" | "dark"Widget color scheme. Defaults to "light". Set to "auto" to follow the user's OS preference.
data-positionstring"bottom-right" (default) or "bottom-left".
data-greetingstringInitial message shown when the widget opens.

Advanced: JavaScript API

For more control, configure the widget via a global object before loading the script:

html
<script>
  window.LuluClawWidget = {
    botId: "bot_abc123",
    theme: "light",
    position: "bottom-right",
    greeting: "Hi! How can I help you today?",
    primaryColor: "#F2729B",
    onReady: function () {
      console.log("Widget loaded");
    },
  };
</script>
<script src="https://cdn.luluclaw.com/widget/v1.js" async></script>

Rate Limits

Rate limits are applied per API key and vary by plan. When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header.

PlanRequests / minRequests / hourRequests / day
BYOK$15/mo1015200
Standard$39/mo3030600
Priority$149/mo60602,000

Need higher limits? Contact us at hello@luluclaw.com for custom enterprise plans.

OpenAPI Spec

A machine-readable OpenAPI 3.1 specification is available for code generation and tooling integration.

{ }

OpenAPI 3.1 Specification

Download the spec to generate client libraries in any language, or import it into Postman, Insomnia, or any OpenAPI-compatible tool.

Coming soon

Ready to start building?

Create your account and generate an API key in under a minute.

Get your API key