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

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