API reference · Bots

Create a report token

POST/v1/bot-tokens

A report-only token (`lbr_…`) for your bot's process: it can send that bot's events and nothing else. Shown once.

On this page

Auth. An account token (Authorization: Bearer lb_…) or a signed-in web session. A report-only token (lbr_…) is refused here with 403 scope_denied.

Limits. Counts against your plan's API requests (60, 600 or 3,000 a minute on Free, Builder and Standard). At most 100 live report tokens per account.

Parameters

Body

Name	Type	Required	Description
`name`	string	yes	A name you will recognise, for example the machine the bot runs on.
`bot_id`	string	no	Bind the token to one bot (recommended). Without it, the token reports for every bot on your account.

Request

Terminal

curl -X POST "https://api.langbot.ai/v1/bot-tokens" \
  -H "Authorization: Bearer $LANGBOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "bot_id": "bot_01M6G72RFQRQ8JGNG8T1447GGP"}'

Python

from langbot import LangbotClient

async with LangbotClient() as lb:  # reads LANGBOT_API_TOKEN
    tok = await lb.bots.create_token("laptop", bot_id="bot_01M6G72RFQRQ8JGNG8T1447GGP")
    print(tok["token"])  # shown once

TypeScript

import { LangbotClient } from "@langbotai/sdk";

const lb = new LangbotClient(); // reads LANGBOT_API_TOKEN
const tok = await lb.bots.createToken({ name: "laptop", botId: "bot_01M6G72RFQRQ8JGNG8T1447GGP" });

Response

201 Created

JSON

{
  "id": "btk_01M6G72RG0GPK193NWY0YFFVEZ",
  "name": "laptop",
  "bot_id": "bot_01M6G72RFQRQ8JGNG8T1447GGP",
  "scope": "bot:report",
  "prefix": "lbr_sfdD",
  "created_at": 1793693147648,
  "last_used_at": null,
  "token": "lbr_…"
}

Only a hash of the token is stored. A report token on any other endpoint is refused with 403 scope_denied: it cannot read your account, your bots or anything else.

Errors

Status	`code`	When
402	`quota_exceeded`	100 report tokens are live on your account; revoke one.
404	`not_found`	No bot with that id on your account (or it was deleted).
401	`auth_required`	No token was sent.
401	`token_invalid`	The token was not recognised (mistyped, revoked or expired).
422	`validation_error`	A parameter failed validation; `detail[].loc` names it.
429	`rate_limited`	Over your request budget; wait `Retry-After` seconds.

Every error body is {"detail": …, "code": "…"}; branch on code. All codes: Errors.