Docs menu

Reference

API overview

Learn how CLI's HTTP API works (auth, conventions, money, dry runs, approvals) and find the main endpoints.

Explain it

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.app

All 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

AddressWhat it is
GET /v1/openapi.jsonThe OpenAPI document, generated from the running server: every route, request bodies from the same schemas the handlers enforce, and the error catalogue
GET /docsThe same reference, readable in a browser
GET /skill.mdThe skill file for agents: sign-in, funding, the deploy loop, guardrails and a playbook for every error code
GET /llms.txtA short index for language models, linking to the skill file and the error catalogue
GET /v1/errorsEvery error code with its status, retry value and remediation (see /docs/errors)
GET /v1/installEvery 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.jsonCLI's public key for checking agent credentials (see /docs/agent-credentials)

Authentication

Send a token on every request, except the public ones:

API
Authorization: Bearer <token>
TokenPrefixHow you get it
Session tokencli_Wallet, email or GitHub sign-in, or cli login; a wallet session lasts 24 hours
Project keyclik_Created by an admin for an agent or CI, with a role, scopes and limits (see /docs/agent-permissions)

Wallet sign-in

  1. Ask for a challenge:
    API
    POST /v1/auth/challenge
    {"address": "0x…"}
    The address can be EVM (0x…) or Solana (base58).
  2. Sign the returned message exactly as given: personal_sign (EIP-191) for EVM, or ed25519 over the UTF-8 bytes for Solana.
  3. 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

API
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, with details.required saying 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.

