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",
  "globalPrefix": "prod-",
  "provider": "aws",
  "region": "us-east-1",
  "domain": "example.com",
  "services": {
    "eks": {
      "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

This endpoint does not exist

GET /api/environments/:id/export was documented here and has never been implemented — the backend serves no such route and it returns 404. The wizard's "export configuration" is assembled in the browser from the environment the API already returns.

Note that the client-side export deliberately omits credential fields, so its absence from an exported document proves nothing about what is stored.

Environment fields

Only these fields are persisted. There is no configuration object — earlier versions of this page showed one, and it is silently discarded.

Field	Type	Notes
name	string	Required, 2–50 chars. Immutable — it names every generated Terraform resource, so changing it would make the next apply a destroy/recreate. A differing value on PUT is rejected with 400
globalPrefix	string	Required in practice; prefixes every resource name. Immutable, same reason
provider	enum	aws, azure, gcp, onpremise. Only aws generates a working stack today
region	string	Lowercase letters, digits and hyphens
domain	string	Optional, editable after creation. The domain the cluster publishes ArgoCD, Grafana and Prometheus on. Empty or omitted means no host-based ingresses are generated at all
services	object	Keyed by catalog service key — eks, vpc, rds, … The available keys and their fields come from the catalog, not from a fixed list here
terraformBackend	object	S3 state backend; created via POST /environments/terraform-backend/create
gitRepository	object	url, branch and the deploy key. The private key is AES-256-GCM encrypted at rest and never returned
cloudCredentialId	uuid	Which stored credential to use

The service key is eks, not kubernetes

Earlier examples on this page used services.kubernetes. The catalog's AWS keys are aurora, cloudfront, ecr, eks, elasticache, lambda, msk, opensearch, rds, route53, s3, sns, sqs, vpc, waf. A key the catalog does not know is stored but generates nothing.

domain is validated the same way on both sides

The backend accepts DNS labels only — at least two, alphabetic TLD, 253 characters maximum — and the wizard uses an identical pattern, so it cannot offer a value the API rejects. "" is accepted and means "no host-based ingresses".

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

The column accepts pending, deploying, running, stopped, failed and destroyed.

Status is not tracked yet

Every environment is created as pending and nothing transitions it — OpenPrime does not currently observe the state of the infrastructure it generates, so this field says nothing about whether a deployment succeeded. Treat it as reserved. Deployment status and drift detection are tracked as OP-187.