API reference
The raw /api/cli/* endpoints — method, path, auth, body, response, and cost — for calling BizOS directly.
Every BizOS CLI command maps to a
/api/cli/*endpoint. All routes are key-authenticated withAuthorization: Bearer bzk_live_…unless marked (cookie). Each route resolves the org from the key, is rate-limited per key, and can never bypass billing. This page mirrors the API contract.
Base URL & auth
Base URL: https://app.bizos.lol (override via BIZOS_API_URL / --api-url)
Auth: Authorization: Bearer bzk_live_…Example raw call:
curl -s https://app.bizos.lol/api/cli/whoami \
-H "Authorization: Bearer $BIZOS_API_KEY"Routes marked (cookie) use a logged-in browser session instead of a key — they are used by the dashboard, not the CLI.
Auth & keys
| Method | Path | Auth | Body | Response | Cost |
|---|---|---|---|---|---|
| GET | /api/cli/whoami | key | — | { org: { id, name }, plan, credits } | free |
| POST | /api/cli/keys | cookie | { name } | { key, secret } (secret shown once) | free |
| GET | /api/cli/keys | cookie | — | { keys: [{ id, name, prefix, last_used_at, ... }] } | free |
| DELETE | /api/cli/keys/:id | cookie | — | { ok } | free |
Tasks
| Method | Path | Body | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/tasks | — | { items, usedToday, limit, remaining } | free |
| POST | /api/cli/tasks | { text } | { task } | free |
| POST | /api/cli/tasks/:id/run | — | { ok, status, runId } / 402 | ⚠️ 1 credit |
POST /api/cli/tasks/:id/run mirrors the web route: it reserves a credit (reserveCredit(orgId, "task")), runs, and refunds on failure.
Documents
| Method | Path | Body / Query | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/documents | ?folder_id= ?all=1 | { items } | free |
| GET | /api/cli/documents/:id | — | { item } | free |
| POST | /api/cli/documents | { title, kind?, content_md?, summary?, folder_id? } | { item } | free |
Leads / prospects
| Method | Path | Response | Cost |
|---|---|---|---|
| GET | /api/cli/leads | { connected, prospects: [{ id, name, email, phone, createdTime, campaign }] } | free |
Creatives
| Method | Path | Body | Response | Cost |
|---|---|---|---|---|
| POST | /api/cli/creative/generate | { prompt, size?, quality?, angle?, format?, label? } | { url, artifactId } / 402 | ⚠️ 1 credit |
Mirrors the web creative route: reserveCreative(orgId) → generate + host → refund on failure.
Landing pages
| Method | Path | Body | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/landing-pages | — | { items } | free |
| POST | /api/cli/landing-pages | { business_name?, preferred_subdomain?, page_type?, spec?, strategy?, render?, publish? } | { ...site, version, published } | free |
Meta (read-only)
| Method | Path | Query | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/meta/campaigns | — | { connected, campaigns } | free |
| GET | /api/cli/meta/insights | ?range= | insights object | free |
Wallet & billing (read-only)
Payments stay on the web; these are read-only in the CLI.
| Method | Path | Response | Cost |
|---|---|---|---|
| GET | /api/cli/wallet | { balance, funding, autoRecharge } | free |
| GET | /api/cli/billing | { plan, credits, tiers, packs } | free |
Notifications
| Method | Path | Body | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/notifications | — | { items, unread } | free |
| POST | /api/cli/notifications/:id/read | — | { ok } | free |
Error shape
All CLI routes return errors as:
{ "error": "<code>", "message": "<human text>" }with an appropriate HTTP status:
| Status | Meaning | Typical message |
|---|---|---|
| 400 | Bad request | Invalid input. |
| 401 | Unauthorized | "Run bizos login." |
| 402 | Out of credits | "Out of credits — top up at app.bizos.lol/billing." |
| 404 | Not found | Resource does not exist (in your org). |
| 422 | Unprocessable | Validation failed. |
| 429 | Rate limited | Too many requests for this key. |
| 500 | Server error | Unexpected error. |
See Billing & credits for handling 402.