JSON
{"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:

PrefixWhat
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:

JSON
{
  "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:

API
X-CLI-Intent: The app needs a database for sessions

It'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.

  1. Tell the person and point them at the approve link.
  2. Poll GET /v1/approvals/:id until its status is approved or denied.
  3. 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:

EndpointHow to page
GET /v1/projects/:id/eventsPass after=<seq>; the answer's next is the cursor for the next call. limit up to 500
GET /v1/projects/:id/auditPass before=<seq>; the answer's next is the cursor for older entries. limit sets the size
GET /v1/sandboxes/:id/runsPass after=<seq> to get only newer commands
GET /v1/projects/:id/flightlimit 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-Limit and RateLimit-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

MethodPathWhat it does
GET/v1/meWho you are, your projects and whether you'd get welcome credit
GET/v1/me/walletA key's spending cap, what's left, scopes and services
GET/v1/homeWhat happened across your projects since you last looked
GET/v1/me/inboxItems waiting for you (approvals, failures, proposals)
POST/v1/auth/step-upConfirm with a second factor for 10 minutes
GET/v1/me/sessionsWhere you're signed in, and the server's idle timeout (idleMinutes)
POST/v1/me/sessions/revoke-allSign out everywhere else; {"keepThisSession": false} signs this session out too
GET/v1/me/deleted-projectsProjects you own that are in the trash and can still be restored
GET/v1/me/deleteWhat stands in the way of deleting your account: ownedProjects, memberships
DELETE/v1/meDelete 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

MethodPathWhat it does
POST/v1/projectsCreate a project
GET/v1/projectsList your projects
GET/v1/projects/:idBalance, status, services, members, approval policy and service graph
PATCH/v1/projects/:idChange settings, such as lowBalanceAlert
POST/v1/projects/:id/environmentsCopy the project into an environment (staging, dev…)
DELETE/v1/projects/:idA 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/restoreBring a deleted project back within 7 days, services stopped (owner, a person)
POST/v1/projects/:id/membersAdd a person or agent wallet with a role
POST/v1/projects/:id/keysCreate a project key (clik_…, shown once)
POST/v1/projects/:id/keys/revoke-allRevoke every key and agent member
GET/v1/projects/:id/auditWho changed what

Security and access reviews

MethodPathWhat it does
GET/v1/projects/:id/securityWhether the project requires a second factor for changes
PUT/v1/projects/:id/securityTurn requireTwoFactor on or off (owner, with a second factor)
GET/v1/projects/:id/access-reviewsRecent access reviews and the schedule (admins)
POST/v1/projects/:id/access-reviewsStart a review (a person, admins)
PUT/v1/projects/:id/access-reviews/scheduleReview every accessReviewDays (7 to 365, or null)
GET/v1/access-reviews/:idOne review, with every entry
POST/v1/access-reviews/:id/decideKeep or remove one entry: principal, keep
POST/v1/access-reviews/:id/completeFinish a review once everything is decided

See Access reviews and 2FA rules.

Funding and spending

MethodPathWhat it does
POST/v1/projects/:id/topup?amount=<micro>Add credit over x402 (answers 402 first)
POST/v1/projects/:id/topup/cardA card checkout link
GET/v1/projects/:id/deposit-addressThe project's USDC deposit address
GET/v1/projects/:id/usageBalance, burn per hour, runway, cost per service
GET/v1/projects/:id/burnThe burn meter: hourly bars, pace and runway
GET/v1/projects/:id/flows?days=30Where money came from and went
PUT/v1/projects/:id/budgetSet a monthly budget
GET/v1/pricingPublished rates (public)

Services and deploys

MethodPathWhat it does
POST/v1/projects/:id/servicesCreate a service from git, GitHub, an image or an upload
PATCH/v1/services/:idChange plan, replicas, autoscale, sleep, volume, GPU, release command, canary…
DELETE/v1/services/:idMove a service to the trash for 7 days
PUT/v1/services/:id/envSet or delete variables
GET/v1/services/:id/env/checkCheck every variable reference resolves
POST/v1/services/:id/deploysDeploy
GET/v1/deploys/:idA deploy's status, with the classified error if it failed
GET/v1/deploys/:id/diffWhat changed since the previous live deploy
POST/v1/deploys/:id/rollbackRedeploy an earlier healthy image
POST/v1/projects/:id/templates/:templateDeploy a one-click stack
POST/v1/projects/:id/importPlan or create services from another platform

Databases

MethodPathWhat it does
POST/v1/projects/:id/databasesCreate Postgres, MySQL, Redis or MongoDB
POST/v1/services/:id/linkGive an app a database's connection URL
GET/v1/services/:id/connectionConnection URLs (needs secrets scope and step-up)
POST/v1/services/:id/backupsBack up now
POST/v1/backups/:id/restoreReplace data with a backup
POST/v1/services/:id/queryRun SQL (read-only by default)

Domains

MethodPathWhat it does
POST/v1/services/:id/domains/generateA hosted subdomain, live at once
POST/v1/services/:id/domainsAdd your own domain; returns DNS records
POST/v1/domains/:id/verifyCheck DNS and go live

Running and monitoring

MethodPathWhat it does
GET/v1/services/:id/logs?tail=200Recent output, with q and level search
GET/v1/services/:id/logs/streamLive output (server-sent events)
GET/v1/services/:id/requests?hours=24Requests, 4xx/5xx and latency
GET/v1/services/:id/traces?sort=slowSlowest requests and per-route latency
GET/v1/projects/:id/errors?status=openGrouped exceptions
POST/v1/services/:id/askAsk a question about a service
GET/v1/services/:id/healthUp or down, uptime and incidents
POST/v1/services/:id/execRun a command in the live container
GET/v1/projects/:id/eventsEvents since a cursor (also /events/stream)
POST/v1/projects/:id/channelsSend events to Slack, Discord, Telegram or a webhook
GET/v1/incidents/:id/storyAn incident's story, cause and suggested fix
GET/v1/projects/:id/proposals?status=openThe on-call agent's proposals

Servers and your own cloud

MethodPathWhat it does
GET/v1/projects/:id/serversThe platform's regions and the project's own servers, with status
POST/v1/projects/:id/serversAdd a server (admins). With "connect": true the worker connects out; the answer holds the secret and install files, once
POST/v1/servers/:id/checkAsk the server's worker if it's there (admins)
POST/v1/servers/:id/rotate-secretA new worker secret; the old one stops at once (admins)
DELETE/v1/servers/:idRemove a server with no services on it (admins)
GET/v1/projects/:id/placementWhether the project keeps to its own servers, and its default server
PUT/v1/projects/:id/placementSet ownServersOnly and defaultServerId (admins)
GET/v1/byoc/compose.ymlThe compose file for a machine in your cloud (public)
GET/v1/byoc/host-setup.shThe host setup script cloud-init runs (public)
GET/v1/workers/connectWhere a worker in your cloud opens its WebSocket, with ?server=srv_…&t=<ms> and its link token as a Bearer token

See Run in your own cloud.

Governing agents

MethodPathWhat it does
PUT/v1/projects/:id/rulesSave rules for agents written in plain language
GET/v1/approvals/:idAn approval's status
POST/v1/approvals/:id/approveApprove a request (people, with step-up)
GET/v1/projects/:id/flightThe flight recorder
POST/v1/flight/:id/undoUndo one change
POST/v1/projects/:id/changesPropose a change for a person to apply
POST/v1/projects/:id/intentTurn a sentence into a priced plan

Agent credentials

MethodPathWhat it does
POST/v1/agents/me/credentialAn agent's own signed credential (with its key; audience, ttlHours)
GET/v1/agents/me/recordAn 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/walletBind a wallet with address, message and signature
DELETE/v1/agents/me/walletUnbind the wallet
POST/v1/projects/:id/keys/:keyId/credentialIssue a credential for one of the project's keys (admins)
GET/v1/projects/:id/credentialsCredentials issued for the project's agents (admins)
POST/v1/credentials/:jti/revokeRevoke a credential (admins, or the agent itself)
POST/v1/credentials/verifyCheck a credential, optionally for an audience (public)
GET/v1/credentials/:jtiWhether a credential is still valid (public)
GET/v1/credentials/keysCLI's public key, the same as /.well-known/jwks.json (public)

See Agent credentials.

Sandboxes and hosted agents

MethodPathWhat it does
POST/v1/projects/:id/sandboxesStart a sandbox
POST/v1/sandboxes/:id/execRun a command in it
POST/v1/projects/:id/hosted-agentsCreate a hosted agent

Selling and buying

MethodPathWhat it does
PUT/v1/services/:id/paywallCharge per request on chosen routes
PUT/v1/services/:id/mcpCharge per MCP tool call
PUT/v1/services/:id/guaranteeOffer refunds for failed paid calls
GET/v1/directory?q=…Search paid APIs (public)
GET/v1/projects/:id/earningsWhat the project earned
POST/v1/projects/:id/withdrawalsWithdraw earnings (owner, step-up)
PUT/v1/services/:id/outboundLet an app pay for other APIs, with caps
MethodPathWhat it does
GET/v1/installInstall lines and links for every agent app (public, no keys)
GET/v1/benchmarkThe latest agent benchmark run and earlier ones (public)
GET/v1/benchmark/:idOne benchmark run (public)
GET/v1/statsHeadline usage numbers, when the operator publishes them (public)
GET/health/deepDatabase, 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.

MethodPathWhat it doesRole
GET/v1/admin/meYour principal and operator roleany operator
POST/v1/admin/people/:principal/sessions/revokeEnd every session a person has (incident response)admin
GET/v1/admin/traction?weeks=12Usage numbers: totals, weeks and cohorts (see /docs/traction)finance
POST/v1/admin/benchmarkPublish a benchmark runadmin
DELETE/v1/admin/benchmark/:idRemove a published benchmark runadmin
GET/v1/admin/access-reviewsOperator access reviews and their scheduleadmin
POST/v1/admin/access-reviewsStart an operator access reviewadmin
PUT/v1/admin/access-reviews/scheduleReview operators every accessReviewDaysadmin
GET/v1/admin/compliance/evidence?from=&to=The evidence export for a period (see /docs/compliance)admin
POST/v1/admin/compliance/restore-drillsRecord a restore drill: ok, notesadmin
GET/v1/admin/operatorsEvery operator with role, fromEnv, addedBy, addedAt, and the roles there areadmin
PUT/v1/admin/operatorsGive someone a role, or change it: principal, roleadmin
DELETE/v1/admin/operators/:principalTake someone's role away (not those in CLI_OPERATORS; URL-encode the principal)admin
GET/v1/admin/security-incidents?open=trueThe security incident register (open=true: not yet resolved)admin
POST/v1/admin/security-incidentsOpen one: title, severity (low, medium, high, critical), summary, optional detectedAtadmin
GET/v1/admin/security-incidents/:idOne incident with its timelineadmin
PATCH/v1/admin/security-incidents/:idChange status (open, contained, resolved; resolving needs a root cause), severity, customersNotified, rootCause, postmortem, titleadmin
POST/v1/admin/security-incidents/:id/notesAdd to the timeline: textadmin

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

MethodPathWhat it does
POST/v1/projects/:id/rpc/:chainIdJSON-RPC with failover
POST/v1/projects/:id/signersCreate a managed signer with a policy
POST/v1/services/:id/watchersCall the app on blocks or contract events

For everything else, open /docs on the API server or read /v1/openapi.json.