# codai Projects & Environments API

**Canonical:** https://apis.io/apis/codai-ro/codai-ro-projects-environments-api/  
**Provider:** codai — https://apis.io/providers/codai-ro/  
**Base URL:** https://ai.codai.ro  
**Documentation:** https://docs.codai.ro/docs/api

codai Projects & Environments API is one of 35 APIs that [codai](https://apis.io/providers/codai-ro/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include Projects & Environments. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and 6 JSON Schemas.

Cloud Environments control plane. A **project** groups environments (repository, default branch, devcontainer path, isolation mode); an **environment** is one machine reachable through the relay via the `codaid` daemon. Members, forwarded ports, sealed secrets and an append-only event log hang off the environment. Visibility: you see a project if you own it or belong to its org; you see an environment if you own it, are a member of it, or belong to its org. Unknown or foreign ids always answer 404 (never 403) so ids cannot be enumerated; a role violation on a resource you CAN see answers 403. Environment roles: `owner` ≥ `maintainer` ≥ `developer` ≥ `viewer` — the environment owner and org owners/admins act as `owner`. Isolation `vm_per_dev` pins one live environment per developer (`for_user_id`): creating a second one answers 409 `already_has_env` carrying the `environment_id` to reuse, and such environments have exactly one member (409 `vm_per_dev_single_member`). Every mutation appends an `environment_events` row. Managed providers (`openstack`, `hetzner`, `local`) are feature-gated (403 until enabled for the key); `byo` — bring your own machine — is open to every key. Project and environment rows are returned camelCase (as stored); request bodies and member/secret lists are snake_case, mirrored here exactly as the gateway sends them. Live daemon state (online, activity, listening ports, git state, attached clients, locks) is served by the **relay**, not the gateway: `GET https://relay.codai.ro/v1/environments/{id}/status`, same bearer key, same 404 rule. It is modelled as the `RelayEnvironmentStatus` path item under `components.pathItems` because it lives on a different host.

## Operations (39)

| Method | Path | Summary |
|---|---|---|
| GET | `/v1/projects` | List your projects |
| POST | `/v1/projects` | Create a project |
| GET | `/v1/projects/{id}` | Get a project with its environments |
| PATCH | `/v1/projects/{id}` | Update a project |
| DELETE | `/v1/projects/{id}` | Delete a project |
| GET | `/v1/environments` | List environments |
| POST | `/v1/environments` | Create an environment |
| POST | `/v1/environments/enroll` | Enrol a daemon (token auth, no API key) |
| GET | `/v1/environments/{id}` | Get an environment |
| PATCH | `/v1/environments/{id}` | Rename or change the idle timeout |
| POST | `/v1/environments/{id}/start` | Start a stopped environment |
| POST | `/v1/environments/{id}/stop` | Stop a running environment |
| POST | `/v1/environments/{id}/archive` | Archive an environment |
| POST | `/v1/environments/{id}/destroy` | Destroy an environment |
| POST | `/v1/environments/{id}/enroll-token` | Mint a one-time enrolment token |
| GET | `/v1/environments/{id}/members` | List members |
| POST | `/v1/environments/{id}/members` | Add a member |
| PUT | `/v1/environments/{id}/members/me/ssh-key` | Set your SSH public key |
| POST | `/v1/environments/{id}/members/me/ssh-cert` | Issue a short-lived SSH certificate |
| GET | `/v1/environments/{id}/ssh-ca` | Get the SSH CA public keys |
| PATCH | `/v1/environments/{id}/members/{userId}` | Change a member's role |
| DELETE | `/v1/environments/{id}/members/{userId}` | Remove a member (or leave) |
| GET | `/v1/environments/{id}/ports` | List forwarded ports |
| PUT | `/v1/environments/{id}/ports/{port}` | Publish a port or change its visibility |
| DELETE | `/v1/environments/{id}/ports/{port}` | Unpublish a port |
| GET | `/v1/environments/{id}/secrets` | List secret names |
| PUT | `/v1/environments/{id}/secrets/{name}` | Set a secret |
| DELETE | `/v1/environments/{id}/secrets/{name}` | Delete a secret |
| GET | `/v1/environments/{id}/tasks` | List agent tasks |
| POST | `/v1/environments/{id}/tasks` | Queue a fire-and-forget agent task |
| GET | `/v1/environments/{id}/tasks/{taskId}` | Get one agent task |
| POST | `/v1/environments/{id}/exec` | Run an operation in an environment |
| GET | `/v1/verify/agent-output/key` | Public key for agent-output signatures (experimental) |
| POST | `/v1/verify/agent-output` | Verify a signed agent output (experimental) |
| GET | `/v1/environments/{id}/files` | List files in an environment |
| GET | `/v1/environments/{id}/files/{path}` | Read a file from an environment |
| PUT | `/v1/environments/{id}/files/{path}` | Write a file in an environment |
| POST | `/v1/environments/{id}/jobs` | Start a background job in an environment |
| GET | `/v1/environments/{id}/jobs/{jobId}` | Get a background job and its output |

## Machine-readable artifacts (8)

- **OpenAPI** — https://artifacts.apis.io/codai-ro/openapi/codai-ro-projects-environments-api-openapi.yml
- **Documentation** — https://docs.codai.ro/docs/gateway
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-environment-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-environment-task-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-project-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-environment-create-body-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-environment-member-schema.json
- **JSONSchema** — https://artifacts.apis.io/codai-ro/json-schema/codai-ro-environment-detail-schema.json

## Other codai APIs (12)

- [codai Account API](https://apis.io/apis/codai-ro/codai-ro-account-api/)
- [codai Agents API](https://apis.io/apis/codai-ro/codai-ro-agents-api/)
- [codai Attestations API](https://apis.io/apis/codai-ro/codai-ro-attestations-api/)
- [codai Authorization API](https://apis.io/apis/codai-ro/codai-ro-authorization-api/)
- [codai Chat & Completions API](https://apis.io/apis/codai-ro/codai-ro-chat-completions-api/)
- [codai Connect API](https://apis.io/apis/codai-ro/codai-ro-connect-api/)
- [codai Devices API](https://apis.io/apis/codai-ro/codai-ro-devices-api/)
- [codai Discovery API](https://apis.io/apis/codai-ro/codai-ro-discovery-api/)
- [codai Embeddings & Audio API](https://apis.io/apis/codai-ro/codai-ro-embeddings-audio-api/)
- [codai Feed API](https://apis.io/apis/codai-ro/codai-ro-feed-api/)
- [codai Guest chat API](https://apis.io/apis/codai-ro/codai-ro-guest-chat-api/)
- [codai Health API](https://apis.io/apis/codai-ro/codai-ro-health-api/)

## Tags

Projects & Environments

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/codai-ro/codai-ro-projects-environments-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/codai-ro/.
