Call bots from your code.

1. Go to /account/tokens (signed-in users only).
2. Type a label (e.g. my-claude-config) so you can revoke this specific key later without nuking everything.
3. Click Generate new key. The plaintext appears once — it starts with lhduser_. Copy it now; you won't see it again.

Bots are referenced by their handle — the lowercase string after /bots/ in the URL (e.g. @price-bot → handle is price-bot).

Not sure what to call? Hit GET /api/v1/bots — it returns every bot accessible to your key.

curl -X POST https://www.localhostdevs.com/api/v1/bots/<HANDLE>/dispatch \
  -H "Authorization: Bearer lhduser_XXXXX..." \
  -H "Content-Type: application/json" \
  -d '{"command":"ping","args":{}}'

const res = await fetch(
  `https://www.localhostdevs.com/api/v1/bots/${handle}/dispatch`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LHD_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ command: 'ping', args: {} }),
  },
);
const json = await res.json();
// { ok: true, msgId: '...', command: 'ping', latencyMs: 42, body: { text: 'pong' } }

import os, httpx
r = httpx.post(
    f"https://www.localhostdevs.com/api/v1/bots/{handle}/dispatch",
    headers={"Authorization": f"Bearer {os.environ['LHD_TOKEN']}"},
    json={"command": "ping", "args": {}},
)
print(r.json())

Successful response

{
  "ok": true,
  "msgId": "01J9KQ...",
  "command": "ping",
  "latencyMs": 42,
  "body": {
    "text": "pong"
  }
}

body shape is bot-defined. The standard fields the SDK emits are text, data, and dispatch — but a bot can return anything it wants. latencyMs is the round-trip time the gateway measured (server → bot → server).

Three transports, picked by the consumer:

• Accept: application/json (default) — one final JSON response. Backward compatible with everything written before. Update frames are buffered server-side and never appear.
• Accept: text/event-stream — SSE with event: update | final | error frames. Read via the browser's EventSource (note: POST endpoints need fetch()+reader, not EventSource).
• Accept: application/x-ndjson — one JSON per line with {"kind":"update"|"final"|"error", …}. Easiest from non-browser callers.

curl -X POST https://www.localhostdevs.com/api/v1/bots/<HANDLE>/dispatch \
  -H "Authorization: Bearer lhduser_XXXXX..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/x-ndjson" \
  --no-buffer \
  -d '{"command":"analyze","args":{}}'

curl -X POST https://www.localhostdevs.com/api/v1/bots/<HANDLE>/dispatch \
  -H "Authorization: Bearer lhduser_XXXXX..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  --no-buffer \
  -d '{"command":"analyze","args":{}}'

const res = await fetch(
  `https://www.localhostdevs.com/api/v1/bots/${handle}/dispatch`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LHD_TOKEN}`,
      'Content-Type': 'application/json',
      'Accept': 'application/x-ndjson',
    },
    body: JSON.stringify({ command: 'analyze', args: {} }),
  },
);
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let i;
  while ((i = buf.indexOf('\n')) >= 0) {
    const line = buf.slice(0, i); buf = buf.slice(i + 1);
    if (!line) continue;
    const frame = JSON.parse(line);
    if (frame.kind === 'update') console.log('progress:', frame.progress);
    if (frame.kind === 'final')   console.log('done:', frame.body);
  }
}

import os, json, httpx
with httpx.stream(
    'POST',
    f"https://www.localhostdevs.com/api/v1/bots/{handle}/dispatch",
    headers={
        "Authorization": f"Bearer {os.environ['LHD_TOKEN']}",
        "Accept": "application/x-ndjson",
    },
    json={"command": "analyze", "args": {}},
) as r:
    for line in r.iter_lines():
        if not line: continue
        frame = json.loads(line)
        if frame["kind"] == "update":
            print("progress:", frame.get("progress"))
        elif frame["kind"] == "final":
            print("done:", frame["body"])

Update frame

{
  "kind": "update",
  "progress": 60,
  "body": {
    "text": "Crunching…",
    "mimeType": "text/plain"
  }
}

progress may be a number (percent), an object { current, total }, or { label }. Bots may emit any number of update frames (or none) before the final reply. Inactivity timeout (10s without any frame) fails the dispatch.

Final frame

{
  "kind": "final",
  "ok": true,
  "msgId": "01J...",
  "command": "analyze",
  "latencyMs": 8421,
  "body": {
    "text": "done",
    "mimeType": "image/png",
    "data": "<base64-encoded bytes>"
  }
}

Error frame

{
  "kind": "error",
  "error": {
    "code": "timeout",
    "message": "bot did not respond in time"
  }
}

• Command must match what the bot registered. If you send fooo and the bot's handler is foo, the bot won't reply and you'll get a 504 timeout after 10s. Use GET /api/v1/bots/{handle}/commands to discover what's available.
• args is the keyword-arg object. Whatever shape the bot expects, that's what goes in there. Send {} for commands that take no args.
• Paid bots debit your credit balance. Free bots are free. You'll see 402 insufficient_credits if you're low — top up at /account/billing. Bots you own are always free for you, regardless of their listed price — no self-billing, no top-up needed for dev/test.
• Rate limit: 60 req/min per token. Returns 429 with a Retry-After header on overflow. Higher limits available on request.
• Bots can be offline. A bot only responds if its harness is running on the developer's machine. If it's offline you'll get 503 bot_offline. Check GET /api/v1/bots/{handle} first — the status field tells you.

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "not enough credits to dispatch"
  }
}