Environments

Environments represent individual Odoo instances (development, staging, production) within a project. Each environment has its own database, containers, and URL.

Base URL: https://api.oec.sh/api/public/v1

Environment Status Values

Status	Meaning
`pending`	Newly created, waiting to be provisioned.
`deploying`	Initial provisioning or redeployment in progress.
`running`	Environment is up and serving traffic.
`stopped`	Deliberately stopped (containers are down, data is preserved).
`paused`	Paused by the platform (e.g. quota exceeded).
`failed`	Last deploy or provisioning attempt failed.
`error`	Runtime error detected.
`destroying`	Deletion is in progress.
`deleted`	Environment has been destroyed.

List Environments

GET /projects/{project_id}/environments

Returns all active environments for a project, ordered by creation time (oldest first).

Path Parameters

Parameter	Type	Description
`project_id`	UUID	The project ID.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status. Case-insensitive. Example: `?status=running`.

Response — 200 OK

Returns an array of Environment objects.

Example

# List all environments for a project
curl "https://api.oec.sh/api/public/v1/projects/YOUR_PROJECT_ID/environments" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Filter to running environments only
curl "https://api.oec.sh/api/public/v1/projects/YOUR_PROJECT_ID/environments?status=running" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Environment

POST /projects/{project_id}/environments

Creates a new environment inside a project and immediately enqueues an initial deployment. Requires a full_access API key.

This endpoint supports idempotency. Supply an X-Idempotency-Key header to safely retry on network errors without creating duplicate environments.

The environment is created with status deploying and a deployment is queued automatically. Poll GET /environments/{id}/status or use webhooks to track when it reaches running.

Path Parameters

Parameter	Type	Description
`project_id`	UUID	The project ID.

Headers

Header	Required	Description
`X-Idempotency-Key`	No	A unique string (UUID recommended). Duplicate requests with the same key return the original response within 24 hours.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name for the environment. Max 255 characters.
`branch`	string	No	Git branch to deploy. Defaults to the project's `default_branch`, then `"main"`.
`environment_type`	string	No	One of `development`, `staging`, `production`. Defaults to `development`.

Response — 201 Created

Returns the created Environment object. The status field will be "deploying".

Example

curl -X POST "https://api.oec.sh/api/public/v1/projects/YOUR_PROJECT_ID/environments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "staging",
    "branch": "release/17.0",
    "environment_type": "staging"
  }'

Get Environment

GET /environments/{env_id}

Returns a single environment by ID.

Path Parameters

Parameter	Type	Description
`env_id`	UUID	The environment ID.

Response — 200 OK

Returns the Environment object.

Environment Object Fields

Field	Type	Description
`id`	UUID	Environment identifier.
`name`	string	Display name.
`status`	string	Current status. See Status Values.
`url`	string\|null	Public HTTPS URL. Uses custom domain if verified, otherwise the platform subdomain.
`odoo_version`	string\|null	Odoo version inherited from the parent project.
`branch`	string\|null	Git branch currently deployed.
`last_commit`	string\|null	SHA of the last deployed commit (not yet implemented — always `null`).
`cpu_cores`	float\|null	Allocated CPU cores.
`ram_mb`	integer\|null	Allocated RAM in megabytes.
`disk_gb`	integer\|null	Allocated disk in gigabytes.
`project_id`	UUID	ID of the parent project.
`server_id`	UUID\|null	ID of the server hosting this environment.
`created_at`	ISO 8601	Creation timestamp.
`updated_at`	ISO 8601\|null	Last update timestamp.

Example

curl "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Environment

PATCH /environments/{env_id}

Updates the environment's name or deployed Git branch. Requires a full_access API key. Omit any field to leave it unchanged. Changes to branch take effect on the next deploy.

Path Parameters

Parameter	Type	Description
`env_id`	UUID	The environment ID.

Request Body

Field	Type	Required	Description
`name`	string	No	New display name. Max 255 characters.
`branch`	string	No	New Git branch to deploy on next deploy. Max 255 characters.

Response — 200 OK

Returns the updated Environment object.

Example

curl -X PATCH "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch": "hotfix/invoice-fix"}'

Delete Environment

DELETE /environments/{env_id}

Enqueues an environment destruction task. The environment and all its data (containers, database) are permanently removed. Requires a full_access API key.

⚠️

This is irreversible. All data in the environment (database, filestore) is permanently deleted. Back up any data you need before proceeding.

Path Parameters

Parameter	Type	Description
`env_id`	UUID	The environment ID.

Headers

Header	Required	Description
`X-Confirm-Delete`	Yes	Must be exactly `"true"`.

Response — 202 Accepted

Deletion is asynchronous. The response contains a task_id to track progress.

{
  "task_id": "a1b2c3d4-...",
  "status": "queued",
  "environment_id": "YOUR_ENV_ID",
  "poll_url": "/api/public/v1/deployments/a1b2c3d4-..."
}

Example

curl -X DELETE "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Confirm-Delete: true"

Get Environment Status

GET /environments/{env_id}/status

Returns a lightweight health snapshot for an environment. Use this for quick polling without fetching the full environment object.

Path Parameters

Parameter	Type	Description
`env_id`	UUID	The environment ID.

Response — 200 OK

{
  "environment_id": "YOUR_ENV_ID",
  "status": "running",
  "url": "https://staging.yourapp.com",
  "container_running": true,
  "db_ready": true,
  "http_ok": true,
  "last_deploy": {
    "id": "task-uuid",
    "status": "completed",
    "started_at": "2026-03-01T12:00:00Z",
    "completed_at": "2026-03-01T12:05:00Z"
  }
}

Response Fields

Field	Type	Description
`environment_id`	UUID	The environment ID.
`status`	string	Current environment status.
`url`	string\|null	Public HTTPS URL.
`container_running`	boolean	`true` when the environment is `running` or `paused`.
`db_ready`	boolean	Best-effort: `true` when the container is running.
`http_ok`	boolean	Best-effort: `true` when the container is running.
`last_deploy`	object\|null	Summary of the most recent deployment task, or `null` if none.
`last_deploy.id`	UUID	Task ID.
`last_deploy.status`	string	Task status: `pending`, `queued`, `running`, `completed`, `failed`.
`last_deploy.started_at`	ISO 8601\|null	When the task started.
`last_deploy.completed_at`	ISO 8601\|null	When the task completed.

Example

curl "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Environment Logs

GET /environments/{env_id}/logs

Returns deployment log text for the most recent (or a specified) task.

Path Parameters

Parameter	Type	Description
`env_id`	UUID	The environment ID.

Query Parameters

Parameter	Type	Description
`task_id`	UUID	Specific deployment task ID. Defaults to the most recent task.
`lines`	integer	Maximum number of log lines to return. Min 1, max 5000. Default `200`.

Response — 200 OK

{
  "task_id": "task-uuid",
  "log": "Step 1/12: Connecting to server...\nStep 2/12: Pulling image...\n...",
  "lines": 42,
  "truncated": false
}

Response Fields

Field	Type	Description
`task_id`	string\|null	The task ID whose logs are returned. `null` if no task found.
`log`	string	Full log text. Lines are joined with `\n`.
`lines`	integer	Number of lines in the returned `log`.
`truncated`	boolean	`true` if there were more lines than requested and the log was cut. The most recent lines are kept.

Example

curl "https://api.oec.sh/api/public/v1/environments/YOUR_ENV_ID/logs?lines=500" \
  -H "Authorization: Bearer YOUR_API_KEY"

Projects Deploy Actions