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, including the ones AI assistants received when they signed in, 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.
  • Only specific Odoo services: the token reaches only these Odoos and their copies. It can't create new Odoos.
  • 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 every plan from Starter up. 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"

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)