Environments

REST API endpoints for managing Meshery environments

Environments represent deployment targets in Meshery, such as Kubernetes clusters or cloud provider accounts. They group connections and provide isolation for infrastructure resources.

List Environments

cURL

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/environments?orgID=YOUR_ORG_ID&page=0&pagesize=25"

Method: GET

Endpoint: /api/environments

Query Parameters

orgID · string · required

Organization ID to retrieve environments for (required for remote providers)

page · integer · default: "0"

Page number for pagination (0-indexed)

pagesize · integer · default: "20"

Number of environments per page

search · string

Search term for filtering environments by name

order · string

Field to order by (e.g., name, created_at, updated_at)

filter · string

JSON filter conditions

Response

page · integer

Current page number

page_size · integer

Number of items per page

total_count · integer

Total number of environments

environments · array

Array of environment objects

Show Environment Object

id · string

Unique environment identifier (UUID)

name · string

Environment name

description · string

Environment description

organization_id · string

Organization ID that owns this environment

created_at · string

Creation timestamp (ISO 8601)

updated_at · string

Last update timestamp (ISO 8601)

owner · string

User ID of the environment owner

Example Response:

{
  "page": 0,
  "page_size": 25,
  "total_count": 2,
  "environments": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Production",
      "description": "Production Kubernetes cluster",
      "organization_id": "org-123",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-02-20T14:45:00Z",
      "owner": "user-uuid"
    }
  ]
}

---

Get Environment by ID

cURL

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/environments/{id}?orgID=YOUR_ORG_ID"

Method: GET

Endpoint: /api/environments/{id}

Path Parameters

id · string · required

Environment ID (UUID)

Query Parameters

orgID · string

Organization ID (required for remote providers)

Response

Returns a single environment object with the same structure as the list response.

---

Create Environment

cURL

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging",
    "description": "Staging environment for testing",
    "organization_id": "org-123"
  }' \
  http://localhost:9081/api/environments

Method: POST

Endpoint: /api/environments

Request Body

name · string · required

Environment name

description · string

Environment description

organization_id · string · required

Organization ID that will own this environment

Response

Status: 201 Created

Returns the created environment object.

---

Update Environment

cURL

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Updated",
    "description": "Updated production environment"
  }' \
  http://localhost:9081/api/environments/{id}

Method: PUT

Endpoint: /api/environments/{id}

Path Parameters

id · string · required

Environment ID (UUID)

Request Body

name · string

Updated environment name

description · string

Updated environment description

Response

Status: 200 OK

Returns the updated environment object.

---

Delete Environment

cURL

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/environments/{id}

Method: DELETE

Endpoint: /api/environments/{id}

Path Parameters

id · string · required

Environment ID (UUID)

Response

Status: 200 OK

Returns the deleted environment object.

---

Get Environment Connections

cURL

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:9081/api/environments/{environmentID}/connections?page=0&pagesize=25"

Method: GET

Endpoint: /api/environments/{environmentID}/connections

Path Parameters

environmentID · string · required

Environment ID (UUID)

Query Parameters

page · integer · default: "0"

Page number

pagesize · integer · default: "20"

Page size

search · string

Search term

order · string

Order by field

filter · string

Filter conditions: {"assigned": true/false, "deleted_at": true/false}

Response

Returns a paginated list of connections assigned to this environment.

Example Response:

{
  "page": 0,
  "page_size": 25,
  "total_count": 1,
  "connections": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "prod-cluster-1",
      "kind": "kubernetes",
      "type": "platform",
      "sub_type": "management",
      "status": "connected"
    }
  ]
}

---

Add Connection to Environment

cURL

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/environments/{environmentID}/connections/{connectionID}

Method: POST

Endpoint: /api/environments/{environmentID}/connections/{connectionID}

Path Parameters

environmentID · string · required

Environment ID (UUID)

connectionID · string · required

Connection ID to add (UUID)

Response

Status: 200 OK

Returns the environment-connection mapping object.

---

Remove Connection from Environment

cURL

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:9081/api/environments/{environmentID}/connections/{connectionID}

Method: DELETE

Endpoint: /api/environments/{environmentID}/connections/{connectionID}

Path Parameters

environmentID · string · required

Environment ID (UUID)

connectionID · string · required

Connection ID to remove (UUID)

Response

Status: 200 OK

Returns the removed environment-connection mapping.

---

Error Codes

400 Bad Request · error

Invalid request parameters or malformed JSON

401 Unauthorized · error

Missing or invalid authentication token

404 Not Found · error

Environment not found

500 Internal Server Error · error

Server error occurred