labelbee CLI · REST API

CLI and API docs

Send data into labelbee and get labels back, from the command line or over HTTP. The CLI signs in with your own account in the browser; CI and programs use an organization API key. Either one sees a single organization's data. Get started →

Install

Requires Node.js 20 or newer. Installs the labelbee command.

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

Sign in

labelbee login opens your browser: sign in to labelbee, check that the code on the page matches your terminal, pick the workspace and authorize. Over SSH or on a machine without a browser, open the printed link on any device. A sign-in lasts 30 days, after which the CLI asks you to log in again; the credentials stay on your machine (~/.config/labelbee/config.json, readable only by you). Each device is listed under Devices in the workspace, where you can revoke it; labelbee logout revokes it on the server too.

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.

In CI

Create a key in the workspace under API keys and set LABELBEE_API_KEY; no login needed. Set LABELBEE_URL to reach another deployment. labelbee login --key <key> saves a key on your machine instead.

export LABELBEE_API_KEY=lb_…   # no login needed
labelbee whoami

Upload data

Append a CSV to an existing data source. Large files are sent in batches; records already in the source are not added again, so repeating an upload is safe.

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

Pull labels

Each record carries the live version's label, or its newest one. --since takes a time or a duration (30m, 12h, 7d); formats are jsonl (default), json and 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

The endpoints the CLI uses. Header: Authorization: Bearer <API key or CLI sign-in token>. Errors answer {"error": "…"}: 401 for an invalid credential (with code token_expired when a CLI sign-in has expired), 404 for anything missing or outside the organization.

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": "…"}]}

Endpoints
`GET /api/v1/whoami`	The credential's organization (for a CLI sign-in, also its person and expiry)
`GET /api/v1/data-sources`	Data sources with their record counts
`POST /api/v1/data-sources/{id}/records`	Append a CSV batch (body text/csv, ≤ 4.5 MB; query text_column, id_column, file_name)
`GET /api/v1/models`	Bee Models and their versions
`GET /api/v1/label-sets`	Label sets
`GET /api/v1/label-sets/{id}/labels`	A label set's current labels (query since)
`POST /api/v1/device/code`	CLI sign-in, step 1: a device code and a user code (RFC 8628, no credential)
`POST /api/v1/device/token`	CLI sign-in, step 2: poll; returns the token once approved (exactly once)
`POST /api/v1/device/revoke`	Revoke the CLI sign-in the request carries (labelbee logout)

From Python

There is no separate Python SDK yet; plain HTTP works.

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"])