Environments API

Manage infrastructure environments through the REST API.

List Environments

Get all environments for the authenticated user.

GET /api/environments
Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
provider	string	Filter by provider (aws, azure, gcp)
status	string	Filter by status
sort	string	Sort field (created_at, name)
order	string	Sort order (asc, desc)

Response 200 OK:

{
  "data": [
    {
      "id": "uuid",
      "name": "production-us-east",
      "provider": "aws",
      "region": "us-east-1",
      "status": "active",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

Create Environment

Create a new infrastructure environment.

POST /api/environments
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "production-us-east",
  "provider": "aws",
  "region": "us-east-1",
  "configuration": {
    "tags": {
      "Environment": "production",
      "Team": "platform"
    }
  },
  "services": {
    "kubernetes": {
      "enabled": true,
      "clusterName": "prod-cluster",
      "version": "1.28",
      "nodeGroups": [
        {
          "name": "general",
          "instanceType": "t3.large",
          "desiredSize": 5,
          "minSize": 2,
          "maxSize": 10
        }
      ]
    }
  },
  "helmCharts": {
    "nginx-ingress": {
      "enabled": true
    },
    "cert-manager": {
      "enabled": true,
      "customValues": true,
      "values": "installCRDs: true"
    }
  }
}

Response 201 Created:

{
  "data": {
    "id": "uuid",
    "name": "production-us-east",
    "provider": "aws",
    "region": "us-east-1",
    "status": "draft",
    "configuration": { ... },
    "services": { ... },
    "helmCharts": { ... },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

400 Bad Request - Validation error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "name",
        "message": "Name must be lowercase alphanumeric with hyphens"
      }
    ]
  }
}

409 Conflict - Duplicate name:

{
  "error": {
    "code": "CONFLICT",
    "message": "Environment with this name already exists"
  }
}

Get Environment

Retrieve a single environment by ID.

GET /api/environments/:id
Authorization: Bearer <access_token>

Response 200 OK:

{
  "data": {
    "id": "uuid",
    "name": "production-us-east",
    "provider": "aws",
    "region": "us-east-1",
    "status": "active",
    "configuration": {
      "tags": { ... },
      "networking": { ... }
    },
    "services": {
      "kubernetes": { ... },
      "database": { ... }
    },
    "helmCharts": {
      "nginx-ingress": { ... }
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T00:00:00Z"
  }
}

Errors:

404 Not Found:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Environment not found"
  }
}

Update Environment

Update an existing environment.

PUT /api/environments/:id
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "production-us-east",
  "services": {
    "kubernetes": {
      "enabled": true,
      "nodeGroups": [
        {
          "name": "general",
          "desiredSize": 10
        }
      ]
    }
  }
}

Response 200 OK:

{
  "data": {
    "id": "uuid",
    "name": "production-us-east",
    ...
  }
}

Delete Environment

Delete an environment.

DELETE /api/environments/:id
Authorization: Bearer <access_token>

Response 204 No Content

Errors:

404 Not Found:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Environment not found"
  }
}

Generate Code

Generate infrastructure code for an environment.

POST /api/environments/:id/generate
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "format": "terraform",
  "options": {
    "includeBackend": true,
    "includeHelm": true,
    "includeArgoCD": false
  }
}

Parameters:

Parameter	Type	Description
format	string	Output format: terraform, helm, argocd
options.includeBackend	boolean	Include Terraform backend config
options.includeHelm	boolean	Include Helm values files
options.includeArgoCD	boolean	Include ArgoCD applications

Response 200 OK:

{
  "data": {
    "files": {
      "main.tf": "terraform {\n  ...\n}",
      "variables.tf": "variable \"cluster_name\" {\n  ...\n}",
      "outputs.tf": "output \"cluster_endpoint\" {\n  ...\n}"
    },
    "helm": {
      "nginx-ingress-values.yaml": "controller:\n  replicaCount: 2"
    }
  }
}

Export Environment

Export environment configuration as JSON or YAML.

GET /api/environments/:id/export?format=yaml
Authorization: Bearer <access_token>

Query Parameters:

Parameter	Type	Description
format	string	Export format: json, yaml (default: json)

Response 200 OK:

name: production-us-east
provider: aws
region: us-east-1
services:
  kubernetes:
    enabled: true
    clusterName: prod-cluster
    version: "1.28"

Clone Environment

Create a copy of an existing environment.

POST /api/environments/:id/clone
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "staging-us-east",
  "region": "us-east-2"
}

Response 201 Created:

{
  "data": {
    "id": "new-uuid",
    "name": "staging-us-east",
    "provider": "aws",
    "region": "us-east-2",
    ...
  }
}

Validation

Environment Name

• Must start with lowercase letter
• Only lowercase letters, numbers, and hyphens
• 3-63 characters
• Pattern: ^[a-z][a-z0-9-]{2,62}$

Provider Values

• aws
• azure
• gcp
• onpremise

Status Values

• draft - Being configured
• active - Ready for deployment
• deployed - Infrastructure provisioned
• archived - Soft deleted