Skip to main content
GET
/
api
/
stacks
curl -X GET "https://your-dockhand-instance.com/api/stacks?env=1" \
  -H "Cookie: auth_token=your_token"
[
  {
    "name": "my-app",
    "containers": ["abc123", "def456"],
    "containerDetails": [
      {
        "id": "abc123",
        "name": "my-app-web-1",
        "service": "web",
        "state": "running",
        "status": "Up 2 hours",
        "health": "healthy",
        "image": "nginx:latest",
        "ports": [
          {
            "publicPort": 8080,
            "privatePort": 80,
            "type": "tcp",
            "display": "8080:80/tcp"
          }
        ],
        "networks": [
          {
            "name": "my-app_default",
            "ipAddress": "172.18.0.2"
          }
        ],
        "volumeCount": 1,
        "restartCount": 0,
        "created": 1709568000
      }
    ],
    "status": "running",
    "sourceType": "internal"
  },
  {
    "name": "database",
    "containers": [],
    "containerDetails": [],
    "status": "created",
    "sourceType": "git"
  }
]

Query Parameters

env
string
required
Environment ID to list stacks from

Response

Returns an array of compose stack objects.
name
string
Stack name
containers
array
Array of container IDs in the stack
containerDetails
array
Detailed information about each container
status
string
Overall stack status: running, stopped, partial, or created
sourceType
string
Stack source type: internal, git, or external

Response Behavior

  • Returns an empty array if no environment ID is provided
  • Returns stacks from both Docker and database
  • Includes stacks that are currently stopped (status: created)
  • Silently returns empty array for offline environments
curl -X GET "https://your-dockhand-instance.com/api/stacks?env=1" \
  -H "Cookie: auth_token=your_token"
[
  {
    "name": "my-app",
    "containers": ["abc123", "def456"],
    "containerDetails": [
      {
        "id": "abc123",
        "name": "my-app-web-1",
        "service": "web",
        "state": "running",
        "status": "Up 2 hours",
        "health": "healthy",
        "image": "nginx:latest",
        "ports": [
          {
            "publicPort": 8080,
            "privatePort": 80,
            "type": "tcp",
            "display": "8080:80/tcp"
          }
        ],
        "networks": [
          {
            "name": "my-app_default",
            "ipAddress": "172.18.0.2"
          }
        ],
        "volumeCount": 1,
        "restartCount": 0,
        "created": 1709568000
      }
    ],
    "status": "running",
    "sourceType": "internal"
  },
  {
    "name": "database",
    "containers": [],
    "containerDetails": [],
    "status": "created",
    "sourceType": "git"
  }
]

Error Responses

error
string
Error message

403 Forbidden

Returned when the user lacks permission to view stacks or access the environment.

404 Not Found

Returned when the specified environment does not exist.

Permissions

Requires stacks:view permission for the specified environment.

Build docs developers (and LLMs) love