API, CLI and MCP

Everything the dashboard does with apps and databases, from scripts, your terminal or an AI agent.

Tokens and scopes

Make a token in Settings, API tokens, and send it as Authorization: Bearer rdx_.... It acts as you, in one workspace, at most at its scope: read looks (a viewer), deploy does a member's work, full has your own role. Deletes made with a token stop the service at once and remove it after 48 hours, unless it's undeleted. Errors come back as { error } with a 4xx status. The machine-readable description is /api/openapi.json.

curl -H "Authorization: Bearer $WATTLE_TOKEN" https://app.wattlecloud.com/api/services

The wattle CLI

Needs Node.js 20 or newer. Install it, sign in through the browser, then deploy a folder:

curl -fsSL https://app.wattlecloud.com/cli/install.sh | sh          # macOS, Linux
irm https://app.wattlecloud.com/cli/install.ps1 | iex              # Windows PowerShell

wattle login
wattle link my-app      # in your project's folder
wattle up               # build and deploy it
wattle logs -f
wattle run -- npx prisma migrate deploy
wattle db connect postgres

wattle help lists every command. In CI, set WATTLE_TOKEN to a deploy token instead of signing in.

MCP, for AI agents

Connect Claude Code, or any MCP client, to https://app.wattlecloud.com/api/mcp. It signs in through the browser (OAuth), where you pick the workspace and what it may do. Tools that change or delete things are marked as such, and a delete waits 48 hours.

claude mcp add --transport http wattle https://app.wattlecloud.com/api/mcp

Or with a token, for scripts: add a header, --header "Authorization: Bearer rdx_...".

Endpoints

Services

get/api/servicesList servicesread

Needs the viewer role, so a read token or wider.

post/api/servicesCreate a database or an appdeploy

A database: { kind: "db", engine }. An app from an image: { kind: "app", image, port }. From GitHub: { kind: "app", github: { installationId, repoId, branch } }.

Needs the member role, so a deploy token or wider.

{
  "kind": "db | app",
  "engine": "string",
  "name": "string",
  "region": "string",
  "image": "string",
  "port": "integer",
  "volumePath": "string",
  "worker": "boolean",
  "cron": "string",
  "github": "object"
}

get/api/services/{id}Get a servicedeploy

A database's connection details (with passwords), or an app's settings.

Needs the member role, so a deploy token or wider.

patch/api/services/{id}Change a servicedeploy

An app's settings, or a database's public access or sizes.

Needs the member role, so a deploy token or wider.

{
  "port": "integer",
  "memoryMb": "integer",
  "diskMb": "integer",
  "public": "boolean",
  "builder": "railpack | dockerfile",
  "rootDir": "string",
  "dockerfilePath": "string",
  "buildCommand": "string",
  "startCommand": "string",
  "preDeployCommand": "string",
  "healthPath": "string",
  "cronSchedule": "string",
  "watchPaths": "array",
  "autoDeploy": "boolean",
  "branch": "string"
}

delete/api/services/{id}Delete a servicefull

With its data. Asked with a token, it stops now and is removed after 48 hours unless undeleted; the answer has deleteAt.

Needs the admin role, so a full token or wider.

{
  "confirm": "string"
}

post/api/services/{id}/undeleteUndo a deletefull

Within the 48 hours of a delete made with a token.

Needs the admin role, so a full token or wider.

post/api/services/{id}/actionsStart, stop, restart or redeploydeploy

Needs the member role, so a deploy token or wider.

{
  "action": "start | stop | restart | redeploy"
}

Apps

get/api/services/{id}/variablesGet an app's variablesdeploy

Needs the member role, so a deploy token or wider.

put/api/services/{id}/variablesReplace an app's variablesdeploy

The whole list, for the app (scope "service") or its environment ("shared"). They apply at the next deploy.

Needs the member role, so a deploy token or wider.

{
  "scope": "service | shared",
  "variables": "array"
}

post/api/services/{id}/sourceDeploy uploaded sourcedeploy

