REST APIv1

Gateway API

Send messages to your LuluClaw hosted assistant over HTTP from any language or platform. The Gateway API lets you integrate your assistant into your own product with a single endpoint.

Base URL

https://luluclaw.com/api/gateway/chat

Authentication

Pass your API key as a Bearer token in the Authorization header. You can find your key in the Account tab.

Authorization: Bearer YOUR_API_KEY

Request

POST/api/gateway/chat

Send a Content-Type: application/json body with the following fields:

Field	Type	Description
message	string	Required. The user message to send (max 4 000 characters).
session_id	string	Optional. A string (max 128 chars) that identifies the conversation thread. Omit to start a new thread.

Response

A successful request returns 200 OK with the following JSON body:

Field	Type	Description
reply	string	The assistant's response text.
session_id	string	The session ID for this thread. Pass this back in subsequent requests to continue the conversation.
credits_used	number	Credits consumed by this request.
credits_remaining	number \| null	Credits remaining in your balance, or `null` if unavailable.

Rate Limits

Hosted-plan requests are rate-limited per workspace by a rolling one-hour window. When the limit is exceeded the API returns 429. The window resets automatically — no action required.

Plan	Price	Turns / hour	Notes
Starter	$29 / mo	15	Hard cap — 429 returned until the window resets.
Pro	$79 / mo	30	Hard cap — 429 returned until the window resets.
Premium	$129 / mo	60	Hard cap — 429 returned until the window resets.
BYOK	varies	Unlimited	Rate limited by your upstream provider (OpenAI / Anthropic).

A “turn” is one request to POST /api/gateway/chat, regardless of message length or model used. Limits are per workspace, not per API key.

Error Codes

Errors are returned as JSON with an error string at the status code listed below.

Status	Meaning	When it happens
401	Unauthorized	API key is missing, malformed, or invalid.
402	Payment Required	Your credit balance has been exhausted. Top up or upgrade your plan.
429	Too Many Requests	Hourly or per-key rate limit reached. Retry after the window resets.
503	Service Unavailable	The assistant service is temporarily unavailable. Retry after a short delay.

cURL Example

bash

curl -X POST https://luluclaw.com/api/gateway/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello! What can you help me with?",
    "session_id": "user-abc-session-1"
  }'

JavaScript Example

javascript

const response = await fetch("https://luluclaw.com/api/gateway/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Hello! What can you help me with?",
    session_id: "user-abc-session-1", // optional — omit to start a new thread
  }),
});

const data = await response.json();
// {
//   reply: "Hi there! I can help you with ...",
//   session_id: "user-abc-session-1",
//   credits_used: 1,
//   credits_remaining: 249
// }
console.log(data.reply);

Python Example

python

import requests

response = requests.post(
    "https://luluclaw.com/api/gateway/chat",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "message": "Hello! What can you help me with?",
        "session_id": "user-abc-session-1",  # optional
    },
)

data = response.json()
# {
#   "reply": "Hi there! I can help you with ...",
#   "session_id": "user-abc-session-1",
#   "credits_used": 1,
#   "credits_remaining": 249
# }
print(data["reply"])

Need an API key? Sign in to your LuluClaw account and open the Account tab to generate one. Credits are consumed per request and can be topped up from the Billing tab.