Skip to main content

​
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 -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 -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
}

Build docs developers (and LLMs) love

Get started for freeTalk to us