A .tar.gz (50 MB at most) with everything under one top folder; it builds with the app's settings, then deploys. What `wattle up` does.

Needs the member role, so a deploy token or wider.

get/api/services/{id}/buildsList an app's buildsread

Needs the viewer role, so a read token or wider.

post/api/services/{id}/buildsBuild from a source addressdeploy

Needs the member role, so a deploy token or wider.

{
  "sourceUrl": "string",
  "builder": "railpack | dockerfile",
  "rootDir": "string"
}

post/api/services/{id}/deployDeploy the branch's newest commitdeploy

Apps from GitHub.

Needs the member role, so a deploy token or wider.

post/api/services/{id}/rollbackRoll back to an earlier builddeploy

Needs the member role, so a deploy token or wider.

{
  "build": "integer"
}

get/api/builds/{id}Get a build and its logdeploy

Needs the member role, so a deploy token or wider.

post/api/services/{id}/runsRun a command once in an appdeploy

In its running container, with its variables and private network, for up to 15 minutes. What `wattle run` does.

Needs the member role, so a deploy token or wider.

{
  "command": "string"
}

get/api/services/{id}/runs/{rid}Get a command's resultdeploy

Needs the member role, so a deploy token or wider.

Observability

get/api/services/{id}/logsRead logsdeploy

Needs the member role, so a deploy token or wider.

?q: A phrase to find (any case).
?kind: http: an app's request log.
?after: Lines after this time (ISO 8601), to follow.
?before: Lines before this time, for older ones.

get/api/services/{id}/metricsRead metricsread

Needs the viewer role, so a read token or wider.

?range: How far back.

Domains

get/api/services/{id}/domainsList an app's domainsread

Needs the viewer role, so a read token or wider.

post/api/services/{id}/domainsAdd a custom domaindeploy

Needs the member role, so a deploy token or wider.

{
  "hostname": "string"
}

delete/api/domains/{id}Remove a custom domaindeploy

Needs the member role, so a deploy token or wider.

Databases

post/api/services/{id}/tunnelOpen a database tunneldeploy

A ticket for `wattle db proxy`.

Needs the member role, so a deploy token or wider.

{
  "port": "integer"
}

post/api/services/{id}/queriesRun a statementdeploy

As the read-only account, or (write: true) the owner, logged.

Needs the member role, so a deploy token or wider.

{
  "statement": "string",
  "write": "boolean"
}

get/api/services/{id}/queries/{qid}Get a statement's resultdeploy

Needs the member role, so a deploy token or wider.

post/api/services/{id}/rotateRotate a database's passwordsfull

Needs the admin role, so a full token or wider.

Backups

get/api/services/{id}/backupsList backups and exportsdeploy

Needs the member role, so a deploy token or wider.

post/api/services/{id}/backupsBack up or export nowdeploy

Needs the member role, so a deploy token or wider.

{
  "export": "boolean"
}

post/api/services/{id}/restoreRestorefull

{ into: "new", name?, base? | at? } makes a copy; { into: "this", confirm } replaces it, backing it up first.

Needs the admin role, so a full token or wider.

{
  "into": "new | this",
  "name": "string",
  "confirm": "string",
  "base": "string",
  "at": "integer"
}

get/api/services/{id}/exports/{name}Download an exportdeploy

Needs the member role, so a deploy token or wider.

Workspace

get/api/billingPlan and what it includesread

Needs the viewer role, so a read token or wider.

get/api/workspace/webhooksList webhooksfull

Needs the admin role, so a full token or wider.

post/api/workspace/webhooksAdd a webhookfull

Needs the admin role, so a full token or wider.

{
  "kind": "discord | slack | http",
  "url": "string",
  "events": "array"
}

post/api/workspace/webhooks/{id}Send a test deliveryfull

Needs the admin role, so a full token or wider.

delete/api/workspace/webhooks/{id}Remove a webhookfull

Needs the admin role, so a full token or wider.