Skip to main content

​
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'))
);

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us