Environments

Manage environments (spaces) within your Release apps. Create, configure, and inspect ephemeral and permanent environments.

Base URL: https://api.release.com

---

List Environments

Retrieve all environments for a specific app.

Endpoint

GET /apps/{appId}/spaces

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app

Status Codes

Status	Description
200	Successfully retrieved environments
401	Unauthorized — invalid or missing authentication headers
404	App not found

Example Responses

200 OK

[
  {
    "id": "env789",
    "name": "feature-x",
    "type": "EPHEMERAL",
    "branch": "feature-branch",
    "status": "running"
  }
]

---

Get Environment

Retrieve details for a specific environment.

Endpoint

GET /apps/{appId}/spaces/{envId}

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
envId	string (hashid)	Yes	The unique identifier of the environment

Status Codes

Status	Description
200	Successfully retrieved environment
401	Unauthorized — invalid or missing authentication headers
404	App or environment not found

Example Responses

200 OK

{
  "id": "env789",
  "name": "feature-x",
  "type": "EPHEMERAL",
  "branch": "feature-branch",
  "status": "running",
  "domain": "feature-x.example.release.com"
}

---

Create Environment

Create a new environment for a specific app.

Endpoint

POST /apps/{appId}/spaces

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app

Request Body

Field	Type	Required	Description
name	string	Yes	Environment name
type	string	Yes	One of: EPHEMERAL, PERMANENT
initiation_type	string	No	One of: manual, automatic
branch	string	Yes	Git branch name
seconds_for_expiration	integer	No	TTL in seconds
services	object	No	Per-service branch overrides in the form {"service_name": {"branch": "branch-name"}}
domain	string	No	Custom domain

Example request body:

{
  "name": "feature-x",
  "type": "EPHEMERAL",
  "initiation_type": "manual",
  "branch": "feature-branch",
  "seconds_for_expiration": 604800,
  "services": {"backend": {"branch": "feature-branch"}},
  "domain": "custom.domain.com"
}

Status Codes

Status	Description
201	Environment created successfully
401	Unauthorized — invalid or missing authentication headers
404	App not found
422	Validation error — invalid or missing required fields

Example Responses

201 Created

{
  "id": "env789",
  "name": "feature-x",
  "type": "EPHEMERAL",
  "branch": "feature-branch",
  "status": "pending"
}

---

Get Environment Config

Retrieve the latest application configuration for a specific environment.

Endpoint

GET /apps/{appId}/spaces/{envId}/latest_config

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
envId	string (hashid)	Yes	The unique identifier of the environment

Status Codes

Status	Description
200	Successfully retrieved environment configuration
401	Unauthorized — invalid or missing authentication headers
404	App or environment not found

Example Responses

200 OK

{
  "config": "--- \nservices:\n  backend:\n    image: org/backend\n    ports:\n      - 3000\n"
}

---

Get Environment Variables

Retrieve the environment variables configuration for a specific environment.

Endpoint

GET /apps/{appId}/spaces/{envId}/latest_env_config

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
envId	string (hashid)	Yes	The unique identifier of the environment

Status Codes

Status	Description
200	Successfully retrieved environment variables
401	Unauthorized — invalid or missing authentication headers
404	App or environment not found

Example Responses

200 OK

{
  "env_config": "DATABASE_URL=postgres://...\nREDIS_URL=redis://...\n"
}

---

Update Environment Config

Update the application configuration for a specific environment.

Endpoint

POST /apps/{appId}/spaces/{envId}/serialized_configs

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
envId	string (hashid)	Yes	The unique identifier of the environment

Request Body

Field	Type	Required	Description
config	string	Yes	The application configuration YAML as a string

Example request body:

{
  "config": "--- \nservices:\n  backend:\n    image: org/backend\n    ports:\n      - 3000\n"
}

Status Codes

Status	Description
200	Environment configuration updated successfully
401	Unauthorized — invalid or missing authentication headers
404	App or environment not found
422	Validation error — invalid configuration

Example Responses

200 OK

{
  "config": "--- \nservices:\n  backend:\n    image: org/backend\n    ports:\n      - 3000\n"
}

---

List Instances

Retrieve Kubernetes pod details for a specific environment.

Endpoint

GET /apps/{appId}/spaces/{envId}/instances

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
envId	string (hashid)	Yes	The unique identifier of the environment

Status Codes

Status	Description
200	Successfully retrieved instances
401	Unauthorized — invalid or missing authentication headers
404	App or environment not found

Response Body

Field	Type	Description
name	string	Pod name
kind	string	Kubernetes resource kind
status.phase	string	Current pod phase
containers	array	List of containers in the pod
images	array	Container image references

Example Responses

200 OK

[
  {
    "name": "backend-6d4f5b8c9-x2k7m",
    "kind": "Pod",
    "status": {
      "phase": "Running"
    },
    "containers": ["backend"],
    "images": ["org/backend:latest"]
  }
]