Panel API
Audience: developers connecting other systems to the panel: CI pipelines, chat bots, scripts, dashboards. Covers: API tokens, how to sign a request, every endpoint and the permission it needs, settings, live events, and a ready-to-use client.
This is the API of the panel (create, change, restart, delete instances). To talk to the Odoo inside an instance, see API and webhooks.
It is the panel's only API: the panel's own web app uses it too (the internal API of earlier versions is removed). Two kinds of callers are accepted, with the same checks:
| Caller | Authentication |
|---|---|
| Another system (CI, bot, script) | An API token and a signature on every request (1, 2) |
| The panel's web app in a browser | The session cookie set by POST /api/v1/session, plus X-CSRF-Token on every change |
Every endpoint needs a permission (for example instances.create). A person's role gives a set of permissions (Security: roles); an API token acts as a role: a write token as an Administrator, a read token as a Viewer, an instances token as a Connected app (the instances scope).
Contents
- Getting a token
- Signing a request
- Endpoints
- Examples
- Errors
- Security notes
- Settings
- Live events
- Metrics
- Signing in from a web app
- Limits
1. Getting a token
Someone with the permission tokens.manage (super admins and administrators) creates tokens in the panel: API tokens in the sidebar, then Create token, with a name saying what will use it and a scope:
| Scope | Acts as | Allows |
|---|---|---|
read | Viewer | Read instances, their figures, activity and logs, jobs and versions. Every change is refused with 403. |
instances | Connected app | For connected apps such as the Odoo module: list, create, start, pause, restart, back up, extend and delete instances; nothing else (below). |
write | Administrator | Everything an Administrator may do: create, change, run actions on and delete instances, read Odoo passwords, manage accounts, tokens, backups and deploy keys. Not the panel's settings. |
The panel shows two values once: the token (sudoo_...) and the signing secret. Store both where the other system keeps secrets. A token can be revoked at any time on the same page; it stops working at once.
On the server, a token can also be created from the command line:
docker exec sudoo-panel sudoo.sh create-token "CI pipeline" writeThe instances scope
An instances token is the least a connected app (such as the Sudoo.sh apps for Odoo, source at Sudoo-sh/sudoo-odoo) needs. It acts as the role Connected app, which only a token can have, with the permissions instances.view, instances.create, instances.update, instances.operate and instances.delete, and it may call these endpoints and nothing else:
| Call | What it may do |
|---|---|
GET /versions | The Odoo versions |
GET /instances, GET /instances/<name> | List and read instances |
GET /instance-quota | How many instances it may still create |
POST /instances | Create an instance; from_backup is refused with 403 |
POST /instances/<name>/actions/<action> | Only start, pause, restart and backup; every other action (update, upgrade, switch-branch, restore, rollback, repair, ...) is refused with 403 |
PATCH /instances/<name> | Only delete_after_days, and only to make the lifetime end later (not 0, "keep", unless the instance is kept already); anything else is refused with 403 |
DELETE /instances/<name> | Delete an instance after a backup; without_backup is refused with 403 |
GET /jobs/<id> | Follow a job it started (without its technical log) |
Every other call is refused with 403 and written to the audit log, among them Odoo passwords (/instances/<name>/credentials), logs, restores, backups, GitHub, accounts, tokens, settings, plugins, metrics and the live event stream (follow jobs with GET /jobs/<id> instead).
2. Signing a request
Every request carries four headers, and a fifth when it is made on someone's behalf:
| Header | Value |
|---|---|
Authorization | Bearer <token> |
X-Sudoo-Timestamp | the current time, Unix seconds, for example 1794430123 |
X-Sudoo-Nonce | 16 to 64 random letters, digits, - or _; new for every request |
X-Sudoo-Signature | sha256= and the hex HMAC-SHA256 of the text below, with the signing secret as the key |
X-Sudoo-Acting-For | optional: the person in the calling system on whose behalf the call is made, 1 to 120 letters, digits, ., _, @, + or - (below) |
The signed text is five lines joined with \n (no newline at the end), and six with X-Sudoo-Acting-For:
<X-Sudoo-Timestamp>
<X-Sudoo-Nonce>
<METHOD in capitals>
<path, with ?query if there is one>
<hex SHA-256 of the exact request body; of an empty body when there is none>
<X-Sudoo-Acting-For, exactly as sent; only when the header is sent>For example, GET /api/v1/instances at 1794430123 with nonce p4Xq9mW2...:
1794430123
p4Xq9mW2...
GET
/api/v1/instances
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855Requests with a body send it as JSON (Content-Type: application/json) and sign the exact bytes sent.
Acting for someone
A connected app used by many people (the Odoo module, a chat bot) can say who asked for a call with X-Sudoo-Acting-For, for example X-Sudoo-Acting-For: [email protected]. The value is signed as the sixth line, so it cannot be added, removed or changed on the way: a request whose signature does not cover it exactly is refused with 401. A value that is empty, longer than 120 characters or has other characters is refused with 400.
The call is then made as api:<token name> for <person> instead of api:<token name>:
- in the audit log;
- as
created_byof the instances it creates; - in the instance limits:
MAX_INSTANCES_PER_USERandCREATE_COOLDOWN_MINUTEScount per person,MAX_INSTANCESfor the whole server still applies. Requests per minute are still counted per token.
The panel trusts the token holder to name the person truthfully: the header records who asked, it gives no rights of its own. Without the header, nothing changes: the five-line text, and the caller is api:<token name>.
POST /api/v1/instances (token "Odoo module", X-Sudoo-Acting-For: [email protected])
1794430123
p4Xq9mW2...
POST
/api/v1/instances
<hex SHA-256 of the body>
[email protected]
-> 202; the instance's created_by is "api:Odoo module for [email protected]"What each part protects against:
| Part | Stops |
|---|---|
| Token | Unknown callers. Revoking it ends access at once. |
| Signature over method, path and body | A request being changed on the way, and anyone who only has the token (from a log, a proxy, a screenshot) |
| Timestamp (within 5 minutes) | Old requests being sent again later |
| Nonce (each one accepted once) | The same request being sent twice within those 5 minutes |
| Acting-for line (when sent) | Someone adding, removing or changing the person a call is made for |
3. Endpoints
All paths start with /api/v1, and every answer follows the same conventions:
| Convention | Detail |
|---|---|
| Success | {"data": <resource or list>}, and "meta" for lists |
| Background work | 202 Accepted, the job in data, and a Location header pointing to it (/api/v1/jobs/<id>) |
| Errors | RFC 9457 problem details, Content-Type: application/problem+json (see Errors) |
| Times | ISO 8601 in UTC: 2026-11-12T08:30:00Z |
| Request id | Every answer has X-Request-ID; send your own (8 to 64 letters, digits, -, _, .) to find a call in both logs |
| Links | Each resource has links.self, the path to read it again |
| Secrets | Never in a resource: no Odoo passwords, no master password, no ports. They are only in GET /instances/<name>/credentials (permission instances.credentials) |
The Permission column names what the caller needs. Without it the answer is 403, and detail says what the role is missing. "public" means no sign-in; "signed in" means any account or token.
Instances, jobs and versions
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /instances?limit=100&offset=0 | instances.view | 200, a list of instances (those being created too, status creating); meta: total, count, limit (1 to 500), offset | |
GET /instances/<name> | instances.view | 200, the instance with disk, recent_commits, submodules, backups, restorable_backup and recent_jobs (below); also while it is being created (status creating) | |
GET /instances/<name>/credentials | instances.credentials | 200, Odoo login, admin_password, master_password, ports; written to the audit log | |
GET /instances/<name>/logs?lines=300 | instances.logs | 200, {"text"}: the end of Odoo's log (1 to 5000 lines) | |
POST /instances | instances.create | as below | 202, the job; Content-Location names the new instance |
PATCH /instances/<name> | instances.operate; also instances.delete for a delete_after_days that ends the lifetime sooner (403 otherwise) | any of auto_update, auto_upgrade, auto_pause (true or false), delete_after_days (0 keeps it), stage (Stages) | 200, the instance |
POST /instances/<name>/actions/<action> | depends on the action (below) | {}, or the action's fields | 202, the job |
DELETE /instances/<name> | instances.delete; with without_backup also backups.manage | {"confirm": "<name>"} (a production instance also "confirm_stage": "production"), and "without_backup": true to delete even when the backup fails (audit-logged) | 202, the job; a backup is taken first, and without without_backup a failed backup stops the deletion |
GET /instance-plan?repo=&branch=&name=&version=&edition=&stage= | instances.create | 200, the name and database a new instance would get, the defaults of stage (development when not given) and of every stage (stage_defaults), and production: limit, instances, refusal (why one more production instance is refused, or null); without repo and name, a name for plain Odoo with a random part (odoo-19-0-community-3f9a), new on each call | |
GET /instance-quota | instances.view | 200, how many instances the caller may still create, and when (Limits) | |
GET /jobs?instance=&limit=30&offset=0 | instances.view | 200, recent jobs, newest first | |
GET /jobs/<id> | instances.view | 200, the job; ?include=log adds its technical log when the caller also has instances.logs | |
GET /jobs/<id>/log?offset=0 | instances.logs | 200, {"text"} from that line on; meta.next_offset is where to continue | |
GET /versions | instances.view | 200, [{"version": "19.0", "enterprise": true}, ...] |
Server, metrics and settings
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /server | instances.view | 200, the panel's version and address, the plugins in use, the server's figures, the number of live-event clients | |
POST /server/restart | settings.manage | {} | 202 {"restarting": true}: the backend stops and Docker starts it again within seconds; the web app, the connectors and the instances keep running. 409 while jobs run |
GET /metrics | instances.view | 200, the latest figures of the server and every instance, and the capacity estimate (Metrics) | |
GET /server/capacity | instances.view | 200, how many instances the server can run at once, how many run, the panel's own use, disk headroom (Capacity); 503 before the first measurement | |
GET /metrics/history?minutes=60 | instances.view | 200, up to one hour of figures, in columns | |
GET /instances/<name>/metrics?minutes=60 | instances.view | 200, one instance's latest figures and history | |
GET /settings | settings.manage | 200, every setting (Settings) | |
PATCH /settings | settings.manage | {"idle_hours": 4} | 200, the settings |
DELETE /settings/<key> | settings.manage | 204, back to the .env value | |
POST /settings/test-email | settings.manage | {"to": "[email protected]"} | 200 {"sent_to"}; 400 when e-mail is not set up, 502 with the mail server's answer when sending fails |
GET /alerts?limit=50 | audit.view | 200, the newest alerts first (1 to 200; the bell of the web app), see below | |
POST /alerts/test | settings.manage | {"channel": "email"} or {"channel": "webhook", "webhook": 1} | 200 {"alert", "sent_to"} or {"alert", "webhook", "status"}, sent with the saved settings; 400 when there is nothing to send to (e-mail not set up, no recipient, the webhook has no address), 502 when the delivery failed, with the reason |
GET /events | signed in | the live event stream (Live events) |
An alert, as GET /alerts lists it and the alert live event carries it (Admin guide, Alerts):
{"id": "3f9c2a1b7d4e", "key": "instance_down:shop-main", "type": "instance_down", "severity": "problem",
"title": "shop-main is down", "text": "Instance shop-main is stopped, for 5 minutes now. ...", "hint": null,
"details": [], "instance": "shop-main", "link": "/i/shop-main", "at": 1763366400.0, "last_at": 1763366400.0,
"count": 1, "resolved_at": null, "delivery": ["e-mailed to 2 of 2 addresses", "webhook 1: delivered (HTTP 200)"]}type: job_failed, update_failed, backup_failed, instance_down, disk, memory, drift, public_link, test. severity: problem, recovered or info. count grows when the same alert repeats inside ALERT_QUIET_MINUTES (it is not sent again); last_at is its latest time and the list's order. link is a path of the web app. resolved_at is set when the problem is over. Webhooks are named by number, never by address.
Accounts, roles and the audit log
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /roles | signed in | 200, {"roles": [{"name", "label", "description", "permissions"}], "permissions": {"<name>": "<what it allows>"}} | |
GET /users | accounts.manage | 200, accounts (below) | |
POST /users | accounts.manage | {"email", "role"} required; optional first_name, last_name, phone, name (made from the e-mail address when absent), password (generated when absent), must_change_password (default true) | 201, the account with its password, shown once |
PATCH /users/<name> | accounts.manage | any of role, first_name, last_name, email, phone ("" clears one); also for your own account | 200, the account; a new role ends its sessions |
POST /users/<name>/password | accounts.manage | {} to generate one, or {"password", "must_change_password"} | 200, {"password"}, shown once; the account's sessions end |
DELETE /users/<name>/second-factors | accounts.manage | 204: removes the account's second factors (a lost phone) and signs it out | |
DELETE /users/<name> | accounts.manage | 204 | |
GET /audit?limit=200&user=&instance= | audit.view | 200, the latest audit-log entries, newest first (limit 1 to 2000) |
role is one of super_admin, admin, maintainer, developer, viewer. Only a super admin creates, changes, resets or deletes super admins (403 otherwise).
| Rule | Answer when broken |
|---|---|
email is required for a new account | 400 "Enter the person's e-mail address: they sign in with it." |
| No two accounts share an e-mail address (compared without case) | 400 "Another account already uses this e-mail address." |
A typed password follows the password rules | 400, detail names the rule, for example "The password contains a sequence such as 12345 or qwerty. Choose another one." |
| The last super admin stays a super admin and cannot be deleted | 400 "The last super admin must stay a super admin." or "The last super admin cannot be deleted." |
| Nobody deletes their own account or sets their own password here | 400; use PUT /session/password for your own password |
PATCH /users/<name> works on your own account too, including your role; a new role ends your sessions as well, so you sign in again. name is the account's user name: 3 to 32 lower-case letters, digits, dots, dashes and underscores, starting with a letter. When it is left out, it is made from the e-mail address ([email protected] gives jane.doe, then jane.doe-2 when that is taken).
The password: without password one is generated and must_change_password is always true. With a typed password, must_change_password: false lets the owner keep it. While must_change_password is true the owner's session is restricted until they choose their own (10).
POST /api/v1/users {"email": "[email protected]", "role": "maintainer", "first_name": "Sam", "last_name": "Lee"}
-> 201 {"data": {"name": "sam", "email": "[email protected]", "must_change_password": true, ...,
"password": "generated-and-shown-once"}}
POST /api/v1/users/sam/password {"password": "green tea at 7 on the balcony", "must_change_password": false}
-> 200 {"data": {"password": "green tea at 7 on the balcony"}}An account:
{
"name": "sam", "display_name": "Sam Lee",
"first_name": "Sam", "last_name": "Lee", "email": "[email protected]", "phone": null,
"role": "maintainer", "role_label": "Maintainer",
"last_sign_in_at": "2026-11-12T08:01:10Z", "password_changed_at": "2026-11-01T09:12:44Z",
"must_change_password": false, "second_factors": ["totp"],
"links": {"self": "/api/v1/users/sam"}
}API tokens, backups and GitHub
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /tokens | tokens.manage | 200, API tokens (never their secrets) | |
POST /tokens | tokens.manage | {"name", "scope"} (read, instances or write) | 201, with token and signing_secret, shown once |
DELETE /tokens/<id> | tokens.manage | 204, revoked | |
GET /backups | backups.manage | 200, backups, newest first (below) | |
GET /backups/<file> | backups.manage | the zip (dump.sql, the filestore, manifest.json) | |
DELETE /backups/<file> | backups.manage | 204 | |
GET /deploy-keys | github.manage | 200, deploy keys | |
POST /deploy-keys | github.manage | {"repo"} | 201, the public key and the GitHub page to add it on |
DELETE /deploy-keys/<owner>/<repo> | github.manage | 204 | |
GET /repositories/branches?url= | instances.view | 200, {"branches", "default"}; through the GitHub App's API when it covers the repository; 400 with what keeps the server from the repository (below) | |
GET /repositories/access?url=&branch= | instances.view | 200, whether the server can read the repository and each submodule, and how (via: deploy-key, github-app or public); a line that cannot be read has problem and, when the GitHub App explains it, fix (below); meta.can_manage_keys, meta.github_app | |
GET /github/app | github.manage | 200, {"connected", "app", "trigger_running", "expected_hook_url", "deploy_keys"}; meta.can_manage (below). The installations are read from GitHub first when the last reading is more than a minute old | |
POST /github/app/manifest | settings.manage | {"organization"} (empty: the personal account) | 200, {"action", "manifest", "state"}: post manifest as a form field to action from the browser; the state is kept in the session for one hour |
POST /github/app | settings.manage | {"code", "state"} from GitHub's redirect to /github/app/created | 201, the app; 400 when the state does not match the session's or the code expired |
DELETE /github/app | settings.manage | 200, {"settings_url", "installations"}: GitHub pages to uninstall and delete the app; the panel forgets its credentials | |
POST /github/app/installations | settings.manage | {"installation_id"} from GitHub's redirect to /github/app/installed | 201, the installation, after GitHub confirms it belongs to the app |
POST /github/app/installations/sync | settings.manage | 200, the installations as GitHub lists them now | |
DELETE /github/app/installations/<id> | settings.manage | 204, forgotten by the panel (uninstall it on GitHub too) | |
GET /github/repositories?q= | instances.create | 200, repositories readable through the app, newest push first, filtered by words of q (at most 200); meta.connected, and meta.installations ([{"account", "settings_url"}]: where to choose on GitHub which repositories the app may read) |
The GitHub App in GET /github/app (app is null while none is connected; secrets are never returned):
{"id": 123456, "slug": "sudoo-sh-panel-3f9a", "name": "Sudoo.sh panel-3f9a", "client_id": "Iv23li...",
"owner": {"login": "acme", "type": "Organization"}, "created": 1794441612,
"hook_url": "https://panel.example.com/hooks/github-app",
"settings_url": "https://github.com/organizations/acme/settings/apps/sudoo-sh-panel-3f9a",
"install_url": "https://github.com/apps/sudoo-sh-panel-3f9a/installations/new",
"installations": [{"id": 777, "account": "acme", "account_type": "Organization", "repository_selection": "all",
"settings_url": "https://github.com/organizations/acme/settings/installations/777",
"suspended": false, "added": 1794441700}]}Both repository checks also read the app's installations from GitHub when the last reading is more than a minute old, so installations made on GitHub itself count at once. When a repository cannot be read and an app is connected, problem (and the 400's detail) says what applies, and the access report's line carries fix:
{"url": "https://github.com/acme/erp", "role": "main", "ok": false,
"problem": "The GitHub App is not installed on acme. Install it there and give it this repository.",
"fix": {"reason": "not_installed", "url": "https://github.com/apps/sudoo-sh-panel-3f9a/installations/new",
"label": "Install on acme"}}reason is app_owned_elsewhere (the app is private and belongs to another account, so it can never be installed on the repository's owner; url is the panel's /github), not_installed, suspended, not_selected (installed, but the repository is not among the selected ones; url is the installation's settings on GitHub) or not_found (url and label empty). Without an app, fix is null and problem advises a deploy key.
A repository in GET /github/repositories:
{"full_name": "acme/sales", "url": "https://github.com/acme/sales", "private": true, "default_branch": "main",
"description": "Sales customisations", "pushed_at": "2026-11-12T08:30:00Z", "account": "acme"}When GitHub refuses or cannot be reached, these endpoints answer 502 with GitHub's message (never 401, which would mean the caller's own session ended).
A backup in GET /backups (created in Unix seconds, size in bytes):
{"file": "sales-main__sales_main__20261112-000012__daily.zip", "instance": "sales-main", "db": "sales_main",
"stamp": "20261112-000012", "kind": "daily", "size": 48213504, "created": 1794441612.4,
"version": "19.0", "series": "19.0", "edition": "community"}version and edition come from the backup's manifest.json (null when it does not say; backups of earlier versions of Sudoo.sh have no edition). series is the Odoo release the database belongs to ("17.1" for saas~17.1): a backup only goes into an instance of the same series, and an Enterprise backup only into an Enterprise instance.
kind is one of:
kind | Taken | Kept |
|---|---|---|
manual | The backup action (Back up now); also every file of earlier versions, which have no kind in their name | Until deleted |
daily | Once a day for each instance used since its last daily backup | Only the latest per instance; removed with the instance |
deletion | Before an instance is deleted | Until deleted |
before-restore | At the start of a restore action | Only the latest per instance, for ROLLBACK_HOURS; removed with the instance |
before-rollback | At the start of a rollback action | Only the latest per instance, for ROLLBACK_HOURS; removed with the instance |
before-repair | Before the panel recreates a database container that was changed outside the panel (repair) | Only the latest per instance; removed with the instance |
before-update | Before an update or update-submodules job (also an automatic one) changes the code, when SAFE_UPDATES is on; for a paused instance only when modules will be upgraded | Only the latest per instance (one kept for a restore by hand when an automatic rollback failed); removed with the instance |
To restore a backup into an instance (its own, or another instance's), use the restore action; to start a new instance from one, from_backup of POST /instances (below).
Plugins and the marketplace
What the Plugins page uses (Marketplace). The panel talks to the hub itself, with its own signed requests; callers of these endpoints never need a hub account or key. When the hub cannot be reached, the /marketplace/... endpoints answer 503 with a sentence saying so, and the /plugins endpoints keep working. A hub refusal is passed on as 409 (404 for something that does not exist) with the hub's reason in plain words, for example that the panel must be linked first. With MARKETPLACE=off the /marketplace/... endpoints and installing answer 409.
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /plugins | plugins.view | 200, the installed plugins: id, name, version, tier, publisher, permissions, requires, enabled, status (active, disabled, modified, blocked, switched_off, unlicensed), loaded, restart_pending, licence (state, standing, expires_at, grace_until, phase: active, expiring, grace, ended, no_lease, unlicensed; null for free plugins), latest_version, update_available; meta.restart_pending | |
GET /plugins/notices | plugins.view | 200, banners: [{"plugin", "kind", "level", "text", "date"}] for licences ending, in grace or ended, changed files, and the hub refusing the panel | |
POST /plugins | settings.manage | {"id": "com.sudoo.smtp", "version": "1.2.0"} (version optional: the newest) | 202, the job (kind plugin-install); the backend restarts when it has finished. 409 while jobs run or when that version is installed |
POST /plugins/<id>/update | settings.manage | {} | 202, the job installing the newest version |
POST /plugins/<id>/disable | settings.manage | {} | 200, the plugin; the backend restarts without it. 409 when another installed plugin needs it |
POST /plugins/<id>/enable | settings.manage | {} | 200, the plugin; the backend restarts with it. 409 when its files were changed |
DELETE /plugins/<id> | settings.manage | {"confirm": "<id>"} | 202, the job: backs up the panel's data, removes the plugin, restarts |
GET /marketplace | plugins.view | 200, the connection: enabled, hub_url, installation_id, registered, hub_keys (accepted key ids), reachable, error, error_code (unreachable, unverified for an answer that was not signed by an accepted key, or the hub's code), hub_status, flags (fingerprint_mismatch), linked (account_name), key_revoked_at, removing_paid_plugins, last_heartbeat_at, next_heartbeat_at, lease_expires_at, lease_valid, lease_ending_soon | |
POST /marketplace/link | settings.manage | {"code": "<one-time code from app.sudoo.sh>"} | 200, {"account_name", "linked_at"}; 404 for a wrong or used code; 409 when the account already has a server or this server belongs to another account |
POST /marketplace/unlink | settings.manage | {"confirm": true} | Log out of the account: the hub revokes this server's paid licences and the panel removes its paid plugins after a backup (a job, plugin-remove-paid). The panel, free plugins and instances keep running. 200, the connection |
POST /marketplace/heartbeat | settings.manage | {} | 200, the connection after a heartbeat sent now |
GET /marketplace/catalog?q=&type=&tier=&installed=&sort=&limit=50&offset=0 | plugins.view | 200, the hub's catalogue for this panel (tier: free or paid; installed: true or false; sort: popular, rating, newest, name, trusted). Each plugin has publisher (verified, official), icon_url (the panel's own address for the icon, or null), countries, languages, odoo_versions, local, plans (cheapest first: id, kind monthly, yearly, fixed_term or one_time, price_cents, currency, period_days, interval, perpetual, monthly_equivalent_cents, savings_percent), latest_version, compatible_version (the newest that runs on this panel), installed_version, license and action: install, update, installed, buy, renew (a licence that ended) or incompatible | |
GET /marketplace/catalog/<id> | plugins.view | 200, the plugin's page: permissions, screenshots, plans, installed_version. The panel tells the hub the page was shown (a recommendation signal, kept only with the account owner's consent) | |
GET /marketplace/recommendations?limit=8 | plugins.view | 200, [{"plugin", "score", "reasons"}]: plugins the hub suggests for this server, each with up to three reasons ("Because you use Sample mailer") | |
GET /marketplace/icons/<id>?v= | plugins.view | 200, the plugin's icon (PNG or SVG), fetched from the hub with a signed request; 404 when it has none | |
GET /marketplace/categories | plugins.view | 200, [{"type", "count"}] | |
GET /marketplace/billing | plugins.view | 200, whether a checkout session can be opened now: payments_enabled, linked, account_name, can_buy, reason (payments_disabled, link_required, fingerprint_mismatch), currency, manage_url (app.sudoo.sh, Servers) | |
POST /marketplace/checkout-sessions | settings.manage | {"plugin_id", "plan_id", "idempotency_key"} | Asks to buy for this server; the panel never charges anything. The caller's name and e-mail go with the request (shown on the checkout page and the receipt). idempotency_key (16 to 64 of A-Za-z0-9_-) is new for each press of Buy and the same when that request is retried: the hub answers the same session. 201 + Location, the session: id, status (open, processing, checkout_required, succeeded, expired, cancelled, failed), url (https://app.sudoo.sh/checkout/...: open it in a new tab, where the account owner pays), expires_at, plugin_id, plugin_name, plan, amount_cents, currency, method, reason (why the last payment failed), receipt_number, requested_by, created_at, completed_at. 409 for already_licensed, purchase_in_progress, idempotency_key_reused ...; 503 when payments are off |
GET /marketplace/checkout-sessions/<id> | settings.manage | 200, the session; poll it every few seconds while open, processing or checkout_required (a declined card leaves it open with a reason); on succeeded install with POST /plugins; on expired, cancelled or failed start again with a new key | |
GET /marketplace/checkout-sessions | plugins.view | 200, the sessions opened from this server, newest first (the same objects); ?format=csv answers a CSV file | |
GET /marketplace/receipts | plugins.view | 200, receipts and credit notes of this server's plugins: number, kind (receipt or credit_note), issued_at, plugin_name, plan_kind, payment_kind (purchase or renewal), total_cents, currency, requested_by_name; ?format=csv answers a CSV file |
No endpoint returns a plugin's files or its package.
Documentation
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /docs | instances.view | 200, {"index", "sections": [{"title", "pages": [{"path", "title"}]}]}: the table of contents | |
GET /docs/<path> | instances.view | 200, {"path", "title", "html", "headings": [{"level", "id", "text"}]}, for example GET /docs/docs/PANEL_API.md |
These are the same Markdown files as in the repository's docs/, rendered on the server. Links between pages point to /help/<path>, the web app's Help pages.
First run, session and own account (the web app)
| Method and path | Permission | Body | Answer |
|---|---|---|---|
GET /setup | public | 200, {"needed", "contact"}: whether the panel still has no account | |
POST /setup | public | {"setup_code", "password", "first_name", "email"} required; last_name, phone, username optional (made from email when absent) | 201, signed in as the first account, a super admin (10) |
GET /contact | public | 200, who to contact | |
POST /session | public | {"username", "password"}; username is the e-mail address (up to 254 characters) or the user name | 201, the session (as GET /session); sets the session cookie. Or 200 with second_factor when a code is needed. 401 "Wrong e-mail address or password." |
POST /session/second-factor | public | {"method", "code"} | 201, signed in |
POST /session/second-factor/<method> | public | {} | 200, a new code was sent (email) |
GET /session | signed in | 200, the signed-in account (below) | |
DELETE /session | signed in | 204, signed out; the session ends on the server too, so a copy of its cookie stops working | |
PUT /session/password | signed in | {"current", "new"} | 204; other sessions of the account end, and a password restriction is lifted |
GET /account | signed in | 200, own account: profile, role, second factors, whether one is required | |
PATCH /account | signed in | any of first_name, last_name, email, phone | 200, the account. The e-mail address cannot change while it receives sign-in codes. An address another account uses is refused: 400 "Another account already uses this e-mail address." A new address ends the account's other sessions |
POST /account/second-factors/<name> | signed in | email: {"email"}; totp: {}. To replace a factor that is already set up, add "password" | 200: a code was sent, or {"secret", "otpauth_uri"} for the app. 400 when the password is missing or wrong, or the e-mail address belongs to another account |
PUT /account/second-factors/<name> | signed in | {"code"} | 200, the factors; it is set up. Replacing a factor, or a new e-mail address, ends the account's other sessions |
DELETE /account/second-factors/<name> | signed in | {"password"} | 204; the account's other sessions end |
GET /session:
{
"data": {
"user": "sam", "display_name": "Sam Lee",
"first_name": "Sam", "last_name": "Lee", "email": "[email protected]", "phone": null,
"role": "maintainer", "role_label": "Maintainer",
"permissions": ["github.manage", "instances.create", "instances.credentials", "instances.logs", "..."],
"csrf_token": "...",
"restricted": null,
"must_set_up_second_factor": false,
"brand_color": "#714B67"
}
}permissions is what the web app uses to show or hide buttons; the server checks again on every call. restricted is "password" (choose your own password first), "second_factor" (set one up first) or null. While it is set, only /session, /account and /contact answer; every other call is refused with 403.
Instances, jobs and actions in detail
An instance:
{
"data": {
"name": "sales-main",
"status": "online",
"stage": "development",
"url": "https://river-stone-apple.trycloudflare.com",
"odoo": {"version": "19.0", "edition": "enterprise", "database": "sales_main"},
"source": "repository",
"git": {
"repository": "https://github.com/acme-co/sales",
"branch": "main",
"branch_deleted_on_github": false,
"commit": {"sha": "4f2a9c1", "subject": "Add delivery report", "author": "Sam", "age": "2 hours ago"}
},
"settings": {"auto_update": true, "auto_upgrade": true, "auto_pause": true, "delete_after_days": 30},
"usage": {
"cpu_percent": 3.2, "memory_bytes": 905969664, "memory_limit_bytes": 3011510272, "memory_percent": 30.1,
"requests_per_minute": 42.0, "error_rate_percent": 0.0, "response_ms_avg": 38.5, "response_ms_p95": 120.4,
"uptime_seconds": 7260, "disk_bytes": 412090368
},
"created_at": "2026-11-11T10:16:47Z",
"last_visit_at": "2026-11-12T08:01:10Z",
"pauses_at": "2026-11-12T14:01:10Z",
"expires_at": "2026-12-11T10:16:47Z",
"current_job": null,
"links": {"self": "/api/v1/instances/sales-main"}
}
}GET /instances/<name> adds, among others, the instance's backups, newest first, and the one the restore action would use without a file (null when there is none):
"backups": [
{"file": "sales-main__sales_main__20261112-000012__daily.zip", "kind": "daily", "database": "sales_main",
"size_bytes": 48213504, "created_at": "2026-11-12T00:00:12Z"},
{"file": "sales-main__sales_main__20261110-153001__manual.zip", "kind": "manual", "database": "sales_main",
"size_bytes": 47120384, "created_at": "2026-11-10T15:30:01Z"}
],
"restorable_backup": "sales-main__sales_main__20261112-000012__daily.zip",
"rollback": {"backups": ["sales-main__sales_main__20261112-101500__before-restore.zip"],
"taken_at": "2026-11-12T10:15:00Z", "until": "2026-11-13T10:15:00Z"}rollback is null unless the instance was restored in the last ROLLBACK_HOURS (and not rolled back since): then it names the before-restore backup(s) the rollback action puts back, and until when it is offered.
Every instance also has update_failure: null, or, when its last code update failed (and no update has worked since), what happened:
"update_failure": {"message": "The update to 9b1e0c4 failed at upgrading modules; the instance was put back to 4f2a9c1. One of the modules has an error in its XML files (views or data). ...",
"failed_at": "2026-11-12T10:20:31Z", "rolled_back": true, "job": "/api/v1/jobs/7d0e5f2a9b13"}rolled_back is false when putting the instance back failed too; message then names the before-update backup to restore by hand.
status is one of creating, online, starting, busy (a job is running), paused, switched_off, stopped, unknown. stage is production, staging or development (Stages).
creating: the instance's creation is queued or running. The instance answers (and is listed) from the moment POST /instances is accepted, before any of its files exist: then it shows what the creation was asked for (version, edition, database, repository and branch, settings) and null or empty for everything else. current_job is the creation job with its steps so far (status queued while it waits for another job on the same name, then running); follow it with GET /jobs/<id> or the live job events. Actions, settings, credentials and logs answer 409 until the creation has finished. When the creation fails, what it made is removed: GET /instances/<name> answers 404 again (a live instance.deleted event is sent) and the job, with its error, stays under /jobs.
"status": "creating",
"current_job": {"id": "b7e0c2a41f93", "action": "Create instance", "status": "running", "progress_percent": 0,
"steps": [{"title": "Downloading Odoo 19.0 image", "status": "running"}],
"links": {"self": "/api/v1/jobs/b7e0c2a41f93"}}While another job runs, current_job has the same shape.
A job (the answer to every 202, and to GET /jobs/<id>):
{
"data": {
"id": "a12fff66a05d",
"instance": "sales-main",
"action": "Restart",
"status": "running",
"progress_percent": 50,
"requested_by": "api:CI pipeline",
"started_at": "2026-11-12T08:31:02Z",
"finished_at": null,
"steps": [{"title": "Restarting Odoo", "status": "running"}],
"notes": [],
"error": null,
"links": {"self": "/api/v1/jobs/a12fff66a05d", "instance": "/api/v1/instances/sales-main"}
}
}status goes from queued to running to success or failed; when it failed, error explains why in plain words. progress_percent is the share of steps done (below 100 until the job has finished), or null for jobs whose number of steps is not known in advance.
Creating an instance takes the same fields as the New instance form:
{
"repo": "https://github.com/acme-co/sales",
"branch": "main",
"version": "19.0",
"edition": "community",
"name": "",
"install_modules": true,
"demo": false,
"delete_after_days": 30,
"stage": "development",
"from_backup": "sales-main__sales_main__20261112-000012__daily.zip"
}Plain Odoo. repo is optional: without it the instance runs the official Odoo only (Community or Enterprise, any offered version), with no code from GitHub. Nothing is cloned (its add-ons folder stays empty and is not on Odoo's add-ons path), branch is ignored, auto_update and auto_upgrade are false and install_modules does nothing. Without name either, it is called odoo-<version>-<edition>-<4 random characters> (for example odoo-18-0-community-3f9a); the usual name rules apply to a given name. It shows "source": "plain" and "git": {"repository": null, "branch": null, ...}. Everything else works as for any instance (pause and start, backups, restore and rollback, lifetime, links, metrics, the integrity watchdog, upgrade of Odoo's own modules). The actions that need a repository (update, update-submodules, switch-branch, add-submodule, remove-submodule) and PATCH with auto_update or auto_upgrade set to true answer 409 with a problem detail saying it runs plain Odoo. To give it a repository later, run connect-repository (below): its database and files are kept, and from then on it works like an instance created from that repository.
{"type": "about:blank", "title": "Conflict", "status": 409,
"detail": "odoo-18-0-community-3f9a runs plain Odoo without a GitHub repository: it has no code to update, no branch and no submodules. Connect a repository to it first.",
"instance": "/api/v1/instances/odoo-18-0-community-3f9a/actions/update", "request_id": "..."}stage is optional (development by default) and decides the defaults of the fields not sent: delete_after_days (DELETE_AFTER_DAYS, STAGING_DELETE_AFTER_DAYS for staging, always 0 for production), auto_pause (never for production) and auto_update (PRODUCTION_AUTO_UPDATE for production). A production instance with delete_after_days other than 0 or "auto_pause": true answers 400; one more production instance than MAX_PRODUCTION_INSTANCES allows answers 409 with a problem detail naming those in production.
from_backup is optional: the new instance starts with that backup's database and files (loaded under the new database name) instead of an empty database. It needs instances.restore and backups.manage besides instances.create; an unknown file answers 404, a backup of another Odoo series (or an Enterprise backup for a Community instance) 400. demo is ignored then, and install_modules installs only the repository's modules the backup does not have. A backup of another instance is neutralised (no e-mail, no scheduled actions; the job's notes say so).
Actions (POST /instances/<name>/actions/<action>); each needs its own permission:
| Action | Does | Permission | Body |
|---|---|---|---|
update | Get latest code | instances.update | {} |
update-submodules | Update submodules | instances.update | {} |
restart | Restart | instances.update | {} |
start | Start a paused or switched-off instance | instances.update | {} |
add-submodule | Add a submodule | instances.update | {"url": "https://github.com/OCA/web", "path": "oca/web", "branch": "19.0"} (path and branch optional) |
pause | Pause | instances.operate | {} |
switch-off | Switch off (stays off until started) | instances.operate | {} |
upgrade | Upgrade modules | instances.operate | {"modules": "sale_custom,stock_custom"} or {"modules": "all"} |
remove-submodule | Remove a submodule | instances.operate | {"path": "oca/web"} |
switch-branch | Switch branch | instances.operate | {"branch": "main"} |
connect-repository | Give an instance of plain Odoo a GitHub repository: clone it, install its modules if asked, restart (data kept); 409 when it has one | instances.operate | {"repo": "https://github.com/acme/odoo-addons", "branch": "main", "install_modules": true} (branch defaults to main) |
backup | Back up now | instances.operate | {} |
update-images | Download the instance's Odoo and PostgreSQL images again (same names and tags), pin the new digests, recreate the containers | instances.operate | {} |
repair | Restore the panel's configuration after a change made outside the panel (also started on its own with DRIFT_ACTION=restore) | instances.operate | {} |
restore | Restore a backup: replaces the database and the filestore | instances.restore (and backups.manage for another instance's backup) | {} for the latest, or {"file": "<backup file name>"} |
rollback | Go back to the state before the last restore, while it is kept (ROLLBACK_HOURS) | instances.restore | {} |
delete | Delete, after a backup (same as DELETE /instances/<name>) | instances.delete | {"confirm": "<name>"}; production: also "confirm_stage": "production" |
By role: a Developer may run the instances.update actions, a Maintainer every action except delete, a Super admin or Administrator all of them. On a production instance, pause, switch-off, restore and rollback also need "confirm_production": true in the body, and delete needs "confirm_stage": "production" besides the name; without them the answer is 400 and nothing starts.
Stages
Every instance has a stage: production, staging or development. Instances made before stages existed are development and behave exactly as before.
| Development | Staging | Production | |
|---|---|---|---|
| Paused when idle | when auto_pause | when auto_pause | never (auto_pause: true answers 409) |
| Deleted automatically | after delete_after_days | after delete_after_days (new ones: STAGING_DELETE_AFTER_DAYS) | never (delete_after_days other than 0 answers 409) |
| Daily backup | when DAILY_BACKUPS and used since the last one | the same, and STAGING_DAILY_BACKUPS | every day, used or not, whatever DAILY_BACKUPS says |
| Safe updates | when SAFE_UPDATES | when SAFE_UPDATES | always |
| New code automatically | AUTO_UPDATE for new ones | AUTO_UPDATE for new ones | PRODUCTION_AUTO_UPDATE for new ones (off by default) |
Change it with PATCH /instances/<name> (instances.operate) and {"stage": "production"}. Moving an instance into production answers 409 when MAX_PRODUCTION_INSTANCES instances are in production already; otherwise its lifetime becomes "keep" and its automatic pause is switched off. Moving one out of production needs "confirm_production": true (400 without it); its settings stay as they are. Each change is in the audit log ("instance stage changed", with the stages before and after).
PATCH /api/v1/instances/sales-main {"stage": "staging", "confirm_production": true}
-> 200 {"data": {"name": "sales-main", "stage": "staging", ...}}restore without file puts back the newest manual, daily or deletion backup of a database the instance has (restorable_backup in GET /instances/<name>); 409 when there is none. With file, it may be any backup of the same Odoo series (series in GET /backups): one of the instance's own backups, or, with backups.manage too, another instance's (403 without it). A backup of an earlier, deleted instance with the same name is another instance's: it is not in backups, not chosen without file, needs backups.manage and is neutralised. An unknown file answers 404, a backup of another series or an Enterprise backup for a Community instance 400. The job ("action": "Restore a backup") saves the current state as a before-restore backup, stops Odoo, replaces the database and the filestore, sets the instance's public address again and starts Odoo. Another instance's backup is loaded under this instance's database name and neutralised first (Odoo's neutralize on Odoo 16 and later: mail servers, scheduled actions and integrations off; a new database identity); the job's notes say so; its administrator (user 2) then gets this instance's admin password, and GET /instances/<name>/credentials shows that administrator's login. When the backup is of a database the instance does not have, the job fails and error says so.
update and update-submodules with SAFE_UPDATES on (the default): when the update changes the code, the job first saves a before-update backup (for a paused instance only when modules will be upgraded), then pulls, upgrades and restarts. If a later step fails (a pull that cannot fast-forward, a submodule, the module upgrade, or Odoo not answering after the restart), the job puts the instance back: the previous commit of the repository and of every submodule, the before-update backup when an upgrade ran or started, then Odoo restarted and checked. The job ends failed and its error reads "The update to <sha> failed at <step>; the instance was put back to <previous sha>." followed by the explanation of the failure, when there is one; update_failure of the instance shows the same, and the audit log has an entry. An automatic update does not try a commit whose update was put back again; update does. With SAFE_UPDATES off, updates run without the backup and the rollback, except on a production instance, which is always updated this way.
rollback puts back the before-restore backup named in rollback of GET /instances/<name>; 409 when there is none (also once the instance was rolled back to it; restoring that file with restore still puts it back). It saves the current state as before-rollback first (never as before-restore, so it cannot replace what it restores). Restoring the instance's own before-restore file with restore does the same.
POST /api/v1/instances/sales-main/actions/restore {"file": "sales-main__sales_main__20261110-153001__manual.zip"}
-> 202 {"data": {"id": "c3d41e0b7a92", "action": "Restore a backup", "status": "queued", ...}}4. Examples
Python: examples/panel_api_client.py is a complete client using only the standard library. Copy it into your project:
from panel_api_client import PanelAPI
api = PanelAPI("https://panel.example.com", token="sudoo_...", signing_secret="...")
for instance in api.instances(): # follows the pages of the list
print(instance["name"], instance["status"], instance["url"])
job = api.action("sales-main", "update") # waits until the update is finished
print(job["status"], job["error"]) # success None, or failed and the reason
job = api.create(repo="https://github.com/acme-co/sales", branch="feature-x", version="19.0",
edition="community", install_modules=True, delete_after_days=7)
print(job["status"], job["instance"])A connected app with an instances token, calling for one of its users:
odoo_module = PanelAPI("https://panel.example.com", token="sudoo_...", signing_secret="...",
acting_for="[email protected]") # signed as the sixth line
job = odoo_module.create(version="19.0", edition="community", delete_after_days=7)
print(job["instance"]) # created_by: "api:<token name> for [email protected]"
odoo_module.request("PATCH", f"/api/v1/instances/{job['instance']}", {"delete_after_days": 14}) # extendShell (bash with openssl):
URL=https://panel.example.com TOKEN=sudoo_... SECRET=...
call() { # call METHOD PATH [JSON]
local body="${3:-}" ts nonce sig
ts=$(date +%s); nonce=$(openssl rand -hex 16)
sig=$(printf '%s\n%s\n%s\n%s\n%s' "$ts" "$nonce" "$1" "$2" "$(printf '%s' "$body" | sha256sum | cut -d' ' -f1)" \
| openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
curl -s -X "$1" "$URL$2" -H "Authorization: Bearer $TOKEN" -H "X-Sudoo-Timestamp: $ts" \
-H "X-Sudoo-Nonce: $nonce" -H "X-Sudoo-Signature: sha256=$sig" \
${body:+-H "Content-Type: application/json" --data "$body"}
}
call GET /api/v1/instances
call POST /api/v1/instances/sales-main/actions/restart '{}'A CI pipeline that gives every pull request its own instance: create an instance from the pull request's branch with delete_after_days: 7, post its url as a comment, and delete it when the pull request is closed.
5. Errors
Errors follow RFC 9457 ("problem details"), with Content-Type: application/problem+json:
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Choose an Odoo version from the list.",
"instance": "/api/v1/instances",
"request_id": "5f0c9a3e2b8d4e7a9c1d0b6f3e2a1c4d"
}detail says what is wrong and what to do; quote request_id when asking for help.
| Status | Meaning |
|---|---|
| 400 | A field is missing or not valid (also X-Sudoo-Acting-For); detail says which and what to send |
| 401 | Token, timestamp, nonce or signature not accepted, the session has ended, or a wrong e-mail address or password at POST /session; detail says which |
| 403 | The caller's role lacks the permission; detail names what is missing, for example "Your role cannot do this (delete instances)." A read token sending a change, an instances token calling anything outside its scope, a restricted session, a wrong setup code, and a reached instance limit (MAX_INSTANCES, MAX_INSTANCES_PER_USER, MAX_RUNNING_INSTANCES) are also 403, each with its own detail |
| 404 | No such instance, job, account, action or documentation page |
| 405 | The method is not allowed on this path |
| 409 | POST /server/restart while jobs are running |
| 415 | The body is not sent as JSON |
| 429 | Too many requests per minute, too many refused calls, wrong passwords or wrong setup codes from this address (5 in 15 minutes), or a creation within CREATE_COOLDOWN_MINUTES; Retry-After says how many seconds to wait |
| 500 | Something unexpected on the server; quote the request_id |
| 502 | POST /settings/test-email: the mail server refused the message; detail has its answer |
| 503 | An e-mail code could not be sent |
6. Security notes
- The token is stored only as a SHA-256 hash, and the signing secret encrypted with the vault key. Neither is ever shown again; a lost one means creating a new token.
- A
writetoken acts as an Administrator: it can do everything an administrator can, including deleting instances, reading Odoo passwords and managing accounts (but not the panel's settings). Areadtoken acts as a Viewer. Aninstancestoken can only list, create, start, pause, restart, back up, extend and delete instances. Give each system its own token, with thereadscope where reading is enough and theinstancesscope for a connected app such as the Odoo module, and revoke tokens that are no longer used. - Every call is in the audit log as
api:<token name>(api:<token name> for <person>withX-Sudoo-Acting-For), and every refused call with its reason and address. - Resources never contain passwords (Odoo admin, master password) or the server's ports; only
GET /instances/<name>/credentialsreturns them, to callers withinstances.credentials, and each read is in the audit log. - API tokens do not open the panel's pages. The browser's session opens the API only from the panel's own address, and every change also needs the session's CSRF token, so another website cannot use a visitor's session.
7. Settings
The settings in .env are the defaults. A super admin (permission settings.manage) can change almost all of them while the panel runs, on the Settings page or through the API; the change is kept in /opt/odoo/manager/settings.json on top of .env. Each setting says when a change takes effect, in applies:
applies | When | Which |
|---|---|---|
now | At once, without a restart | Almost every setting: limits, sessions, e-mail, daily backups (daily_backups, daily_backup_time, timezone), Odoo images and versions, Enterprise paths, contact, accent colour (marked live in Configuration) |
restart | After the panel restarts (POST /api/v1/server/restart, or Restart the panel on the Settings page) | The settings that choose plugins: mailer, second_factors, update_triggers, enterprise_source, auth, rate_limiter |
env | Only in .env; the API refuses a change with 400 | Folders, ports, exposure, storage |
GET /api/v1/settings
{
"data": [
{
"key": "idle_hours", "env": "IDLE_HOURS",
"value": 4, "env_value": 6, "changed_in_panel": true,
"editable": true, "applies": "now", "pending_restart": false,
"secret": false, "type": "number", "minimum": 0,
"description": "Pause an instance after this many hours without visits; 0: never."
},
...
]
}pending_restart is true for a restart setting whose new value is not in use yet. editable is true for now and restart settings.
| Request | Effect |
|---|---|
PATCH /api/v1/settings {"idle_hours": 4, "auto_pause": false} | Change several at once; all are checked before any is kept |
PATCH /api/v1/settings {"idle_hours": null} | Back to the .env value |
DELETE /api/v1/settings/idle_hours | The same |
POST /api/v1/settings/test-email {"to": "[email protected]"} | Send a test e-mail with the current mail settings |
POST /api/v1/alerts/test {"channel": "webhook", "webhook": 2} | Send a test alert to webhook 2 (or {"channel": "email"}: to every alert recipient) |
POST /api/v1/server/restart | Apply the restart settings; refused with 409 while jobs run |
A wrong value is refused with 400 and the setting's name (IDLE_HOURS: Input should be greater than or equal to 0.); a setting that can only be set in .env is refused with 400. Secrets (smtp_password, odoo_admin_password, github_webhook_secret, alert_webhook_<n>_url, alert_webhook_<n>_secret) are write-only: value and env_value only say whether they are set, and they are stored encrypted with the vault key. The audit log records their change as SMTP_PASSWORD=(set), never the value. Every change sends the settings live event.
8. Live events
GET /api/v1/events keeps the connection open and sends every change the moment it happens, as Server-Sent Events, a standard every browser reads with EventSource. Nothing needs to ask "anything new?" again and again: a job's progress, an instance going online, new resource figures arrive by themselves.
id: 4182
event: job
data: {"key": "a12fff66a05d", "data": {"id": "a12fff66a05d", "status": "running", "steps": [...], ...}}
id: 4183
event: metrics
data: {"key": "", "data": {"server": {"cpu": 12.5, ...}, "instances": {"sales-main": {"cpu_percent": 3.1, ...}}}}| Event | When | data |
|---|---|---|
instance | An instance changed: status, code, address, settings, a job started or ended | The instance, as GET /instances/<name> |
instance.deleted | An instance was deleted | {"name"} |
job | A job started, moved to another step, added a note or ended | The job, as GET /jobs/<id> |
job.output | New log text of a running job (at most twice a second) | {"job", "offset", "text"} |
metrics | Every METRICS_INTERVAL_SECONDS (5 by default) | The new figures, as GET /metrics (Metrics) |
settings | A setting was changed | {"changed": ["idle_hours", ...]} |
alert | An alert was raised, repeated, resolved or delivered; only for callers with audit.view | The alert, as GET /alerts |
reset | After a reconnection, when more was missed than the panel keeps | {}: reload everything |
?topics=job,instancesends only those events.- A line starting with
:is sent every 20 seconds to keep the connection open through proxies; ignore it. - When the connection drops,
EventSourcereconnects by itself and sends the lastidit received (Last-Event-ID); the stream starts with what was missed, only the latest state of each instance and job. Other clients can send?last_event_id=instead. - An open stream checks its caller every minute and ends when the session was signed out or ended, the account was deleted, or the API token was revoked. Reconnecting then answers 401.
- One account or API token can hold 8 streams at once; one more is answered 429. The panel holds 500 in all; beyond that the answer is 503. Both carry
Retry-After: wait, then open the stream again. The panel's web app does this by itself.
In a browser (the session cookie is sent by itself):
const events = new EventSource("/api/v1/events?topics=job,instance");
events.addEventListener("job", (message) => {
const { data: job } = JSON.parse(message.data);
console.log(job.action, job.status);
});From another system, sign GET /api/v1/events like any other request; the signature's 5-minute window applies to opening the stream, which then stays open. With the Python client:
for event in api.events(topics=["job"]):
print(event["event"], event["data"]["status"])9. Metrics
The panel measures the server and every instance every METRICS_INTERVAL_SECONDS (5 seconds by default, 2 to 60, changeable on the Settings page) and keeps one hour of figures in memory (they start again empty when the panel restarts). Container figures come from a continuous docker stats stream.
| Figure | Meaning |
|---|---|
cpu_percent | Share of the whole server's processor (all cores); for an instance, Odoo and its database together |
memory_percent, memory_bytes, memory_limit_bytes | Memory in use, of the containers' limit (the server's memory when they have none) |
requests_per_minute | Requests the gateway forwarded to Odoo: pages, RPC and API calls (the background traffic of open tabs is left out) |
error_rate_percent | Share of those requests answered with a 5xx error; null without requests |
response_ms_avg, response_ms_p95 | Time until Odoo started answering: average, and the time 95 % of requests stayed under |
uptime_seconds | Since Odoo's container started; null when it is not running |
disk_bytes | Database and files, measured every 5 minutes while running |
Server only: memory_*_bytes, disk_percent, disk_*_bytes, load_1m, cores, uptime_seconds, instances_running, instances_total | instances_running: how many instances run now |
Server only: panel_cpu_percent, panel_memory_bytes, panel_cpu_peak_percent, panel_memory_peak_bytes | The panel's own use (its backend, its web service and the Cloudflare connectors): now, and the highest over the history kept |
GET /api/v1/metrics returns the latest sample:
{
"data": {
"at": 1794430123,
"interval_seconds": 5,
"server": {"cpu_percent": 12.5, "memory_percent": 61.2, "disk_percent": 48.0, "load_1m": 0.42, ...},
"instances": {"sales-main": {"running": true, "cpu_percent": 3.2, "memory_percent": 30.1, ...}}
}
}GET /api/v1/metrics/history?minutes=60 returns the history in columns, one list per figure, the shape chart libraries draw from directly; t holds the times (Unix seconds):
{
"data": {
"server": {"t": [1794426523, ...], "cpu_percent": [11.0, ...], "memory_percent": [...], "disk_percent": [...], "load_1m": [...],
"instances_running": [3, ...]},
"instances": {"sales-main": {"t": [...], "cpu_percent": [...], "memory_percent": [...], "requests_per_minute": [...], ...}}
},
"meta": {"minutes": 60, "interval_seconds": 5}
}A dashboard loads the history once, then appends the sample of every metrics live event. GET /metrics and the metrics event also carry capacity, the estimate below (null before the first measurement).
Capacity
GET /api/v1/server/capacity says how many instances the server can run at the same time comfortably, so a tool can check before it creates or starts one. How the figures are made, in plain language: How many instances can my server run?.
{
"data": {
"comfortable": 9, "running": 9, "headroom": 0, "limited_by": "memory",
"warning": true,
"message": "This server can run about 9 instances at once; 9 are running. Starting another may slow every instance.",
"overloaded": false, "alert": null, "memory_percent": 71.4, "warning_percent": 85,
"hard_limit": null, "blocked": false,
"memory": {"total_bytes": 8589934592, "reserve_bytes": 1073741824, "panel_bytes": 314572800,
"usable_bytes": 7201619968, "per_instance_bytes": 734003200, "per_instance_source": "default",
"instance_average_bytes": null, "instance_peak_bytes": null, "instance_largest_bytes": null,
"measured_instances": 0, "instances": 9},
"processor": {"cores": 4, "panel_percent": 0.6, "per_instance_percent": null, "instances": null},
"disk": {"free_bytes": 128849018880, "instance_average_bytes": 1610612736, "more_instances": 80},
"by_version": [],
"panel": {"cpu_percent": 0.4, "cpu_peak_percent": 3.1, "memory_bytes": 251658240, "memory_peak_bytes": 314572800,
"parts": {"backend": {"cpu_percent": 0.3, "memory_bytes": 167772160, "containers": 1},
"web": {"cpu_percent": 0.0, "memory_bytes": 20971520, "containers": 1},
"connectors": {"cpu_percent": 0.1, "memory_bytes": 62914560, "containers": 3}}}
}
}| Field | Meaning |
|---|---|
comfortable | Instances that can run at once: memory.instances, or processor.instances when that is lower (limited_by) |
running, headroom | Instances running now or being created or started, and comfortable - running (negative when over) |
warning, message | true when starting one more goes beyond comfortable, with the sentence the panel shows |
overloaded, alert | true when the server's memory use reached warning_percent (CAPACITY_WARNING_PERCENT) or more instances run than comfortable, with the dashboard's sentence |
hard_limit, blocked | MAX_RUNNING_INSTANCES (null when off), and whether creating or starting one more is refused now (403) |
memory | usable_bytes = total_bytes - reserve_bytes - panel_bytes; per_instance_bytes is the measured peak of a running instance, averaged over measured_instances, or CAPACITY_INSTANCE_MEMORY_MB (per_instance_source: "default") |
processor | The average share of the server's processor one running instance uses; instances: how many fit under warning_percent (null before one is measured) |
disk | Free disk, the average size of an instance (database and files) and how many more of that size fit |
by_version | Per Odoo version, once instances of it were measured: {"version": "18.0", "instances": 3, "average_bytes", "peak_bytes"} |
panel | The panel's own use: now, the highest over the history, and by part |
The estimate is never a refusal unless MAX_RUNNING_INSTANCES is set: then POST /instances and the start action answer 403 with detail "This server runs at most 9 instances at once and 9 are running or starting. Pause one first." while that many run.
10. Signing in from a web app
On a new server there is no account yet. GET /api/v1/setup answers {"needed": true}, and the first account is created with the setup code the installer printed (docker exec sudoo-panel sudoo.sh setup-code shows it again):
POST /api/v1/setup {"setup_code": "K7QH-3MXP-9TAD", "password": "...",
"first_name": "Sam", "last_name": "Lee", "email": "[email protected]", "phone": ""}
-> 201 {"data": {"user": "sam", "role": "super_admin", "csrf_token": "...", ...}} signed inemail and first_name are required. Without username, the user name is made from the e-mail address (here sam); it is the account's key in user and in /users/<name>. The password follows the password rules. The code works once. A wrong one is 403; 5 wrong ones from an address in 15 minutes block it (429). Once an account exists, POST /api/v1/setup is refused with 400.
The panel's own web app then signs in with a session cookie. Without a second factor it is one call; with one, two:
POST /api/v1/session {"username": "[email protected]", "password": "..."}
-> 201 {"data": {"user": "sam", "csrf_token": "...", ...}} signed in
-> 200 {"data": {"second_factor": {
"methods": [{"name": "totp", "label": "Authenticator app"}, {"name": "email", "label": "E-mail code"}],
"sent_to": "s***@example.com"}}} a code is needed
POST /api/v1/session/second-factor/email (only to send a new e-mail code)
POST /api/v1/session/second-factor {"method": "totp", "code": "123456"}
-> 201 {"data": {"user": "sam", "csrf_token": "...", ...}}username takes the e-mail address or the user name. A wrong e-mail address and a wrong password give the same 401 "Wrong e-mail address or password.", in the same time.
Between the two calls the session opens nothing, for 5 minutes at most.
A signed-in session can be restricted ("restricted" in the answer). Only /api/v1/session, /api/v1/account and /api/v1/contact answer until the task is done:
restricted | Why | Done with |
|---|---|---|
"password" | The password was set by someone else (a new account, or POST /users/<name>/password) with must_change_password | PUT /api/v1/session/password {"current", "new"} |
"second_factor" | REQUIRE_SECOND_FACTOR applies and the account has no second factor ("must_set_up_second_factor": true) | setting one up, as below |
Setting up an authenticator app:
POST /api/v1/account/second-factors/totp {} -> {"secret": "JBSW...", "otpauth_uri": "otpauth://totp/..."}
(show the URI as a QR code)
PUT /api/v1/account/second-factors/totp {"code": "123456"}API tokens are not affected: a token already is something only its system has.
GET /api/v1/session returns the same document at any time; read permissions from it to decide which controls to show.
11. Limits
Requests per minute. Every caller (signed-in user, API token, or address before signing in) may send RATE_LIMIT_READS_PER_MINUTE reading requests (600) and RATE_LIMIT_CHANGES_PER_MINUTE changing ones (60). Answers carry the standard fields:
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 41 seconds until the window has moved onOver the limit: 429 Too Many Requests and Retry-After. Well-behaved clients wait that long.
Instances. MAX_INSTANCES (server), MAX_INSTANCES_PER_USER and CREATE_COOLDOWN_MINUTES limit creation; all are off (0) unless set, and can be changed on the Settings page. Before offering New instance, ask:
GET /api/v1/instance-quota
{"data": {"instances": 4, "max_instances": 10, "own_instances": 2, "max_instances_per_user": 3,
"cooldown_minutes": 60, "next_creation_at": 1794433723}}With X-Sudoo-Acting-For the caller is api:<token name> for <person>: own_instances, MAX_INSTANCES_PER_USER and the waiting time then count per person.
next_creation_at (Unix time) is set while the caller has to wait. A creation that breaks a limit is refused with 403 (a number is reached) or 429 with Retry-After (wait). Creations that are queued or running count as instances (of whoever started them), in instances and own_instances too, so creations started together cannot pass a limit.