List Containers

Retrieve a list of Docker containers from a specific environment

List Containers

GET /api/containers?env=1&all=true

Retrieves a list of containers from the specified environment. Requires an environment ID to be provided.

Query Parameters

env · string · required

The environment ID from which to list containers. This parameter is required.

all · boolean · default: "true"

Whether to show all containers (including stopped ones). Defaults to true if not specified.

Response

Returns an array of container objects.

containers · array

Array of container objects with the following properties:

id · string

Container ID

name · string

Container name

image · string

Image used by the container

state · string

Current state of the container (e.g., “running”, “exited”, “paused”)

status · string

Human-readable status string

Error Responses

error · string

Error message if the request fails

Status Codes:

• 200 - Success
• 403 - Permission denied or environment access denied
• 404 - Environment not found

Example

curl

curl -X GET "https://your-dockhand.com/api/containers?env=1&all=true" \
  -H "Cookie: session=your-session-cookie"

Response Example

[
  {
    "id": "abc123def456",
    "name": "my-app",
    "image": "nginx:latest",
    "state": "running",
    "status": "Up 2 hours"
  },
  {
    "id": "xyz789ghi012",
    "name": "database",
    "image": "postgres:15",
    "state": "exited",
    "status": "Exited (0) 5 minutes ago"
  }
]

Create Container

POST /api/containers?env=1

Creates a new container in the specified environment. If the image is not available locally, it will be automatically pulled.

Query Parameters

env · string · required

The environment ID where the container will be created.

Request Body

image · string · required

The Docker image to use for the container (e.g., “nginx:latest”)

name · string

Name for the container

startAfterCreate · boolean · default: "false"

Whether to automatically start the container after creation

env · array

Array of environment variables in the format [“KEY=value”]

ports · object

Port bindings object mapping container ports to host ports

volumes · object

Volume bindings object

labels · object

Labels to attach to the container

Response

success · boolean

Whether the container was created successfully

id · string

The ID of the created container

imagePulled · boolean

Whether the image was pulled automatically

Error Responses

error · string

Error message if the request fails

details · string

Additional error details

Status Codes:

• 200 - Container created successfully
• 403 - Permission denied or environment access denied
• 500 - Failed to create container or pull image

Example

curl

curl -X POST "https://your-dockhand.com/api/containers?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "image": "nginx:latest",
    "name": "my-nginx",
    "startAfterCreate": true,
    "ports": {
      "80/tcp": [{"HostPort": "8080"}]
    }
  }'

Response Example

{
  "success": true,
  "id": "abc123def456789",
  "imagePulled": true
}