Reference
API overview
Learn how CLI's HTTP API works (auth, conventions, money, dry runs, approvals) and find the main endpoints.
Everything in CLI happens through one web API. The dashboard, the cli command and AI agents all use it, so anything a person can do, an agent can do too, under the same limits.
Do you need this page? Only if you're writing your own scripts or integration. If you use the dashboard or an AI agent, you never have to call the API yourself.
The technical version covers sign-in, how money and errors are shown, dry runs (preview a change without making it), approvals, and a map of every endpoint.
Everything in CLI is an HTTP API: the dashboard, the cli command, the MCP server and the skill file all use it, so anything a person can do, an agent can do too. This page covers the conventions every endpoint shares and maps the main endpoint groups. The full, generated reference is at /docs on the API server.
Base URL
https://api.clicloud.appAll paths on this page are relative to it, for example GET /v1/projects. If you run your own platform, use its CLI_PUBLIC_URL instead (see /docs/self-hosting).
Reference documents
| Address | What it is |
|---|---|
GET /v1/openapi.json | The OpenAPI document, generated from the running server: every route, request bodies from the same schemas the handlers enforce, and the error catalogue |
GET /docs | The same reference, readable in a browser |
GET /skill.md | The skill file for agents: sign-in, funding, the deploy loop, guardrails and a playbook for every error code |
GET /llms.txt | A short index for language models, linking to the skill file and the error catalogue |
GET /v1/errors | Every error code with its status, retry value and remediation (see /docs/errors) |
GET /v1/install | Every way to install CLI's MCP server for this server: npm package, registry name, Claude Code plugin and command, Cursor and VS Code links (see /docs/install) |
GET /.well-known/jwks.json | CLI's public key for checking agent credentials (see /docs/agent-credentials) |
Authentication
Send a token on every request, except the public ones:
Authorization: Bearer <token>| Token | Prefix | How you get it |
|---|---|---|
| Session token | cli_ | Wallet, email or GitHub sign-in, or cli login; a wallet session lasts 24 hours |
| Project key | clik_ | Created by an admin for an agent or CI, with a role, scopes and limits (see /docs/agent-permissions) |
Wallet sign-in
- Ask for a challenge:The address can be EVM (API
POST /v1/auth/challenge {"address": "0x…"}0x…) or Solana (base58). - Sign the returned
messageexactly as given:personal_sign(EIP-191) for EVM, or ed25519 over the UTF-8 bytes for Solana. - Exchange it for a token:API
POST /v1/auth/verify {"message": "…", "signature": "…"}
Each nonce works once (AUTH_NONCE_INVALID if reused or expired). A wallet needs no other sign-up: it can create and fund projects straight away.
Email sign-in
POST /v1/auth/email/start
{"email": "[email protected]"}
POST /v1/auth/email/verify
{"email": "[email protected]", "code": "123456"}Public endpoints
These need no token: pricing (/v1/pricing), config (/v1/config), the skill file, the OpenAPI document, the error catalogue, the directory of paid APIs, status pages, store pages, badges, receipt verification, install links (/v1/install), the agent benchmark (/v1/benchmark), public stats (/v1/stats, when the operator turns them on), checking agent credentials (/v1/credentials/* reads and verify, /.well-known/jwks.json), the files for machines in your own cloud (/v1/byoc/*), and the health checks (/health, /health/deep).
JSON conventions
- Requests and responses are JSON over HTTPS.
- Errors always use the same envelope with a stable
code(see /docs/errors). - A refused request because of role or scope is
FORBIDDEN, withdetails.requiredsaying what's needed.
Money units
Amounts are in micro-USDC: 1 USDC = 1,000,000. Credit is pegged to the dollar, so 1 USDC buys $1 of hosting.
{"balance": 12500000}That's $12.50. Per-second resource rates are published in nano-USDC (GET /v1/pricing), for example 20,000 nano-USDC per vCPU-second. A few inputs say their unit in the name instead, such as {"amountUsd": 20} for a card top-up.
IDs
IDs carry a prefix that says what they are:
| Prefix | What |
|---|---|
prj_ | Project (environments are projects too) |
svc_ | Service (apps and databases) |
dep_ | Deploy |
apr_ | Approval |
aud_ | Change (audit entry) |
sbx_ | Sandbox |
inc_ | Incident |
run_ | Sandbox command |
pst_ | Payment stream |
cli_, clik_, clps_ | Session token, project key, stream token |
Dry runs
Most changes accept ?dryRun=true or the header X-CLI-Dry-Run: true. Nothing changes and nothing is recorded. The answer is a plan:
For example, a dry run of a deploy (POST /v1/services/:id/deploys?dryRun=true) answers:
{
"dryRun": true,
"plan": {
"service": "web",
"action": "deploy",
"hourlyCost": 20000,
"addsCost": 0,
"replaces": "dep_…",
"restart": "none: traffic moves once the new version is healthy",
"missingReferences": [],
"wouldFail": null,
"needsApproval": false
}
}Plans say what would change, the hourly cost, what restarts, what would break, wouldFail (for example not enough credit) and needsApproval. The exact fields depend on the change.
Saying why: X-CLI-Intent
Any change can carry a one-sentence reason:
X-CLI-Intent: The app needs a database for sessionsIt's shown in the flight recorder beside the change and on approval requests. MCP tools send it from their why argument.
Approvals: X-CLI-Approval
When the project's rules say a change needs a person, CLI answers 403 APPROVAL_REQUIRED with details.approvalId and details.approveUrl.
- Tell the person and point them at the approve link.
- Poll
GET /v1/approvals/:iduntil its status isapprovedordenied. - If approved, resend the identical request with the approval id:API
X-CLI-Approval: apr_…
An approval works once, for that exact request (APPROVAL_INVALID otherwise). See Approvals.
Pagination
Lists that can grow use cursors rather than pages:
| Endpoint | How to page |
|---|---|
GET /v1/projects/:id/events | Pass after=<seq>; the answer's next is the cursor for the next call. limit up to 500 |
GET /v1/projects/:id/audit | Pass before=<seq>; the answer's next is the cursor for older entries. limit sets the size |
GET /v1/sandboxes/:id/runs | Pass after=<seq> to get only newer commands |
GET /v1/projects/:id/flight | limit sets how many recent changes |
Other lists return everything at once.
Rate limits
When you go over a limit, CLI answers 429 RATE_LIMITED with details.retryAfterSeconds. Wait that long; don't retry in a loop. Limits include:
- requests per minute: 600 per API key, connector sign-in or session, and 120 per IP address for requests without one (every response carries
RateLimit-LimitandRateLimit-Remaining; health checks, flag reads, webhook inboxes, and opening dashboard pages and their files aren't counted, so a team behind one office address isn't blocked from the dashboard); - deploys per project per hour (30 by default);
- sign-in emails per address per hour;
- five wrong second-factor answers, which lock the factor for 15 minutes (
MFA_LOCKED).
Paying over x402
Endpoints that start compute, top-ups and paid routes can answer 402 with an x402 challenge: accepts[] in the body, also base64-encoded in the PAYMENT-REQUIRED header. Sign a USDC payment on Base or Solana and resend the same request with the PAYMENT-SIGNATURE header. See Credit, pricing and billing.
Endpoint map
These are the most-used endpoints. :id is the id of the resource named by the path segment before it.
Account
| Method | Path | What it does |
|---|---|---|
| GET | /v1/me | Who you are, your projects and whether you'd get welcome credit |
| GET | /v1/me/wallet | A key's spending cap, what's left, scopes and services |
| GET | /v1/home | What happened across your projects since you last looked |
| GET | /v1/me/inbox | Items waiting for you (approvals, failures, proposals) |
| POST | /v1/auth/step-up | Confirm with a second factor for 10 minutes |
| GET | /v1/me/sessions | Where you're signed in, and the server's idle timeout (idleMinutes) |
| POST | /v1/me/sessions/revoke-all | Sign out everywhere else; {"keepThisSession": false} signs this session out too |
| GET | /v1/me/deleted-projects | Projects you own that are in the trash and can still be restored |
| GET | /v1/me/delete | What stands in the way of deleting your account: ownedProjects, memberships |
| DELETE | /v1/me | Delete your account (a person, step-up, no live projects you own) |
Session, deleted-project and account routes need a person; API keys get FORBIDDEN. See Teams and security and Deleting projects and accounts.
Projects and people
| Method | Path | What it does |
|---|---|---|
| POST | /v1/projects | Create a project |
| GET | /v1/projects | List your projects |
| GET | /v1/projects/:id | Balance, status, services, members, approval policy and service graph |
| PATCH | /v1/projects/:id | Change settings, such as lowBalanceAlert |
| POST | /v1/projects/:id/environments | Copy the project into an environment (staging, dev…) |
| DELETE | /v1/projects/:id | A whole project: to the trash for 7 days (owner, a person, step-up; dry run shows the plan). An environment: deleted at once with its data (admins) |
| POST | /v1/projects/:id/restore | Bring a deleted project back within 7 days, services stopped (owner, a person) |
| POST | /v1/projects/:id/members | Add a person or agent wallet with a role |
| POST | /v1/projects/:id/keys | Create a project key (clik_…, shown once) |
| POST | /v1/projects/:id/keys/revoke-all | Revoke every key and agent member |
| GET | /v1/projects/:id/audit | Who changed what |
Security and access reviews
| Method | Path | What it does |
|---|---|---|
| GET | /v1/projects/:id/security | Whether the project requires a second factor for changes |
| PUT | /v1/projects/:id/security | Turn requireTwoFactor on or off (owner, with a second factor) |
| GET | /v1/projects/:id/access-reviews | Recent access reviews and the schedule (admins) |
| POST | /v1/projects/:id/access-reviews | Start a review (a person, admins) |
| PUT | /v1/projects/:id/access-reviews/schedule | Review every accessReviewDays (7 to 365, or null) |
| GET | /v1/access-reviews/:id | One review, with every entry |
| POST | /v1/access-reviews/:id/decide | Keep or remove one entry: principal, keep |
| POST | /v1/access-reviews/:id/complete | Finish a review once everything is decided |
See Access reviews and 2FA rules.
Funding and spending
| Method | Path | What it does |
|---|---|---|
| POST | /v1/projects/:id/topup?amount=<micro> | Add credit over x402 (answers 402 first) |
| POST | /v1/projects/:id/topup/card | A card checkout link |
| GET | /v1/projects/:id/deposit-address | The project's USDC deposit address |
| GET | /v1/projects/:id/usage | Balance, burn per hour, runway, cost per service |
| GET | /v1/projects/:id/burn | The burn meter: hourly bars, pace and runway |
| GET | /v1/projects/:id/flows?days=30 | Where money came from and went |
| PUT | /v1/projects/:id/budget | Set a monthly budget |
| GET | /v1/pricing | Published rates (public) |
Services and deploys
| Method | Path | What it does |
|---|---|---|
| POST | /v1/projects/:id/services | Create a service from git, GitHub, an image or an upload |
| PATCH | /v1/services/:id | Change plan, replicas, autoscale, sleep, volume, GPU, release command, canary… |
| DELETE | /v1/services/:id | Move a service to the trash for 7 days |
| PUT | /v1/services/:id/env | Set or delete variables |
| GET | /v1/services/:id/env/check | Check every variable reference resolves |
| POST | /v1/services/:id/deploys | Deploy |
| GET | /v1/deploys/:id | A deploy's status, with the classified error if it failed |
| GET | /v1/deploys/:id/diff | What changed since the previous live deploy |
| POST | /v1/deploys/:id/rollback | Redeploy an earlier healthy image |
| POST | /v1/projects/:id/templates/:template | Deploy a one-click stack |
| POST | /v1/projects/:id/import | Plan or create services from another platform |
Databases
| Method | Path | What it does |
|---|---|---|
| POST | /v1/projects/:id/databases | Create Postgres, MySQL, Redis or MongoDB |
| POST | /v1/services/:id/link | Give an app a database's connection URL |
| GET | /v1/services/:id/connection | Connection URLs (needs secrets scope and step-up) |
| POST | /v1/services/:id/backups | Back up now |
| POST | /v1/backups/:id/restore | Replace data with a backup |
| POST | /v1/services/:id/query | Run SQL (read-only by default) |
Domains
| Method | Path | What it does |
|---|---|---|
| POST | /v1/services/:id/domains/generate | A hosted subdomain, live at once |
| POST | /v1/services/:id/domains | Add your own domain; returns DNS records |
| POST | /v1/domains/:id/verify | Check DNS and go live |
Running and monitoring
| Method | Path | What it does |
|---|---|---|
| GET | /v1/services/:id/logs?tail=200 | Recent output, with q and level search |
| GET | /v1/services/:id/logs/stream | Live output (server-sent events) |
| GET | /v1/services/:id/requests?hours=24 | Requests, 4xx/5xx and latency |
| GET | /v1/services/:id/traces?sort=slow | Slowest requests and per-route latency |
| GET | /v1/projects/:id/errors?status=open | Grouped exceptions |
| POST | /v1/services/:id/ask | Ask a question about a service |
| GET | /v1/services/:id/health | Up or down, uptime and incidents |
| POST | /v1/services/:id/exec | Run a command in the live container |
| GET | /v1/projects/:id/events | Events since a cursor (also /events/stream) |
| POST | /v1/projects/:id/channels | Send events to Slack, Discord, Telegram or a webhook |
| GET | /v1/incidents/:id/story | An incident's story, cause and suggested fix |
| GET | /v1/projects/:id/proposals?status=open | The on-call agent's proposals |
Servers and your own cloud
| Method | Path | What it does |
|---|---|---|
| GET | /v1/projects/:id/servers | The platform's regions and the project's own servers, with status |
| POST | /v1/projects/:id/servers | Add a server (admins). With "connect": true the worker connects out; the answer holds the secret and install files, once |
| POST | /v1/servers/:id/check | Ask the server's worker if it's there (admins) |
| POST | /v1/servers/:id/rotate-secret | A new worker secret; the old one stops at once (admins) |
| DELETE | /v1/servers/:id | Remove a server with no services on it (admins) |
| GET | /v1/projects/:id/placement | Whether the project keeps to its own servers, and its default server |
| PUT | /v1/projects/:id/placement | Set ownServersOnly and defaultServerId (admins) |
| GET | /v1/byoc/compose.yml | The compose file for a machine in your cloud (public) |
| GET | /v1/byoc/host-setup.sh | The host setup script cloud-init runs (public) |
| GET | /v1/workers/connect | Where a worker in your cloud opens its WebSocket, with ?server=srv_…&t=<ms> and its link token as a Bearer token |
Governing agents
| Method | Path | What it does |
|---|---|---|
| PUT | /v1/projects/:id/rules | Save rules for agents written in plain language |
| GET | /v1/approvals/:id | An approval's status |
| POST | /v1/approvals/:id/approve | Approve a request (people, with step-up) |
| GET | /v1/projects/:id/flight | The flight recorder |
| POST | /v1/flight/:id/undo | Undo one change |
| POST | /v1/projects/:id/changes | Propose a change for a person to apply |
| POST | /v1/projects/:id/intent | Turn a sentence into a priced plan |
Agent credentials
| Method | Path | What it does |
|---|---|---|
| POST | /v1/agents/me/credential | An agent's own signed credential (with its key; audience, ttlHours) |
| GET | /v1/agents/me/record | An agent's record, its bound wallet and how many keys it adds up |
| GET | /v1/agents/me/wallet/challenge?address=0x… | The message to sign to bind a wallet |
| POST | /v1/agents/me/wallet | Bind a wallet with address, message and signature |
| DELETE | /v1/agents/me/wallet | Unbind the wallet |
| POST | /v1/projects/:id/keys/:keyId/credential | Issue a credential for one of the project's keys (admins) |
| GET | /v1/projects/:id/credentials | Credentials issued for the project's agents (admins) |
| POST | /v1/credentials/:jti/revoke | Revoke a credential (admins, or the agent itself) |
| POST | /v1/credentials/verify | Check a credential, optionally for an audience (public) |
| GET | /v1/credentials/:jti | Whether a credential is still valid (public) |
| GET | /v1/credentials/keys | CLI's public key, the same as /.well-known/jwks.json (public) |
See Agent credentials.
Sandboxes and hosted agents
| Method | Path | What it does |
|---|---|---|
| POST | /v1/projects/:id/sandboxes | Start a sandbox |
| POST | /v1/sandboxes/:id/exec | Run a command in it |
| POST | /v1/projects/:id/hosted-agents | Create a hosted agent |
Selling and buying
| Method | Path | What it does |
|---|---|---|
| PUT | /v1/services/:id/paywall | Charge per request on chosen routes |
| PUT | /v1/services/:id/mcp | Charge per MCP tool call |
| PUT | /v1/services/:id/guarantee | Offer refunds for failed paid calls |
| GET | /v1/directory?q=… | Search paid APIs (public) |
| GET | /v1/projects/:id/earnings | What the project earned |
| POST | /v1/projects/:id/withdrawals | Withdraw earnings (owner, step-up) |
| PUT | /v1/services/:id/outbound | Let an app pay for other APIs, with caps |
Install links, the benchmark and health
| Method | Path | What it does |
|---|---|---|
| GET | /v1/install | Install lines and links for every agent app (public, no keys) |
| GET | /v1/benchmark | The latest agent benchmark run and earlier ones (public) |
| GET | /v1/benchmark/:id | One benchmark run (public) |
| GET | /v1/stats | Headline usage numbers, when the operator publishes them (public) |
| GET | /health/deep | Database, leader and platform backup checks for an uptime monitor: 200 or 503 (public) |
See Install in your agent app and The agent benchmark.
Operators
These need you to be a CLI operator with a role that covers the route. People in CLI_OPERATORS are admins, and admins can do everything; others have the support or finance role (see /docs/compliance). Anyone who isn't an operator gets FORBIDDEN; an operator whose role doesn't cover the route gets FORBIDDEN with details.role and details.required.
| Method | Path | What it does | Role |
|---|---|---|---|
| GET | /v1/admin/me | Your principal and operator role | any operator |
| POST | /v1/admin/people/:principal/sessions/revoke | End every session a person has (incident response) | admin |
| GET | /v1/admin/traction?weeks=12 | Usage numbers: totals, weeks and cohorts (see /docs/traction) | finance |
| POST | /v1/admin/benchmark | Publish a benchmark run | admin |
| DELETE | /v1/admin/benchmark/:id | Remove a published benchmark run | admin |
| GET | /v1/admin/access-reviews | Operator access reviews and their schedule | admin |
| POST | /v1/admin/access-reviews | Start an operator access review | admin |
| PUT | /v1/admin/access-reviews/schedule | Review operators every accessReviewDays | admin |
| GET | /v1/admin/compliance/evidence?from=&to= | The evidence export for a period (see /docs/compliance) | admin |
| POST | /v1/admin/compliance/restore-drills | Record a restore drill: ok, notes | admin |
| GET | /v1/admin/operators | Every operator with role, fromEnv, addedBy, addedAt, and the roles there are | admin |
| PUT | /v1/admin/operators | Give someone a role, or change it: principal, role | admin |
| DELETE | /v1/admin/operators/:principal | Take someone's role away (not those in CLI_OPERATORS; URL-encode the principal) | admin |
| GET | /v1/admin/security-incidents?open=true | The security incident register (open=true: not yet resolved) | admin |
| POST | /v1/admin/security-incidents | Open one: title, severity (low, medium, high, critical), summary, optional detectedAt | admin |
| GET | /v1/admin/security-incidents/:id | One incident with its timeline | admin |
| PATCH | /v1/admin/security-incidents/:id | Change status (open, contained, resolved; resolving needs a root cause), severity, customersNotified, rootCause, postmortem, title | admin |
| POST | /v1/admin/security-incidents/:id/notes | Add to the timeline: text | admin |
The finance role also covers the payout review queue (/v1/admin/payouts) and the CLI token's operator routes (/v1/admin/token); support covers the abuse queue, suspensions, GET /v1/admin/cluster and GET /v1/admin/backups. Taking a backup (POST /v1/admin/backups) needs admin.
With CLI_REQUIRE_OPERATOR_2FA=true, an operator without a second factor gets MFA_REQUIRED.
On-chain
| Method | Path | What it does |
|---|---|---|
| POST | /v1/projects/:id/rpc/:chainId | JSON-RPC with failover |
| POST | /v1/projects/:id/signers | Create a managed signer with a policy |
| POST | /v1/services/:id/watchers | Call the app on blocks or contract events |
For everything else, open /docs on the API server or read /v1/openapi.json.