git.stella-ops.org/docs/modules/release-orchestrator/api/environments.md

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 Related Modules: Environment Manager, Agents

Runtime note: environment APIs are documented here; controller implementation sequencing is tracked in ../promotion-runtime-gap-closure-plan.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:

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

Response: 201 Created

{
  "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

[
  {
    "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

{ "deleted": true }

---

Freeze Window Endpoints

Create Freeze Window

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

Request:

{
  "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

{
  "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

{ "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:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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
• Environment Manager Module
• Agent Security