API Overview

Introduction

The Dockhand API provides programmatic access to all Docker management functionality. Use it to automate container operations, manage stacks, configure environments, and integrate Dockhand into your workflows.

Base URL

All API requests are made to your Dockhand instance:

http://your-dockhand-instance:3000/api

For production deployments with SSL:

https://your-dockhand-instance.com/api

The API is served from the same domain as the web interface on the /api path.

Request Format

HTTP Methods

The API uses standard HTTP methods:

GET - Retrieve resources
POST - Create resources or trigger actions
PUT / PATCH - Update resources
DELETE - Remove resources

Content Type

All requests with a body must use application/json:

Content-Type: application/json

Query Parameters

Many endpoints accept query parameters for filtering and configuration:

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

env

integer

Environment ID to scope the request to a specific Docker environment

Response Format

Success Responses

Successful responses return JSON with appropriate HTTP status codes:

{
  "success": true,
  "id": "abc123"
}

Resource Lists

List endpoints return arrays:

[
  {
    "id": "container1",
    "name": "web-app",
    "status": "running"
  },
  {
    "id": "container2",
    "name": "database",
    "status": "running"
  }
]

Error Responses

Errors return JSON with an error message and appropriate status code:

{
  "error": "Permission denied"
}

HTTP Status Codes

Dockhand uses standard HTTP status codes:

200

Request succeeded

201

Created

Resource created successfully

400

Bad Request

Invalid request parameters or body

401

Unauthorized

Authentication required or session expired

403

Forbidden

Insufficient permissions or enterprise license required

404

Not Found

Resource or environment not found

429

Too Many Requests

Rate limit exceeded (login attempts)

500

Internal Server Error

Server error or Docker operation failed

Error Handling

Standard Error Format

All errors follow a consistent format:

{
  "error": "Container not found",
  "details": "No container with ID abc123"
}

error

string

required

Human-readable error message

details

string

Additional error details when available

Common Error Scenarios

Docker Connection Errors

When a Docker environment is offline or unreachable, most endpoints return empty arrays or specific error messages:

{
  "error": "Environment not found"
}

Permission Errors

When authentication is enabled and the user lacks required permissions:

{
  "error": "Permission denied"
}

Validation Errors

When request parameters are invalid:

{
  "error": "Stack name is required"
}

API Resources

The Dockhand API provides access to:

Core Resources

Containers - Create, start, stop, and manage Docker containers
Images - Pull, build, tag, and inspect Docker images
Networks - Manage Docker networks
Volumes - Create and manage Docker volumes
Stacks - Deploy and manage Docker Compose stacks

Management

Environments - Configure remote Docker connections
Users - Manage user accounts (when authentication is enabled)
Roles - Configure RBAC permissions (Enterprise)
Settings - Application configuration and preferences

Git Integration

Git Repositories - Connect to Git repositories for automated deployments
Git Stacks - Deploy stacks from Git with automatic sync
Webhooks - Configure automated deployments via Git webhooks

Monitoring

Events - Stream Docker events in real-time
Stats - Container and system metrics
Health - System health checks
Audit Logs - View security audit logs (Enterprise)

Streaming Responses

Some endpoints use Server-Sent Events (SSE) for real-time updates:

Container stats streaming
Build output
Stack deployment progress
Docker events

Example: Streaming Events

curl -N -H "Cookie: session=..." \
  http://localhost:3000/api/events?env=1

Response:

event: container-start
data: {"id":"abc123","name":"web-app"}

event: container-die
data: {"id":"def456","name":"worker"}

Streaming endpoints require maintaining an open connection and return Content-Type: text/event-stream.

Rate Limiting

Rate limiting is applied to authentication endpoints:

Login attempts: 5 failed attempts per IP/username combination
Lockout duration: Exponential backoff (5-60 seconds)

After 5 consecutive failed login attempts, you’ll receive a 429 status with a retry-after message.

Environment Context

Most Docker-related operations require an environment ID to specify which Docker daemon to target:

GET /api/containers?env=1
GET /api/stacks?env=2

env

integer

required

The ID of the Docker environment (1 for local, or remote environment IDs)

When no environment is configured, Dockhand connects to the local Docker daemon with env=1.

Pagination

Currently, the API does not implement pagination. All list endpoints return complete result sets.

For large deployments, consider filtering by environment or using query parameters to reduce response sizes.

Versioning

The API currently does not use versioning. Breaking changes are avoided, and new fields are added in a backward-compatible manner.

Example Requests

List Containers

curl -X GET "http://localhost:3000/api/containers?env=1" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Create Container

curl -X POST "http://localhost:3000/api/containers?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "my-nginx",
    "image": "nginx:latest",
    "startAfterCreate": true,
    "portBindings": {
      "80/tcp": [{"HostPort": "8080"}]
    }
  }'

List Stacks

curl -X GET "http://localhost:3000/api/stacks?env=1" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Deploy Stack

curl -X POST "http://localhost:3000/api/stacks?env=1" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "wordpress",
    "compose": "version: '3.8'\nservices:\n  wordpress:\n    image: wordpress:latest\n    ports:\n      - 8080:80",
    "start": true
  }'

Best Practices

Authentication

Always check if authentication is enabled via /api/auth/session
Obtain session cookies via /api/auth/login
Include session cookies in all subsequent requests
Handle 401 responses by redirecting to login

Error Handling

Always check HTTP status codes
Parse error messages from response JSON
Handle Docker connection errors gracefully
Implement retry logic for transient failures

Environment Management

Always specify the env parameter for Docker operations
Handle 404 errors when environments are deleted
Check environment health before operations
Cache environment IDs on the client side

Performance

Use streaming endpoints for long-running operations
Filter results using query parameters
Avoid polling - use event streams when available
Implement client-side caching for static data

Support

For API issues or questions:

Check the GitHub repository for known issues
Review the source code in src/routes/api/ for implementation details
Submit bug reports or feature requests via GitHub Issues

Container Management

Stack Management

Image Management

Network & Volume

Environment Management

Scheduling & Automation

​Introduction

​Base URL

​Request Format

​HTTP Methods

​Content Type

​Query Parameters

​Response Format

​Success Responses

​Resource Lists

​Error Responses

​HTTP Status Codes

​Error Handling

​Standard Error Format

​Common Error Scenarios

​Docker Connection Errors

​Permission Errors

​Validation Errors

​API Resources

​Core Resources

​Management

​Git Integration

​Monitoring

​Streaming Responses

​Example: Streaming Events

​Rate Limiting

​Environment Context

​Pagination

​Versioning

​Example Requests

​List Containers

​Create Container

​List Stacks

​Deploy Stack

​Best Practices

​Authentication

​Error Handling

​Environment Management

​Performance

​Support

Build docs developers (and LLMs) love

Introduction

Base URL

Request Format

HTTP Methods

Content Type

Query Parameters

Response Format

Success Responses

Resource Lists

Error Responses

HTTP Status Codes

Error Handling

Standard Error Format

Common Error Scenarios

Docker Connection Errors

Permission Errors

Validation Errors

API Resources

Core Resources

Management

Git Integration

Monitoring

Streaming Responses

Example: Streaming Events

Rate Limiting

Environment Context

Pagination

Versioning

Example Requests

List Containers

Create Container

List Stacks

Deploy Stack

Best Practices

Authentication

Error Handling

Environment Management

Performance

Support