List Environments

curl --request GET \
  --url https://api.example.com/api/environments

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/environments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/environments"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/environments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "name": "<string>",
  "host": "<string>",
  "port": 123,
  "protocol": "<string>",
  "connectionType": "<string>",
  "socketPath": "<string>",
  "tlsCa": "<string>",
  "tlsCert": "<string>",
  "tlsKey": "<string>",
  "tlsSkipVerify": true,
  "hawserToken": "<string>",
  "hawserLastSeen": "<string>",
  "hawserAgentId": "<string>",
  "hawserAgentName": "<string>",
  "hawserVersion": "<string>",
  "hawserCapabilities": [
    "<string>"
  ],
  "icon": "<string>",
  "collectActivity": true,
  "collectMetrics": true,
  "highlightChanges": true,
  "labels": [
    "<string>"
  ],
  "publicIp": {},
  "updateCheckEnabled": true,
  "updateCheckAutoUpdate": true,
  "imagePruneEnabled": true,
  "timezone": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "403 Forbidden": {},
  "500 Internal Server Error": {}
}

GET

api

environments

List Environments

curl --request GET \
  --url https://api.example.com/api/environments

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/environments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/environments"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/environments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "id": 123,
  "name": "<string>",
  "host": "<string>",
  "port": 123,
  "protocol": "<string>",
  "connectionType": "<string>",
  "socketPath": "<string>",
  "tlsCa": "<string>",
  "tlsCert": "<string>",
  "tlsKey": "<string>",
  "tlsSkipVerify": true,
  "hawserToken": "<string>",
  "hawserLastSeen": "<string>",
  "hawserAgentId": "<string>",
  "hawserAgentName": "<string>",
  "hawserVersion": "<string>",
  "hawserCapabilities": [
    "<string>"
  ],
  "icon": "<string>",
  "collectActivity": true,
  "collectMetrics": true,
  "highlightChanges": true,
  "labels": [
    "<string>"
  ],
  "publicIp": {},
  "updateCheckEnabled": true,
  "updateCheckAutoUpdate": true,
  "imagePruneEnabled": true,
  "timezone": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "403 Forbidden": {},
  "500 Internal Server Error": {}
}

Description

Retrieves a list of all Docker environments. In Enterprise mode with authentication enabled, results are filtered based on the user’s accessible environments unless the user is an admin.

Authentication

Requires environments:view permission when authentication is enabled.

Response

Returns an array of environment objects with parsed labels, public IPs, and additional settings.

Environment Object

number

required

Unique identifier for the environment

string

required

Display name of the environment

string

Hostname or IP address for remote Docker connections (required for direct and hawser-standard types)

number

default:"2375"

Port number for Docker API connection

string

default:"http"

Connection protocol: http or https

string

default:"socket"

Type of Docker connection:

socket - Local Unix socket
direct - Direct TCP connection to Docker API
hawser-standard - HTTP proxy via Hawser agent
hawser-edge - WebSocket reverse proxy via Hawser agent

string

default:"/var/run/docker.sock"

Unix socket path (used when connectionType is socket)

string

TLS Certificate Authority (CA) certificate in PEM format

string

TLS client certificate in PEM format

string

TLS client private key in PEM format

boolean

default:"false"

Skip TLS certificate verification (insecure, not recommended for production)

string

Authentication token for hawser-standard connections

string

ISO 8601 timestamp of last connection from Hawser Edge agent

string

Unique identifier of the connected Hawser Edge agent

string

Name of the connected Hawser Edge agent

string

Version of the Hawser agent software

string[]

JSON array of agent capabilities: ["compose", "exec", "metrics"]

string

default:"globe"

Icon identifier for UI display

boolean

default:"true"

Enable collection of container activity events

boolean

default:"true"

Enable collection of host metrics

boolean

default:"true"

Highlight recent changes in the UI

string[]

Array of label strings for categorization (max 10 labels)

string | null

Public IP address of the environment host

boolean

Whether automatic update checking is enabled

boolean

Whether automatic updates are enabled

boolean

Whether automatic image pruning is enabled

string | null

Timezone identifier for the environment

string

ISO 8601 timestamp of environment creation

string

ISO 8601 timestamp of last update

Example Response

[
  {
    "id": 1,
    "name": "Production",
    "host": "prod-docker.example.com",
    "port": 2376,
    "protocol": "https",
    "connectionType": "direct",
    "socketPath": "/var/run/docker.sock",
    "tlsCa": "-----BEGIN CERTIFICATE-----\n...",
    "tlsCert": "-----BEGIN CERTIFICATE-----\n...",
    "tlsKey": "-----BEGIN PRIVATE KEY-----\n...",
    "tlsSkipVerify": false,
    "icon": "server",
    "collectActivity": true,
    "collectMetrics": true,
    "highlightChanges": true,
    "labels": ["production", "us-east-1"],
    "publicIp": "203.0.113.42",
    "updateCheckEnabled": true,
    "updateCheckAutoUpdate": false,
    "imagePruneEnabled": true,
    "timezone": "America/New_York",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:22:00.000Z"
  },
  {
    "id": 2,
    "name": "Local Development",
    "connectionType": "socket",
    "socketPath": "/var/run/docker.sock",
    "port": 2375,
    "protocol": "http",
    "tlsSkipVerify": false,
    "icon": "laptop",
    "collectActivity": true,
    "collectMetrics": true,
    "highlightChanges": true,
    "labels": ["development"],
    "publicIp": null,
    "updateCheckEnabled": false,
    "updateCheckAutoUpdate": false,
    "imagePruneEnabled": false,
    "timezone": null,
    "createdAt": "2024-01-10T09:15:00.000Z",
    "updatedAt": "2024-01-10T09:15:00.000Z"
  },
  {
    "id": 3,
    "name": "Edge Server",
    "connectionType": "hawser-edge",
    "port": 2375,
    "protocol": "http",
    "socketPath": "/var/run/docker.sock",
    "tlsSkipVerify": false,
    "icon": "cloud",
    "collectActivity": true,
    "collectMetrics": true,
    "highlightChanges": true,
    "labels": ["edge", "remote"],
    "publicIp": null,
    "updateCheckEnabled": false,
    "updateCheckAutoUpdate": false,
    "imagePruneEnabled": false,
    "timezone": "UTC",
    "hawserLastSeen": "2024-01-20T15:30:00.000Z",
    "hawserAgentId": "edge-agent-001",
    "hawserAgentName": "Edge Agent 1",
    "hawserVersion": "1.2.0",
    "hawserCapabilities": ["compose", "exec", "metrics"],
    "createdAt": "2024-01-18T12:00:00.000Z",
    "updatedAt": "2024-01-20T15:30:00.000Z"
  }
]

Error Responses

object

User lacks environments:view permission

{
  "error": "Permission denied"
}

object

Failed to retrieve environments

{
  "error": "Failed to get environments"
}

API Overview

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

List Environments

Description

Authentication

Response

Environment Object

Example Response

Error Responses

​Description

​Authentication

​Response

​Environment Object

​Example Response

​Error Responses

Description

Authentication

Response

Environment Object

Example Response

Error Responses