# Environment Management APIs

> API endpoints for managing environments, targets, agents, freeze windows, and inventory.

**Status:** Planned (not yet implemented)
**Source:** [Architecture Advisory Section 6.3.2](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
**Related Modules:** [Environment Manager](../modules/environment-manager.md), [Agents](../modules/agents.md)

## Overview

The Environment Management API provides CRUD operations for environments, target groups, deployment targets, agents, freeze windows, and inventory synchronization. All endpoints require authentication and respect tenant isolation via Row-Level Security.

---

## Environment Endpoints

### Create Environment

**Endpoint:** `POST /api/v1/environments`

**Request:**
```json
{
  "name": "production",
  "displayName": "Production",
  "orderIndex": 3,
  "config": {
    "deploymentTimeout": 600,
    "healthCheckInterval": 30
  },
  "requiredApprovals": 2,
  "requireSod": true,
  "promotionPolicy": "default"
}
```

**Response:** `201 Created`
```json
{
  "id": "uuid",
  "name": "production",
  "displayName": "Production",
  "orderIndex": 3,
  "isProduction": true,
  "requiredApprovals": 2,
  "requireSeparationOfDuties": true,
  "createdAt": "2026-01-10T14:23:45Z"
}
```

### List Environments

**Endpoint:** `GET /api/v1/environments`

**Query Parameters:**
- `includeState` (boolean): Include current release state

**Response:** `200 OK`
```json
[
  {
    "id": "uuid",
    "name": "development",
    "displayName": "Development",
    "orderIndex": 1,
    "currentRelease": {
      "id": "release-uuid",
      "name": "myapp-v2.3.1",
      "deployedAt": "2026-01-09T10:00:00Z"
    }
  }
]
```

### Get Environment

**Endpoint:** `GET /api/v1/environments/{id}`

**Response:** `200 OK` - Full environment details

### Update Environment

**Endpoint:** `PUT /api/v1/environments/{id}`

**Request:** Partial environment object

**Response:** `200 OK` - Updated environment

### Delete Environment

**Endpoint:** `DELETE /api/v1/environments/{id}`

**Response:** `200 OK`
```json
{ "deleted": true }
```

---

## Freeze Window Endpoints

### Create Freeze Window

**Endpoint:** `POST /api/v1/environments/{envId}/freeze-windows`

**Request:**
```json
{
  "start": "2026-01-15T00:00:00Z",
  "end": "2026-01-20T00:00:00Z",
  "reason": "Holiday freeze",
  "exceptions": ["user-uuid-1", "user-uuid-2"]
}
```

**Response:** `201 Created`
```json
{
  "id": "uuid",
  "environmentId": "env-uuid",
  "start": "2026-01-15T00:00:00Z",
  "end": "2026-01-20T00:00:00Z",
  "reason": "Holiday freeze",
  "createdBy": "user-uuid"
}
```

### List Freeze Windows

**Endpoint:** `GET /api/v1/environments/{envId}/freeze-windows`

**Query Parameters:**
- `active` (boolean): Filter to active freeze windows only

**Response:** `200 OK` - Array of freeze windows

### Delete Freeze Window

**Endpoint:** `DELETE /api/v1/environments/{envId}/freeze-windows/{windowId}`

**Response:** `200 OK`
```json
{ "deleted": true }
```

---

## Target Group Endpoints

### Create Target Group

**Endpoint:** `POST /api/v1/environments/{envId}/target-groups`

### List Target Groups

**Endpoint:** `GET /api/v1/environments/{envId}/target-groups`

### Get Target Group

**Endpoint:** `GET /api/v1/target-groups/{id}`

### Update Target Group

**Endpoint:** `PUT /api/v1/target-groups/{id}`

### Delete Target Group

**Endpoint:** `DELETE /api/v1/target-groups/{id}`

---

## Target Endpoints

### Create Target

**Endpoint:** `POST /api/v1/targets`

**Request:**
```json
{
  "environmentId": "env-uuid",
  "targetGroupId": "group-uuid",
  "name": "prod-web-01",
  "targetType": "docker_host",
  "connection": {
    "host": "192.168.1.100",
    "port": 2375,
    "tlsEnabled": true
  },
  "labels": {
    "role": "web",
    "datacenter": "us-east-1"
  },
  "deploymentDirectory": "/opt/deployments"
}
```

**Response:** `201 Created`
```json
{
  "id": "uuid",
  "name": "prod-web-01",
  "targetType": "docker_host",
  "healthStatus": "unknown",
  "createdAt": "2026-01-10T14:23:45Z"
}
```

### List Targets

**Endpoint:** `GET /api/v1/targets`

**Query Parameters:**
- `environmentId` (UUID): Filter by environment
- `targetType` (string): Filter by type (`docker_host`, `compose_host`, `ecs_service`, `nomad_job`)
- `labels` (JSON): Filter by labels
- `healthStatus` (string): Filter by health status

**Response:** `200 OK` - Array of targets

### Get Target

**Endpoint:** `GET /api/v1/targets/{id}`

### Update Target

**Endpoint:** `PUT /api/v1/targets/{id}`

### Delete Target

**Endpoint:** `DELETE /api/v1/targets/{id}`

### Trigger Health Check

**Endpoint:** `POST /api/v1/targets/{id}/health-check`

**Response:** `200 OK`
```json
{
  "status": "healthy",
  "message": "Docker daemon responding",
  "checkedAt": "2026-01-10T14:23:45Z"
}
```

### Get Version Sticker

**Endpoint:** `GET /api/v1/targets/{id}/sticker`

**Response:** `200 OK`
```json
{
  "releaseId": "uuid",
  "releaseName": "myapp-v2.3.1",
  "components": [
    {
      "componentId": "uuid",
      "componentName": "api",
      "digest": "sha256:abc123..."
    }
  ],
  "deployedAt": "2026-01-09T10:00:00Z",
  "deployedBy": "user-uuid"
}
```

### Check Drift

**Endpoint:** `GET /api/v1/targets/{id}/drift`

**Response:** `200 OK`
```json
{
  "hasDrift": true,
  "expected": { "releaseId": "uuid", "digest": "sha256:abc..." },
  "actual": { "digest": "sha256:def..." },
  "differences": [
    { "component": "api", "expected": "sha256:abc...", "actual": "sha256:def..." }
  ]
}
```

---

## See Also

- [Agents API](agents.md)
- [Environment Manager Module](../modules/environment-manager.md)
- [Agent Security](../security/agent-security.md)