List Images

Retrieve all Docker images in an environment

Overview

Fetch the list of Docker images available in a specified environment. Returns an empty array if no environment is specified or if the Docker daemon is unavailable.

Endpoint

GET /api/images?env={environmentId}

Query Parameters

env · integer · required

Environment ID to list images from. Required to return any results.

Authentication

Requires images:view permission for the specified environment.

Response

Returns an array of image objects:

[
  {
    "Id": "sha256:abc123...",
    "RepoTags": ["nginx:latest"],
    "RepoDigests": ["nginx@sha256:def456..."],
    "Created": 1709510400,
    "Size": 142000000,
    "VirtualSize": 142000000,
    "SharedSize": 0,
    "Labels": {
      "maintainer": "NGINX Docker Maintainers"
    },
    "Containers": 2
  }
]

Response Fields

Id · string

Unique image identifier (SHA256 hash)

RepoTags · string[]

Repository tags associated with the image

RepoDigests · string[]

Content-addressable digests

Created · integer

Unix timestamp when the image was created

Size · integer

Image size in bytes

VirtualSize · integer

Total size including shared layers

Containers · integer

Number of containers using this image

Error Responses

403 · object

Permission denied - user lacks images:view permission or environment access

{ "error": "Permission denied" }

404 · object

Environment not found

{ "error": "Environment not found" }

Implementation

export const GET: RequestHandler = async ({ url, cookies }) => {
  const auth = await authorize(cookies);
  
  const envId = url.searchParams.get('env');
  const envIdNum = envId ? parseInt(envId) : undefined;
  
  // Permission check with environment context
  if (auth.authEnabled && !await auth.can('images', 'view', envIdNum)) {
    return json({ error: 'Permission denied' }, { status: 403 });
  }
  
  // Early return if no environment specified
  if (!envIdNum) {
    return json([]);
  }
  
  try {
    const images = await listImages(envIdNum);
    return json(images);
  } catch (error) {
    if (error instanceof EnvironmentNotFoundError) {
      return json({ error: 'Environment not found' }, { status: 404 });
    }
    // Return empty array instead of error to allow UI to load
    return json([]);
  }
};

Usage Examples

Fetch Images for Environment

curl -X GET 'https://dockhand.example.com/api/images?env=1' \
  -H 'Cookie: session=...'

Filter Images in UI

const response = await fetch(`/api/images?env=${environmentId}`);
const images = await response.json();

const filteredImages = images.filter(img => 
  img.RepoTags?.some(tag => tag.includes('nginx'))
);

Related Operations

• Pull Image - Download images from registries
• Scan Image - Run vulnerability scans
• Push Image - Upload to registries
• Prune Images - Remove unused images

Notes

• Returns empty array on connection errors to prevent UI failures
• Requires valid environment ID to return results
• Enterprise users must have environment access permissions
• Images are fetched directly from Docker daemon via Docker API