Skip to main content
GET
/
api
/
environments
List Environments
curl --request GET \
  --url https://api.example.com/api/environments
{
  "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

​
id
number
required
Unique identifier for the environment
​
name
string
required
Display name of the environment
​
host
string
Hostname or IP address for remote Docker connections (required for direct and hawser-standard types)
​
port
number
default:"2375"
Port number for Docker API connection
​
protocol
string
default:"http"
Connection protocol: http or https
​
connectionType
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
​
socketPath
string
default:"/var/run/docker.sock"
Unix socket path (used when connectionType is socket)
​
tlsCa
string
TLS Certificate Authority (CA) certificate in PEM format
​
tlsCert
string
TLS client certificate in PEM format
​
tlsKey
string
TLS client private key in PEM format
​
tlsSkipVerify
boolean
default:"false"
Skip TLS certificate verification (insecure, not recommended for production)
​
hawserToken
string
Authentication token for hawser-standard connections
​
hawserLastSeen
string
ISO 8601 timestamp of last connection from Hawser Edge agent
​
hawserAgentId
string
Unique identifier of the connected Hawser Edge agent
​
hawserAgentName
string
Name of the connected Hawser Edge agent
​
hawserVersion
string
Version of the Hawser agent software
​
hawserCapabilities
string[]
JSON array of agent capabilities: ["compose", "exec", "metrics"]
​
icon
string
default:"globe"
Icon identifier for UI display
​
collectActivity
boolean
default:"true"
Enable collection of container activity events
​
collectMetrics
boolean
default:"true"
Enable collection of host metrics
​
highlightChanges
boolean
default:"true"
Highlight recent changes in the UI
​
labels
string[]
Array of label strings for categorization (max 10 labels)
​
publicIp
string | null
Public IP address of the environment host
​
updateCheckEnabled
boolean
Whether automatic update checking is enabled
​
updateCheckAutoUpdate
boolean
Whether automatic updates are enabled
​
imagePruneEnabled
boolean
Whether automatic image pruning is enabled
​
timezone
string | null
Timezone identifier for the environment
​
createdAt
string
ISO 8601 timestamp of environment creation
​
updatedAt
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

​
403 Forbidden
object
User lacks environments:view permission
{
  "error": "Permission denied"
}
​
500 Internal Server Error
object
Failed to retrieve environments
{
  "error": "Failed to get environments"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us