codai docs
Projects & Environments

Environments API

The /v1/projects and /v1/environments endpoints on ai.codai.ro, with request and response examples.

Base URL https://ai.codai.ro, Authorization: Bearer codai_…, JSON in and out. The live daemon view (online, listening ports, git state, locks, attached clients) is served by the relay at https://relay.codai.ro/v1/environments/{id}/status with the same key.

Conventions, all taken from the gateway:

  • Project and environment rows are returned camelCase, as stored; request bodies and member/secret lists are snake_case.
  • A project or environment you cannot see answers 404 (never 403), so ids cannot be enumerated. A role violation on something you can see answers 403.
  • Errors use the gateway envelope { "error": { "message", "type", "code" } }; validation errors are 400 bad_request.
  • Every mutation appends an environment_events row.

Endpoints

MethodPathMin. roleNotes
GET/v1/projects—Yours plus your orgs', newest first
POST/v1/projects—org_id needs org owner/admin
GET/v1/projects/{id}visibleProject + all its environments
PATCH/v1/projects/{id}project owner / org adminSlug cannot change
DELETE/v1/projects/{id}project owner / org admin409 project_has_environments until all are destroyed
GET/v1/environments—?project_id=, ?for_user_id=me
POST/v1/environmentsproject visibleManaged providers are feature-gated (403)
GET/v1/environments/{id}viewerEnv + role + isolation + members + ports + last 20 events
PATCH/v1/environments/{id}maintainername, idle_timeout_minutes
POST/v1/environments/{id}/start · stop · archivemaintainer409 invalid_transition
POST/v1/environments/{id}/destroyowner
POST/v1/environments/{id}/enroll-tokenmaintainerBYO only (409 not_byo)
POST/v1/environments/enrolltokenCalled by codaid, no API key
GET/v1/environments/{id}/membersviewer
POST/v1/environments/{id}/membersmaintainerowner needs owner
PUT/v1/environments/{id}/members/me/ssh-keydeveloperYour own key
PATCH · DELETE/v1/environments/{id}/members/{userId}maintainerLeaving yourself needs no role
GET/v1/environments/{id}/portsviewerPublished ports
PUT · DELETE/v1/environments/{id}/ports/{port}developerpublic needs maintainer
GET/v1/environments/{id}/secretsdeveloperNames only
PUT · DELETE/v1/environments/{id}/secrets/{name}maintainerNames are ENV_STYLE

Create a project

curl https://ai.codai.ro/v1/projects \
  -H "Authorization: Bearer $CODAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "brivio", "repo_url": "https://github.com/acme/brivio", "isolation": "shared_vm" }'

201:

{
  "project": {
    "id": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f",
    "ownerUserId": "5f0c…", "orgId": null,
    "name": "brivio", "slug": "brivio",
    "repoUrl": "https://github.com/acme/brivio", "defaultBranch": "main", "devcontainerPath": null,
    "isolation": "shared_vm", "settings": {},
    "createdAt": "2026-09-25T09:00:00.000Z", "updatedAt": "2026-09-25T09:00:00.000Z"
  }
}

slug defaults to the slugified name and must be unique among your projects (409 slug_taken). isolation is shared_vm (default), container or vm_per_dev.

Create an environment

FieldTypeNotes
project_iduuidRequired.
providerbyo · openstack · hetznerRequired. local is reserved.
namestring ≤ 120Required, except in vm_per_dev projects (defaults to <project> — <you>).
slug^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$Default <project-slug>-<4 random chars>; globally unique (409 slug_taken).
sizesmall · medium · largeManaged only; default small.
regionstringManaged only; default eu-east-1 (OpenStack) or nbg1 (Hetzner).
idle_timeout_minutes5–1440Default 30.
budget_micro_eurinteger ≥ 0 or nullManaged only; monthly compute cap.
curl https://ai.codai.ro/v1/environments \
  -H "Authorization: Bearer $CODAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "project_id": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f", "name": "dev-box", "provider": "byo" }'

201:

{
  "environment": {
    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",
    "projectId": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f",
    "ownerUserId": "5f0c…", "orgId": null, "forUserId": null, "for_user_id": null,
    "isolation": "shared_vm",
    "name": "dev-box", "slug": "brivio-k3xq",
    "provider": "byo", "region": null, "size": null,
    "state": "pending", "stateReason": null,
    "deviceId": null, "providerRef": null, "publicIp": null,
    "idleTimeoutMinutes": 30, "lastActivityAt": null, "startedAt": null, "stoppedAt": null,
    "hourlyRateMicroEur": null, "includedHoursUsedSeconds": 0,
    "metadata": {},
    "createdAt": "2026-09-25T09:01:00.000Z", "updatedAt": "2026-09-25T09:01:00.000Z"
  }
}

