API
The raw /api/cli/* endpoints — method, path, body, response and cost — for calling BizOS directly.
Every CLI command maps to a /api/cli/* endpoint. Call them
directly if you would rather not install anything.
Base URL: https://app.bizos.lol (override with BIZOS_API_URL / --api-url)
Auth: Authorization: Bearer bzk_live_…curl -s https://app.bizos.lol/api/cli/whoami \
-H "Authorization: Bearer $BIZOS_API_KEY"Every route resolves your organization from the key, is rate-limited per key, and can never bypass billing. Routes marked (cookie) use a logged-in browser session instead — the dashboard uses them, not the CLI.
Scope
Your tasks, your documents, your credits. Ads, leads, creative generation and landing pages are not reachable with an API key; they live in the app.
Deliberate: a key stays a small, predictable surface.
Identity & keys
| Method | Path | Auth | Body | Response | Cost |
|---|---|---|---|---|---|
| GET | /api/cli/whoami | key | — | { org: { id, name|null }, plan, credits } | free |
| POST | /api/cli/keys | cookie | { name } | { key, secret } (shown once) | free |
| GET | /api/cli/keys | cookie | — | { keys: [...] } | free |
| DELETE | /api/cli/keys/:id | cookie | — | { ok } | free |
credits is a single number: how many Work Credits you can spend right now.
Tasks
| Method | Path | Body | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/tasks | — | { items, credits } | free |
| POST | /api/cli/tasks | { text } | { task, credits } | free |
| GET | /api/cli/tasks/:id | — | { task, finished } | free |
| POST | /api/cli/tasks/:id/run | — | { taskId, status, finished } / 402 | ⚠️ 1 credit |
Work is asynchronous, so the run route usually answers
status: "in_progress" — the task is not finished when the call returns. Poll
GET /api/cli/tasks/:id and watch finished, which is computed server-side, so
you never maintain your own list of final statuses.
A task carries a fixed set of fields: id, text, description, status, scheduling and timestamps.
Documents
| Method | Path | Body | 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 |
Notifications
| Method | Path | Body | Response | Cost |
|---|---|---|---|---|
| GET | /api/cli/notifications | — | { items, unread } | free |
| POST | /api/cli/notifications/:id/read | — | { ok } | free |
read is a boolean.
Errors
Every route errors the same way:
{ "error": "<code>", "message": "<human text>" }error is one of a fixed list — branch on it, not on the message text:
| Code | Typical status | Meaning |
|---|---|---|
unauthorized | 401 | Key missing or invalid. |
not_found | 404 | No such task or document for this org. |
invalid_request | 400 / 409 | The request cannot be accepted as written. |
no_credits | 402 | Out of Work Credits — top up in the app. |
busy | 409 | The agent is working on something else; this starts right after. |
rate_limited | 429 | Too many requests — honour Retry-After. |
unavailable | 503 | Temporary — retry shortly. |
On 402, stop rather than retry: it will keep returning 402 until you top up.
See Billing & Work Credits.