Images API

The Images API allows you to upload, retrieve, and manage images for use in the application.

Endpoints

List Images

GET /api/v1/images

Retrieves a paginated list of all images.

Query Parameters

Parameter	Type	Description
skip	integer	Number of items to skip (for pagination)
limit	integer	Maximum number of items to return (for pagination)

Response

{
  "items": [
    {
      "id": 1,
      "original_filename": "example.jpg",
      "storage_filename": "a1b2c3d4e5f6.jpg",
      "mime_type": "image/jpeg",
      "size": 12345,
      "width": 800,
      "height": 600,
      "url_path": "/api/v1/images/a1b2c3d4e5f6.jpg",
      "uploaded_at": "2025-05-14T11:30:00"
    }
    // More images...
  ],
  "total": 42,
  "page": 1,
  "size": 20,
  "pages": 3
}

Get Image

GET /api/v1/images/{image_id}

Retrieves a specific image by ID.

Path Parameters

Parameter	Type	Description
image_id	integer	ID of the image to retrieve

Response

{
  "id": 1,
  "original_filename": "example.jpg",
  "storage_filename": "a1b2c3d4e5f6.jpg",
  "mime_type": "image/jpeg",
  "size": 12345,
  "width": 800,
  "height": 600,
  "url_path": "/api/v1/images/a1b2c3d4e5f6.jpg",
  "uploaded_at": "2025-05-14T11:30:00"
}

Upload Image

POST /api/v1/images

Uploads a new image.

Request

The request should be a multipart/form-data request with a file field named file.

Response

{
  "id": 1,
  "url_path": "/api/v1/images/a1b2c3d4e5f6.jpg",
  "original_filename": "example.jpg",
  "mime_type": "image/jpeg",
  "size": 12345,
  "width": 800,
  "height": 600
}

Delete Image

DELETE /api/v1/images/{image_id}

Deletes a specific image by ID.

Path Parameters

Parameter	Type	Description
image_id	integer	ID of the image to delete

Response

{
  "id": 1,
  "original_filename": "example.jpg",
  "storage_filename": "a1b2c3d4e5f6.jpg",
  "mime_type": "image/jpeg",
  "size": 12345,
  "width": 800,
  "height": 600,
  "url_path": "/api/v1/images/a1b2c3d4e5f6.jpg",
  "uploaded_at": "2025-05-14T11:30:00"
}

Error Responses

400 Bad Request

Returned when the request is invalid, such as when uploading an unsupported file type.

{
  "detail": "Invalid file type. Allowed types: image/jpeg, image/png, image/gif, image/webp, image/svg+xml"
}

404 Not Found

Returned when the requested image does not exist.

{
  "detail": "Image not found"
}

403 Forbidden

Returned when the user does not have permission to delete an image.

{
  "detail": "Not enough permissions"
}

Supported Image Types

The following image types are supported:

JPEG (image/jpeg)
PNG (image/png)
GIF (image/gif)
WebP (image/webp)
SVG (image/svg+xml)