A managed provider starts in creating with size, region, hourlyRateMicroEur (e.g. 30000 for small) and metadata.budget_micro_eur filled in. In a vm_per_dev project a second live environment answers:

{
  "error": { "message": "You already have an environment in this vm_per_dev project.", "type": "invalid_request_error", "code": "already_has_env" },
  "environment_id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c"
}

Enrol a BYO machine

curl -X POST https://ai.codai.ro/v1/environments/$ENV_ID/enroll-token -H "Authorization: Bearer $CODAI_API_KEY"
{ "token": "codai_env_4Qm9…32 chars", "expires_at": "2026-09-25T09:31:00.000Z", "environment_id": "9c1e5a7b-…" }

The token is returned once, stored only as a SHA-256 hash, valid 30 minutes, and minting again replaces it. codaid presents it to POST /v1/environments/enroll:

{ "token": "codai_env_…", "device_id": "1c2f…-uuid", "daemon_version": "0.3.3", "os": "linux", "arch": "x86_64" }

→ { "environment_id": "9c1e…", "relay_url": "wss://relay.codai.ro" } (managed machines also receive a one-time api_key). An unknown, used or expired token is 401 invalid_api_key; a state that does not admit enrolment is 409 not_enrollable.

Lifecycle actions

curl -X POST https://ai.codai.ro/v1/environments/$ENV_ID/stop -H "Authorization: Bearer $CODAI_API_KEY"
{ "environment": { "id": "9c1e…", "state": "stopping", "stateReason": "user_request", "…": "…" }, "from": "running", "to": "stopping" }

Allowed transitions are on the managed page; BYO environments accept only archive and destroy.

Members

curl https://ai.codai.ro/v1/environments/$ENV_ID/members \
  -H "Authorization: Bearer $CODAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "role": "developer" }'

201 → { "member": { "user_id": "7a1c09e4-…", "role": "developer", "linux_username": "u-7a1c09e4", "port_range_start": 30100 } }. GET …/members returns { "members": [{ "user_id", "role", "email", "name", "linux_username", "port_range_start", "ssh_public_key": true, "provisioned_at", "created_at" }] } — ssh_public_key is only a flag. Errors: 404 (no account with that e-mail), 409 already_member, 409 vm_per_dev_single_member, 409 last_owner.

Register your own key:

curl -X PUT https://ai.codai.ro/v1/environments/$ENV_ID/members/me/ssh-key \
  -H "Authorization: Bearer $CODAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "public_key": "ssh-ed25519 AAAAC3Nza… ana@laptop" }'

→ { "user_id": "…", "ssh_public_key": true }.

Ports

PUT /v1/environments/{id}/ports/{port} with { "visibility": "owner" | "org" | "authenticated" | "public", "label"?: string ≤ 64, "protocol"?: "http" } returns { "port": { "id", "environmentId", "port", "protocol", "label", "visibility", "openedByUserId", "createdAt", "updatedAt" } }. See ports and previews.

Secrets

curl -X PUT https://ai.codai.ro/v1/environments/$ENV_ID/secrets/DATABASE_URL \
  -H "Authorization: Bearer $CODAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "value": "postgres://…" }'

201 → { "name": "DATABASE_URL", "updated": false } (200 and true when replacing). Values are envelope-sealed at rest (≤ 64 KB) and never returned; GET …/secrets lists { "name", "created_by_user_id", "created_at", "updated_at" }. Injecting secrets into shells inside the environment is coming soon; today only CODAI_GIT_TOKEN is used, for cloning (see team).

Relay status

curl https://relay.codai.ro/v1/environments/$ENV_ID/status -H "Authorization: Bearer $CODAI_API_KEY"
{
  "environment_id": "9c1e…", "online": true, "instance": "relay-7f3a", "last_heartbeat": 1790326860000,
  "activity": "agent",
  "ports": [{ "port": 3000, "pid": 4121, "process": "node" }],
  "git_state": { "branch": "main", "dirty": true, "ahead": 1, "behind": 0, "worktrees": ["/home/u-7a1c09e4/work/brivio"] },
  "daemon": { "daemon_version": "0.3.3", "os": "linux", "arch": "x86_64", "capabilities": ["shell", "pty", "tcp", "http", "lock:build", "identity:per-user"] },
  "streams": 2,
  "attached": [{ "client_id": "…", "user_id": "…", "role": "owner", "kind": "agent", "device_id": "…", "name": "Work laptop", "platform": "desktop", "attached_at": "2026-09-25T09:20:00.000Z" }],
  "locks": [{ "name": "build-0123456789ab", "holder": "u-7a1c09e4 · pnpm build", "since": "2026-09-25T09:20:30Z" }],
  "clients": 1
}

