Skip to content

Documentation / API

API

Integrate with calmo.cloud using the REST API.

calmo.cloud provides a REST API that lets you manage your team's servers and Odoo services programmatically. The API authenticates requests with bearer tokens.

To let an AI assistant such as Claude or ChatGPT work with calmo.cloud, connect it to the MCP server instead. It offers the same capabilities as tools the assistant can call.

Interactive documentation #

The full API reference with all endpoints, request parameters, and response schemas is available as interactive OpenAPI documentation:

Open API Reference Browse all endpoints, try requests, and view response schemas.

You can also download the OpenAPI specification as JSON at /docs/api.json to import into tools like Postman or Insomnia.

Authentication #

Include your API token in the Authorization header of every request:

Authorization: Bearer your-api-token

API tokens are created on the API Tokens page, in the Developer section of the panel menu. Owners and admins of a team can open it. A token belongs to the team, not to the person who created it: it keeps working after that person leaves the team, and unless you limit it, it can do everything the team can. The page lists every token of your team and revokes them.

Limiting what a token can do #

When you create a token you choose what it may do. Click Edit access next to a token to change it later; the token itself stays the same, and the change applies to its next request.

  • Expires on: the token stops working at the end of that day. Leave it empty for a token that never expires.
  • Accepted by: the REST API and command line, the MCP server for AI assistants, or both.
  • Permissions: Full access, or only the permissions you select — for example Read Odoo services for a status dashboard, or Start, stop and redeploy Odoo services for a deployment pipeline. Permissions to change something include reading it. Downloading and restoring backups are permissions of their own, because a backup holds the whole database. So is reading the emails a copy's mail catcher kept, because they can hold password reset links into the copy, and so is Install, upgrade and uninstall Odoo modules: changing modules stops the Odoo while Odoo works, and uninstalling one deletes its data. Creating a new repository on GitHub needs Manage repositories, also when the repository is added to an Odoo straight away. Adding modules from the Odoo App Store or a ZIP to a repository of an Odoo, in early access, needs Manage repositories and Manage Odoo services.
  • Only specific Odoo services: the token reaches only these Odoos and their copies. It can't create new Odoos, and it can't add modules to a repository branch that Odoos outside its limit deploy from, since they would receive those modules as an update.
  • Only specific servers: the token reaches only these servers. It can't create new servers. Which Odoos it reaches is set separately.

A request the token isn't allowed to make is answered with 403 Forbidden and a message naming what is missing, for example "This API token does not have the services:operate scope." Lists only contain the Odoos and servers the token reaches.

Tokens created before these options existed, and the tokens the command line receives when you sign in, have full access.

Tokens are only created, changed and revoked on the API Tokens page. No token can manage tokens, its own included, through the API or the MCP server.

The API answers only teams whose plan includes it, which is the Agency plan. See Pricing and billing.

Store your API token securely. It grants access to your team's resources. If a token is compromised, revoke it immediately and create a new one.

Quick example #

curl https://calmo.cloud/api/service-odoo \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Records are named by UUID #

The API addresses records by their uuid: in URLs, and wherever a request or a response names a related record — the private_key_uuid of a server, the server_uuid of an Odoo, the backup_destination_uuid of a backup. The lists of your team's backup destinations, SSH keys and server providers return exactly these UUIDs. To a partner team of a shared Odoo, responses give no UUID of the hosting team's servers or backup destinations.

Responses still contain the older id and *_id fields, and requests still accept them — for example server_id instead of server_uuid. They are deprecated and will be removed in the next release, so move to the UUID fields; the API reference marks each deprecated field. A request that names the same record both ways is refused. Uptime monitors and caught emails have no UUID: their id stays.

Webhooks #

The API is for calls you make. For the other direction — calmo.cloud telling your system that something happened, for example that a coding agent needs a decision — create a webhook on the Webhook page under Developer. Webhooks describes what your endpoint receives, how to verify it and how to act on it through the API.

Pricing and billing AI assistants (MCP)