Projects

Projects are the top-level container for your Odoo deployments. Each project belongs to an organisation, has a single Git repository, and can contain multiple Environments.

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

List Projects

GET /projects

Returns all active projects for your organisation. If your API key is project-scoped, only that project is returned.

Query Parameters

Parameter	Type	Description
`limit`	integer	Results per page. Min 1, max 100. Default `20`.
`cursor`	string	Opaque pagination cursor from the previous response's `pagination.next_cursor`.

Response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Client ERP",
      "odoo_version": "17.0",
      "git_repo_url": "https://github.com/acme/client-erp",
      "default_branch": "main",
      "environment_count": 3,
      "server_id": "8e4f2a1c-1234-5678-abcd-ef0123456789",
      "created_at": "2025-09-15T10:30:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total": 1
  }
}

Response Fields

Field	Type	Description
`data`	array	List of project objects.
`pagination.has_more`	boolean	Whether more pages exist.
`pagination.next_cursor`	string\|null	Pass as `cursor` to fetch the next page. `null` when on the last page.
`pagination.total`	integer	Total number of matching projects.

Project Object Fields

Field	Type	Description
`id`	UUID	Project identifier.
`name`	string	Display name.
`odoo_version`	string\|null	Odoo version string, e.g. `"17.0"`.
`git_repo_url`	string\|null	Git repository URL.
`default_branch`	string\|null	Default Git branch, e.g. `"main"`.
`environment_count`	integer	Number of active environments.
`server_id`	UUID\|null	ID of the server this project is deployed on.
`created_at`	ISO 8601	Creation timestamp.

Example

curl "https://api.oec.sh/api/public/v1/projects?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Project

POST /projects

Creates a new project. Requires a full_access, org-scoped API key.

This endpoint supports idempotency. Supply an X-Idempotency-Key header to safely retry without creating duplicates. The same response is returned for duplicate requests within 24 hours.

Headers

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

Request Body

Field	Type	Required	Description
`name`	string	Yes	Project display name. Max 255 characters.
`server_id`	UUID	Yes	ID of the server to deploy on. Use List Servers to find valid IDs.
`git_repo_url`	string	No	HTTPS URL of the Git repository.
`default_branch`	string	No	Default Git branch. Defaults to `"main"`. Max 255 characters.
`odoo_version`	string	No	Odoo version string, e.g. `"17.0"`, `"16.0"`.

Response — 201 Created

Returns the created Project object.

Example

curl -X POST "https://api.oec.sh/api/public/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Client ERP",
    "server_id": "YOUR_SERVER_ID",
    "git_repo_url": "https://github.com/acme/client-erp",
    "default_branch": "main",
    "odoo_version": "17.0"
  }'

Get Project

GET /projects/{project_id}

Returns a single project by ID.

Path Parameters

Parameter	Type	Description
`project_id`	UUID	The project ID.

Response — 200 OK

Returns the Project object.

Example

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

Update Project

PATCH /projects/{project_id}

Updates a project's name, default branch, or Git repository URL. Requires a full_access API key. Omit any field to leave it unchanged.

Path Parameters

Parameter	Type	Description
`project_id`	UUID	The project ID.

Request Body

Field	Type	Required	Description
`name`	string	No	New display name. Max 255 characters.
`default_branch`	string	No	New default Git branch. Max 255 characters.
`git_repo_url`	string	No	New Git repository URL.

Response — 200 OK

Returns the updated Project object.

Example

curl -X PATCH "https://api.oec.sh/api/public/v1/projects/YOUR_PROJECT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"default_branch": "release/17.0"}'

Delete Project

DELETE /projects/{project_id}

Soft-deletes a project. Requires a full_access, org-scoped API key.

⚠️

This is a destructive operation. You must include the X-Confirm-Delete: true header. The project must have no running or deploying environments — stop them first.

Path Parameters

Parameter	Type	Description
`project_id`	UUID	The project ID.

Headers

Header	Required	Description
`X-Confirm-Delete`	Yes	Must be exactly `"true"`. Missing or any other value returns `400`.

Response — 204 No Content

Empty body on success.

Error Cases

Status	Error Code	Reason
`400`	`confirm_required`	`X-Confirm-Delete: true` header was not provided.
`403`	`project_scoped_key`	Project-scoped keys cannot delete projects.
`409`	`environments_running`	One or more environments are still running or deploying.

Example

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

List Servers

GET /servers

Returns the BYOS (Bring Your Own Server) servers available to your organisation. Use the id field when creating a project.

Query Parameters

Parameter	Type	Description
`limit`	integer	Results per page. Min 1, max 100. Default `20`.
`cursor`	string	Pagination cursor from previous response.

Response — 200 OK

{
  "data": [
    {
      "id": "8e4f2a1c-1234-5678-abcd-ef0123456789",
      "name": "production-server",
      "provider": "hetzner",
      "region": "fsn1",
      "cpu_cores": 6,
      "ram_mb": 63488,
      "disk_gb": 477,
      "environment_count": 4
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "total": 1
  }
}

Server Object Fields

Field	Type	Description
`id`	UUID	Server identifier — use this as `server_id` when creating a project.
`name`	string	Display name.
`provider`	string	Cloud provider, e.g. `"hetzner"`, `"digitalocean"`, `"aws"`.
`region`	string\|null	Provider region or datacenter.
`cpu_cores`	integer	Total CPU cores.
`ram_mb`	integer	Total RAM in megabytes.
`disk_gb`	integer	Total disk in gigabytes.
`environment_count`	integer	Number of active environments currently deployed on this server.

Example

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

Errors & Status Codes Environments