Reference

GET
/v1/projects

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects"
{  "projects": [    {      "id": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f",      "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",      "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",      "name": "brivio",      "slug": "brivio",      "repoUrl": "https://github.com/acme/brivio",      "defaultBranch": "main",      "devcontainerPath": ".devcontainer/devcontainer.json",      "isolation": "shared_vm",      "settings": {},      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/projects

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects" \  -H "Content-Type: application/json" \  -d '{    "name": "brivio"  }'
{  "project": {    "id": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "name": "brivio",    "slug": "brivio",    "repoUrl": "https://github.com/acme/brivio",    "defaultBranch": "main",    "devcontainerPath": ".devcontainer/devcontainer.json",    "isolation": "shared_vm",    "settings": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
GET
/v1/projects/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Project UUID. A malformed value is 400; an unknown or foreign project is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "project": {    "id": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "name": "brivio",    "slug": "brivio",    "repoUrl": "https://github.com/acme/brivio",    "defaultBranch": "main",    "devcontainerPath": ".devcontainer/devcontainer.json",    "isolation": "shared_vm",    "settings": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "environments": [    {      "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",      "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",      "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",      "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",      "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",      "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",      "isolation": "shared_vm",      "name": "brivio — Ana",      "slug": "brivio-k3xq",      "provider": "byo",      "region": "nbg1",      "size": "small",      "state": "pending",      "stateReason": "string",      "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",      "providerRef": "string",      "publicIp": "string",      "idleTimeoutMinutes": 30,      "lastActivityAt": "2019-08-24T14:15:22Z",      "startedAt": "2019-08-24T14:15:22Z",      "stoppedAt": "2019-08-24T14:15:22Z",      "hourlyRateMicroEur": 0,      "includedHoursUsedSeconds": 0,      "metadata": {},      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
PATCH
/v1/projects/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Project UUID. A malformed value is 400; an unknown or foreign project is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

At least one field is required.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{  "project": {    "id": "2b6d1c0e-4f3a-4b9c-8d7e-1a2b3c4d5e6f",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "name": "brivio",    "slug": "brivio",    "repoUrl": "https://github.com/acme/brivio",    "defaultBranch": "main",    "devcontainerPath": ".devcontainer/devcontainer.json",    "isolation": "shared_vm",    "settings": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
DELETE
/v1/projects/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Project UUID. A malformed value is 400; an unknown or foreign project is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "deleted": true,  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}
GET
/v1/environments

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Query Parameters

project_id?string

Restrict to one project.

Formatuuid
for_user_id?"me"

Only me is accepted — your own per-developer environments.

Value in

  • "me"

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/environments"
{  "environments": [    {      "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",      "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",      "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",      "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",      "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",      "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",      "isolation": "shared_vm",      "name": "brivio — Ana",      "slug": "brivio-k3xq",      "provider": "byo",      "region": "nbg1",      "size": "small",      "state": "pending",      "stateReason": "string",      "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",      "providerRef": "string",      "publicIp": "string",      "idleTimeoutMinutes": 30,      "lastActivityAt": "2019-08-24T14:15:22Z",      "startedAt": "2019-08-24T14:15:22Z",      "stoppedAt": "2019-08-24T14:15:22Z",      "hourlyRateMicroEur": 0,      "includedHoursUsedSeconds": 0,      "metadata": {},      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/environments

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments" \  -H "Content-Type: application/json" \  -d '{    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",    "provider": "byo"  }'
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
POST
/v1/environments/enroll

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/enroll" \  -H "Content-Type: application/json" \  -d '{    "token": "string",    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",    "daemon_version": "string",    "os": "linux",    "arch": "x64"  }'
{  "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",  "relay_url": "wss://relay.codai.ro",  "api_key": "string"}
GET
/v1/environments/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "isolation": "shared_vm",  "role": "owner",  "members": [    {      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",      "role": "owner",      "email": "[email protected]",      "name": "string",      "linux_username": "string",      "port_range_start": 0,      "ssh_public_key": true,      "provisioned_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "ports": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",      "port": 3000,      "protocol": "http",      "label": "web",      "visibility": "owner",      "openedByUserId": "c717c8e6-87b5-4b69-9353-93a60c6b5d41",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "events": [    {      "id": 0,      "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",      "actorUserId": "94141e08-adc7-44ce-bed3-45f031b9f36f",      "actorKind": "user",      "kind": "state:pending->enrolling",      "payload": {},      "createdAt": "2019-08-24T14:15:22Z"    }  ]}
PATCH
/v1/environments/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Provide name and/or idle_timeout_minutes.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
POST
/v1/environments/{id}/start

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/start"
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "from": "pending",  "to": "pending"}
POST
/v1/environments/{id}/stop

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/stop"
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "from": "pending",  "to": "pending"}
POST
/v1/environments/{id}/archive

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/archive"
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "from": "pending",  "to": "pending"}
POST
/v1/environments/{id}/destroy

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/destroy"
{  "environment": {    "id": "9c1e5a7b-2d4f-4e6a-8b0c-3d5e7f9a1b2c",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",    "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa",    "forUserId": "e7ebe9fe-55a5-420c-a31b-7f6410828de5",    "for_user_id": "5c382187-9b39-4b04-b883-3a2ecc9f4e6e",    "isolation": "shared_vm",    "name": "brivio — Ana",    "slug": "brivio-k3xq",    "provider": "byo",    "region": "nbg1",    "size": "small",    "state": "pending",    "stateReason": "string",    "deviceId": "4de4adb9-21ee-47e3-aeb4-8cf8ed6c109a",    "providerRef": "string",    "publicIp": "string",    "idleTimeoutMinutes": 30,    "lastActivityAt": "2019-08-24T14:15:22Z",    "startedAt": "2019-08-24T14:15:22Z",    "stoppedAt": "2019-08-24T14:15:22Z",    "hourlyRateMicroEur": 0,    "includedHoursUsedSeconds": 0,    "metadata": {},    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "from": "pending",  "to": "pending"}
POST
/v1/environments/{id}/enroll-token

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/enroll-token"
{  "token": "string",  "expires_at": "2019-08-24T14:15:22Z",  "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4"}
GET
/v1/environments/{id}/members

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/members"
{  "members": [    {      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",      "role": "owner",      "email": "[email protected]",      "name": "string",      "linux_username": "string",      "port_range_start": 0,      "ssh_public_key": true,      "provisioned_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/environments/{id}/members

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Exactly one of user_id or email is required.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/members" \  -H "Content-Type: application/json" \  -d '{}'
{  "member": {    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",    "role": "owner",    "linux_username": "string",    "port_range_start": 0  }}
PUT
/v1/environments/{id}/members/me/ssh-key

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/me/ssh-key" \  -H "Content-Type: application/json" \  -d '{    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGx7v0o6Q3m1q0Y4bJw2m9V7a2X5b1x6ZJ3o8Kk1QzAB ana@laptop"  }'
{  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",  "ssh_public_key": true}
PATCH
/v1/environments/{id}/members/{userId}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid
userId*string

UUID of the member.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "role": "owner"  }'
{  "member": {    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",    "role": "owner"  }}
DELETE
/v1/environments/{id}/members/{userId}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid
userId*string

UUID of the member to remove (your own id to leave).

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "deleted": true,  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}
GET
/v1/environments/{id}/ports

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/ports"
{  "ports": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",      "port": 3000,      "protocol": "http",      "label": "web",      "visibility": "owner",      "openedByUserId": "c717c8e6-87b5-4b69-9353-93a60c6b5d41",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
PUT
/v1/environments/{id}/ports/{port}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid
port*integer

TCP port inside the environment (1..65535).

Range1 <= value <= 65535

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/ports/1" \  -H "Content-Type: application/json" \  -d '{    "visibility": "owner"  }'
{  "port": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "environmentId": "19f5cc2e-7657-437a-9268-83cd3d563563",    "port": 3000,    "protocol": "http",    "label": "web",    "visibility": "owner",    "openedByUserId": "c717c8e6-87b5-4b69-9353-93a60c6b5d41",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
DELETE
/v1/environments/{id}/ports/{port}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid
port*integer

TCP port inside the environment (1..65535).

Range1 <= value <= 65535

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/ports/1"
{  "deleted": true,  "port": 0}
GET
/v1/environments/{id}/secrets

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets"
{  "secrets": [    {      "name": "DATABASE_URL",      "created_by_user_id": "209f54c4-4c33-43bc-9c6a-ef4c65ad7473",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}
PUT
/v1/environments/{id}/secrets/{name}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid
name*string

Secret name, ENV_STYLE.

Match^[A-Z_][A-Z0-9_]{0,127}$

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/string" \  -H "Content-Type: application/json" \  -d '{    "value": "string"  }'
{  "name": "string",  "updated": true}
DELETE
/v1/environments/{id}/secrets/{name}

Authorization

bearerAuth
AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Path Parameters

id*string

Environment UUID. A malformed value is 400; an unknown or foreign environment is 404.

Formatuuid
name*string

Secret name, ENV_STYLE.

Match^[A-Z_][A-Z0-9_]{0,127}$

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/environments/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/string"
{  "deleted": true,  "name": "string"}

On this page