Skip to content

API Reference

Jump to bottom
Durand edited this page Dec 1, 2025 · 1 revision

💻 API Reference: Detailed Endpoints and Schemas

DeepDock exposes a comprehensive REST API (built with FastAPI) to manage the lifecycle of your GPU-aware Docker containers. This reference provides an overview of available endpoints, methods, and a brief description of their functionality.

🔗 Live Documentation (Swagger UI)

For detailed request/response schemas, validation rules, and the ability to test endpoints directly, please consult the automatic interactive documentation provided by FastAPI (Swagger UI):

URL: http://127.0.0.1:8000/docs

1. Image Management Endpoints

These endpoints handle operations related to Docker images, such as pulling new ones from registries, listing available images on the host, and deleting local images.

Method Path Description
GET /images Lists all container images currently stored on the host system, including details like ID, tag, digest, and size.
POST /images Initiates the pulling of a Docker image from a specified registry (e.g., Docker Hub). Requires repo_tag (e.g., nvidia/cuda:latest) in the request body.
DELETE /images/{image_ref} Deletes a local Docker image from the host by its short ID or tag. Uses force=True to handle dependencies.

GET /images

Response Schema

Returns a JSON object containing the count and a list of image details available on the host.

{
  "count": 2,
  "images": [
    {
      "id": "8aef630a54bc",
      "tag": "nvidia/cuda:12.6.3-cudnn-runtime-ubuntu24.04",
      "digest": "nvidia/cuda@sha256:8aef630a54bc5c5146ae5ce68e6af5caa3df0fb690bb91544175c91f307e4356",
      "size_mb": 2008.44
    },
    {
      "id": "739e0bde7baf",
      "tag": "nvidia/cuda:12.2.0-runtime-ubuntu22.04",
      "digest": "nvidia/cuda@sha256:739e0bde7bafdb2ed9057865f53085539f51cbf8bd6bf719f2e114bab321e70e",
      "size_mb": 1134.02
    }
  ]
}

POST /images (Pull Image)

Request Schema

The request body requires the full repository and tag string of the image to be pulled.

{
  "repo_tag": "nvidia/cuda:12.2.0-runtime-ubuntu20.04"
}

Response Schema

Returns confirmation details of the image successfully pulled.

{
  "message": "Image 'nvidia/cuda:12.2.0-runtime-ubuntu20.04' pulled successfully.",
  "id": "44fdb25dd06b",
  "tags": [
    "nvidia/cuda:12.2.0-runtime-ubuntu20.04"
  ],
  "size_mb": 1135.24
}

DELETE /images/{image_ref}

Response Schema

Returns a confirmation message that the image has been successfully removed.

{
  "message": "Image '44fdb25dd06b' removed successfully."
}

2. Container Lifecycle Management Endpoints

This is the primary group of endpoints for managing running and stopped containers, essential for multi-user environments.

Method Path Description
GET /containers Lists all containers belonging to the current project namespace, returning a list of parsed container information.
POST /containers/create Creates a new GPU-enabled container instance. The request body requires name, image, user_name, password, and optional fields for env and gpu_ids (list of integers).
POST /containers/create Creates a new GPU-enabled container instance. The request body requires name, image, user_name, password, and optional fields for env and gpu_ids (list of integers).
POST /containers/{name}/start Starts a container identified by its unique name.
POST /containers/{name}/stop Gracefully stops a running container identified by its unique name.
POST /containers/{name}/restart Restarts a container identified by its unique name.
DELETE /containers/{name} Removes a container instance from the system. Accepts an optional query parameter force (boolean) to forcibly remove running containers.

GET /containers

Response Schema:

Returns a list of all containers managed by the DeepDock project namespace.

{
  "containers": [
    {
      "id": "e61c9453638e",
      "name": "container_1",
      "status": "exited",
      "image": [
        "nvidia/cuda:12.6.3-cudnn-runtime-ubuntu24.04"
      ],
      "created": "2025-11-28T14:33:52.180994982Z",
      "ssh-port": null,
      "gpus": [
        "0"
      ]
    },
    {
      "id": "4e191151c508",
      "name": "container_2",
      "status": "exited",
      "image": [
        "nvidia/cuda:12.6.3-cudnn-runtime-ubuntu24.04"
      ],
      "created": "2025-11-28T14:30:37.956854109Z",
      "ssh-port": null,
      "gpus": [
        "0"
      ]
    }
  ]
}

POST /containers/create

Request Schema

The request body defines the configuration for the new container, including user credentials and GPU assignment.

{
  "name": "my-custom-container",
  "image": "nvidia/cuda:12.6.3-cudnn-runtime-ubuntu24.04",
  "user_name": "deepdock_user",
  "password": "secure_password_123",
  "gpu_ids": [0]
}

Response Schema

Returns the details of the container successfully created, including its internal ID and the assigned external SSH port.

{
  "message": "container created",
  "id": "1bb0e524d7f0",
  "name": "name",
  "ssh-port": 22000
}

POST /containers/{name}/start

Response Schema:

Returns a confirmation message that the specified container has been started successfully.

{
  "message": "container '{name}' started"
}

POST /containers/{name}/stop

Response Schema:

Returns a confirmation message that the specified container has been stopped successfully.

{
  "message": "container '{name}' stopped"
}

POST /containers/{name}/restart

Response Schema:

Returns a confirmation message that the specified container has been restarted successfully.

{
  "message": "container '{name}' restarted"
}

DELETE /containers/{name}

Response Schema:

Returns a confirmation message that the specified container has been removed successfully.

{
  "message": "container '{name}' removed"
}

3. Host and GPU Monitoring Endpoints

These endpoints provide real-time information about the host system's hardware status (CPU, RAM) and detailed NVIDIA GPU utilization metrics, primarily sourced via NVML.

Method Path Description
GET /metrics Retrieves general host metrics, including the number of GPUs detected, total/available RAM (MB), and physical CPU core count.
GET /metrics/gpus Lists all detected NVIDIA GPUs along with detailed, time-stamped metrics (memory usage, utilization, temperature) collected over a period for time-series monitoring.

GET /metrics

Response Schema:

Returns general host information about available resources.

{
  "gpu_count": 1,
  "ram_total_mb": 20006,
  "ram_available_mb": 17092,
  "cpu_cores": 4
}

GET /metrics/gpus

Response Schema:

Returns detailed time-series metrics for all detected GPUs, keyed by GPU ID (e.g., "0" for the first GPU). Each key contains an array of metrics captured at various timestamps.

{
  "0": [
    {
      "timestamp": "2025-12-01T19:02:30.437763",
      "memory_used": 2928.9218363242576,
      "utilization": 13.742574257425742,
      "power_usage": 20.23792079207921,
      "temperature": 50.0,
      "fan_speed": 0.0
    },
    {
      "timestamp": "2025-12-01T19:02:40.539339",
      "memory_used": 2941.695969987624,
      "utilization": 16.0,
      "power_usage": 20.43307920792079,
      "temperature": 50.04950495049505,
      "fan_speed": 0.0
    },
    {
      "timestamp": "2025-12-01T19:02:50.643242",
      "memory_used": 2942.235264542079,
      "utilization": 8.623762376237623,
      "power_usage": 20.358633663366337,
      "temperature": 50.9009900990099,
      "fan_speed": 0.0
    }
  ]
}

Clone this wiki locally