# Projects & Environments

> Group environments under a shared product or team. Bind environments to deployment spaces, namespaces, and registries for pushing built images.

Source: https://zop.dev/developer-docs/deployments/projects

---

A **project** groups one or more environments (typically `dev`, `staging`, `prod`) under a shared product or team. An **environment** binds a project to a [deployment space](https://zop.dev/docs/deployments/deployment-spaces) (a registered Kubernetes cluster) and a namespace, plus a registry for pushing built images.

**Info**

Project → Environment → Deployment. Topology, RBAC, and audit logs all roll up along this hierarchy.

**Info**

The project / environment / deployment catalog is owned by the **config service** — every endpoint on this page is served by config. Live runtime queries that need a kubeconfig (`environments/{envID}/stats`, `environments/{envID}/cluster-discovery`) are served by the **deployer** and called out below.

## Projects

### POST /projects

Create a project. (config)

```bash title="Request"
curl -X POST https://zopnight.com/api/projects \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "checkout" }'
```

### GET /projects

List projects. (config)

### GET /projects/stats

Batch stats (env count, service count, status buckets, last deploy) for every project the caller can see — used to render the dashboard cards in a single round-trip. (config)

### GET /projects/{projectID}

Get a single project. (config)

### PATCH /projects/{projectID}

Rename a project. (config)

### DELETE /projects/{projectID}

Soft-delete a project. All child environments and deployments must be removed first. (config)

## Environments

Environments live under a project. Each environment binds:

- A [deployment space](https://zop.dev/docs/deployments/deployment-spaces) (the registered cluster).
- A `namespace` on that space's cluster.
- An optional registry integration plus URL for built images (typically the cloud account's native registry — ECR / Artifact Registry / ACR).

### POST /projects/{projectID}/environments

Create an environment under a project. (config)

```bash title="Request"
curl -X POST https://zopnight.com/api/projects/prj_acme/environments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-us-east",
    "spaceId": "spc_abc",
    "namespace": "checkout-prod",
    "registryIntegrationId": "int_ecr_001",
    "registryUrl": "123456789012.dkr.ecr.us-east-1.amazonaws.com/checkout"
  }'
```

### GET /projects/{projectID}/environments

List environments under a project. (config)

### GET /projects/{projectID}/environments/{envID}

Get an environment in nested-path form (used by the canvas). (config)

### PATCH /projects/{projectID}/environments/{envID}

Update an environment (name, space, namespace, registry). (config)

### DELETE /projects/{projectID}/environments/{envID}

Soft-delete an environment. All deployments must be removed first. (config)

### Flat lookup

For deep-link URLs and integrations that hold an env ID without its project, the catalog exposes a flat lookup:

### GET /environments/{envID}

Get an environment by ID without knowing its project. (config)

### Live runtime queries

The two endpoints below run against the env's target cluster in real-time (kubeconfig-minted from the cloud account credentials). They live on the deployer because that's where cluster credentials are materialised.

### GET /environments/{envID}/stats

Quick stats for the environment (deployment count, current state, total CPU/RAM requested). (deployer)

```json title="Response"
{
  "data": {
    "deploymentCount": 6,
    "runningCount": 5,
    "failedCount": 0,
    "cpuRequestedCores": 12,
    "memoryRequestedGB": 24
  }
}
```

### GET /environments/{envID}/cluster-discovery

Live cluster discovery: ingress controllers and cert managers actually present on the namespace

## Topology & the Canvas

The Architecture canvas is rendered client-side from the same catalog endpoints above — there is no aggregated server-side topology endpoint on the public API. The client lists projects, environments, [deployments](https://zop.dev/docs/deployments/deployments), and [service connections](https://zop.dev/docs/deployments/service-connections), groups them into the project → environment → deployment hierarchy, and renders the edges using the stored `canvasPosition` on each deployment.