Appearance
API overview
The MicroApps API is a plain REST API that speaks JSON. It is the same API the console uses, so anything you can do by clicking, you can do with an HTTP request. What the console uses is what you get.
Base URL
https://cloud-api.microapps.ioAuthentication
Every request under /api carries a bearer token in the Authorization header:
http
Authorization: Bearer <token>The token can be one of two things, and the API works out which by looking at it:
- A login token (JWT) from
POST /auth/login. Good for interactive sessions. It expires after about an hour and there is no refresh endpoint, so long-lived automation should use the other option. - An API key (starts with
mck_) that you create once and reuse. Best for scripts, servers, and anything that runs without a human present. See API keys.
A few endpoints under /auth/* and /open/* need no token at all.
Content type
Requests and responses are JSON unless a specific endpoint says otherwise (invoice PDFs and the pod console are the exceptions).
http
Content-Type: application/json
Accept: application/jsonPagination
List endpoints that can grow without bound take three query parameters:
| Parameter | Default | Notes |
|---|---|---|
page | 1 | 1-based |
limit | 20 | max 100 |
search | - | case-insensitive substring match, up to 100 characters |
GET /api/pods?page=1&limit=20&search=webThey return an envelope:
json
{
"data": [ ... ],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3
}Smaller collections (a pod's snapshots, a firewall's rules) come back as a plain array. Each endpoint's page says which shape it uses.
Errors
Errors are JSON with a single message field. The HTTP status carries the category.
json
{ "message": "name is required" }| Status | Meaning |
|---|---|
400 | Bad request - your input did not validate |
401 | Unauthorized - missing, invalid, or expired token |
402 | Insufficient credit - top up and try again |
403 | Forbidden - no permission, or you hit an account limit |
404 | Not found - or not yours |
409 | Conflict - a duplicate, or the resource is busy with another operation |
428 | A domain you are adding needs ownership validation first |
429 | Too many requests, or too many failed logins |
500 | Something broke on our side |
Credit and limits
Creating anything billable (pods, snapshots, backups, networks, firewalls, domains, email accounts) needs at least $3 of account credit, or you get a 402. Each resource type also has a per-account limit; hit it and you get a 403. (The per-pod snapshot and backup caps are the one exception - those return 400.) Both are covered in Billing and Account limits.
Rate limits
Requests under /api are limited per account; /auth and /open are limited per IP. The defaults are generous for normal use. If you have a legitimate reason to go faster, tell us - we would rather raise the limit than watch you write exponential backoff.
Asynchronous operations
A lot of actions (creating a pod, resizing, restoring a snapshot, cloning) kick off work in the background. The API responds right away with the new resource in a transient status like Initializing or Restoring, and you poll until it settles. Firing a second operation at a resource that is still busy returns 409.