labelbee CLI · REST API

CLI 与 API 文档

用命令行或 HTTP 把数据送进 labelbee、把标注结果取回来。CLI 用你自己的账号在浏览器里登录；CI 和程序用组织级 API Key。两者都只能访问一个组织的数据。快速开始 →

安装

需要 Node.js 20 或更新版本。安装后得到 labelbee 命令。

npm install -g @tinkerlandai/labelbee-cli
labelbee --version

labelbee login 会打开浏览器：登录 labelbee，确认页面上的代码和终端里的一致，选择工作区并授权。通过 SSH 或在没有浏览器的机器上，用任意设备打开终端里给出的链接即可。登录 30 天有效，过期后 CLI 会提示重新登录；凭据只保存在本机（~/.config/labelbee/config.json，仅你可读）。在工作区 → 设备里可以看到并撤销每台设备；labelbee logout 会同时在服务端吊销。

labelbee login
# To sign in, open this page and confirm the code:
#   https://labelbee.ai/device?code=WDJB-MJHT
#   Code: WDJB-MJHT (valid for 10 minutes)
# Signed in as you@company.com to Lumen Studio.

在 CI 中使用

在工作区 → API Key 新建一个 Key，设置环境变量 LABELBEE_API_KEY 即可，不需要 login；连接其他部署时再设置 LABELBEE_URL。也可以用 labelbee login --key <key> 把 Key 保存在本机。

export LABELBEE_API_KEY=lb_…   # no login needed
labelbee whoami

上传数据

把一份 CSV 追加到已有数据源。大文件会自动分批发送；数据源里已有的记录不会重复写入，所以重复上传是安全的。

labelbee sources
labelbee upload <source-id> feedback.csv --text-column text --id-column id

拉取标注结果

每条记录取当前上线版本的标签，没有时取最新的一条。--since 支持时间点或时长（30m、12h、7d），格式支持 jsonl（默认）、json、csv。

labelbee label-sets
labelbee pull <label-set-id> --since 1d --format csv --out labels.csv
labelbee pull <label-set-id> --since 2026-11-05T00:00:00Z   # JSON Lines

REST API

CLI 用的就是这些接口。认证头：Authorization: Bearer <API Key 或 CLI 登录令牌>。错误返回 {"error": "…"}：401 凭据无效（CLI 登录过期时 code 为 token_expired），404 不存在或不属于这个组织。

curl -H "Authorization: Bearer $LABELBEE_API_KEY" \
  "https://labelbee.ai/api/v1/label-sets/<label-set-id>/labels?since=2026-11-05T00:00:00Z"

# → {"labels": [{"record_id": "q_88213", "label_key": "ignored_instruction",
#               "model_version_id": "…",
#               "labeled_at": "2026-11-05 08:12:44.120", "text": "…"}]}

接口
`GET /api/v1/whoami`	凭据所属的组织（CLI 登录时还有登录的人和过期时间）
`GET /api/v1/data-sources`	数据源及记录数
`POST /api/v1/data-sources/{id}/records`	追加一批 CSV（请求体 text/csv，≤ 4.5 MB；参数 text_column、id_column、file_name）
`GET /api/v1/models`	Bee Model 及其版本
`GET /api/v1/label-sets`	标注集
`GET /api/v1/label-sets/{id}/labels`	标注集当前的标签（参数 since）
`POST /api/v1/device/code`	CLI 登录第一步：申请设备码和用户码（RFC 8628，无需认证）
`POST /api/v1/device/token`	CLI 登录第二步：轮询，批准后返回令牌（只返回一次）
`POST /api/v1/device/revoke`	吊销请求所带的 CLI 登录令牌（labelbee logout）

在 Python 里调用

目前没有单独的 Python SDK，直接用 HTTP 即可。

import os, requests

r = requests.get(
    "https://labelbee.ai/api/v1/label-sets/<label-set-id>/labels",
    headers={"Authorization": f"Bearer {os.environ['LABELBEE_API_KEY']}"},
    params={"since": "2026-11-05T00:00:00Z"},
)
r.raise_for_status()
for label in r.json()["labels"]:
    print(label["record_id"], label["label_key"])