API Reference

Pixelflare API - Version 1.0.0

The Pixelflare API provides full programmatic access to all features, so you can integrate image hosting, CDN delivery, and management into your own applications and workflows.

Quick Start

To upload an image via the API:

1. Authenticate: All API endpoints require authentication (see below)
2. Create an Image: POST to /images to get a signed upload URL
3. Upload File: PUT your image to the signed URL

Then, you'll be able to access your image via the CDN, with either:

• /{owner}/{album}/{filename}
• /{owner}/{album}/{filename}/{variant}
• /i/{image-id}

Try a test request, by running:

curl 'https://pixelflare.cc/api/v1/images?limit=1' --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Authentication

NOTE

Note that authentication options depend on your deployment configuration.

This API uses:

• Cloudflare Access: JWT-based authentication (if enabled)
• API Keys: Bearer token authentication for programmatic access (if enabled)

You can generate a key in the Pixelflare app at Settings > API Keys, or use the POST /keys endpoint.

CAUTION

Keep your API keys secure. They grant access to your account

Rate Limiting

Unless otherwise specified, the following rate limits apply:

• API endpoints: 100 requests/minute per user
• CDN endpoints: 1000 requests/minute per IP (does not apply to cached content)

You will receive HTTP 429 responses, along with a message when exceeding these limits.

NOTE

Rate limits are configurable by the server administrator, and may differ from the defaults listed here.

WARNING

Repeatedly exceeding rate limits by a significant margin may result in temporary or permanent bans.

Using the API docs

1. In the web app, create an API token with your desired scopes and expiry.
2. Then, under the "Authentication" section to the right, paste your token into the "Bearer" field
3. Choose your desired programming language, in the Client Library section (this will give you code snippets for making requests)
4. You will then be able to send test requests directly from the documentation interface, or copy the code snippets

Alternatively, you can download the OpenAPI Schema and import it into an Swagger-compatible API client of your choice (such as Postman, Insomnia, or Hoppscotch).

TIP

If you use Scalar, click here for a pre-configured instance!

Links

• App
• Documentation
• Source
• Bugs

Getting help

Support is offered to paying customers and GitHub Sponsors, who reach our via support@as93.net.

For all other users, please reference the docs, github repo and community forum.

Legal

Pixelflare is licensed under MIT © Alicia Sykes 2025

For terms, privacy policy, and security information, please see Legal Documents

IMPORTANT

The public instance does not allow for NSFW or adult content

API Overview

55 endpoints · 15 resource groups · 40 GET · 21 POST · 7 PATCH · 9 DELETE

Auto-generated Documentation

This documentation is automatically generated from the OpenAPI specification. For interactive testing, visit the API Playground.

Base URLs

• Production API: https://pixelflare.cc/api/v1
• Production API (alternate): https://api.pixelflare.cc/v1
• Local Development: http://localhost:8787/v1

Table of Contents

Media Management

• Images
• Albums
• Tags
• Favourites
• Events

Configuration

• Settings
• API Keys
• Backup
• Custom Domains
• Webhooks

Stats & Logs

• Analytics
• Audit Logs

Public

• Public Profiles

CDN

• Image Serving

Misc

• Status

---

Images

The /images endpoint covers everything from uploading, retrieving, updating, deleting, and managing image variants.

GET /images

Authentication Required

This endpoint requires authentication: Bearer

Returns a paginated list of images with optional filtering by album, tags, search terms, date range, and more. Returns 401 if unauthorized.

Parameters:

• limit (query) optional
  • Type: integer
  • Description: Number of images to return (max 200)
  • Example: 10
  • Default: 10
• cursor (query) optional
  • Type: string
  • Description: Pagination cursor from previous response
  • Example: img_xyz789
• album (query) optional
  • Type: string
  • Description: Filter by album slug
  • Example: vacation-2024
• tag (query) optional
  • Type: string
  • Description: Filter by tag(s) - comma-separated for AND logic
  • Example: nature,sunset
• search (query) optional
  • Type: string
  • Description: Search by filename, alt text, or tags
  • Example: sunset beach
• sort (query) optional
  • Type: "relevance" | "recent" | "bytes"
  • Description: Sort order: relevance (if searching), recent (newest first), or bytes (largest first)
  • Example: recent
  • Default: recent
• include_deleted (query) optional
  • Type: boolean
  • Description: Include soft-deleted images
  • Default: false
• is_favourited (query) optional
  • Type: boolean
  • Description: Filter by favourite status
  • Example: true
• from (query) optional
  • Type: string
  • Description: Filter by creation date (start, YYYY-MM-DD)
  • Example: 2024-01-01
• to (query) optional
  • Type: string
  • Description: Filter by creation date (end, YYYY-MM-DD)
  • Example: 2024-12-31

Responses:

200: Paginated list of images

Response 200:

• data required
  • Type: any[]
  • Description: Array of items in this page
• next_cursor required
  • Type: string
  • Description: Cursor for next page (null if no more pages)
  • Example: "img_xyz789"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images

Authentication Required

This endpoint requires authentication: Bearer

Creates a new image resource and returns a signed upload URL. The image file should be uploaded to the returned upload URL within 1 hour. Returns 401 if unauthorized.

Request Body:

• filename required
  • Type: string
  • Description: Your image filename with extension
  • Example: "sunset.jpg"
• content_type optional
  • Type: string
  • Description: MIME type - we'll detect it if you don't provide it
  • Example: "image/jpeg"
• size_bytes optional
  • Type: integer
  • Description: File size in bytes - max 100MB
  • Example: 1048576
• width optional
  • Type: integer
  • Description: Width in pixels - we'll extract this from your file
  • Example: 1920
• height optional
  • Type: integer
  • Description: Height in pixels - we'll extract this too
  • Example: 1080
• album optional
  • Type: string
  • Description: Album to file the image in - defaults to "images"
  • Example: "vacation-2024"
• tags optional
  • Type: string[]
  • Description: Tags for organising your images
  • Example: ["nature","sunset","beach"]
• strip_metadata optional
  • Type: boolean
  • Description: Remove EXIF data from the image
  • Example: true
• alt optional
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A stunning sunset over the Pacific Ocean"
• nsfw optional
  • Type: boolean
  • Description: Is this image NSFW?
• license optional
  • Type: "all-rights-reserved" | "cc0" | "pd" | "cc-by" | "cc-by-sa" | "cc-by-nc" | "cc-by-nc-sa" | "cc-by-nd" | "cc-by-nc-nd" | "mit" | "apache-2.0" | "gpl-3.0"
  • Description: License for your image
  • Example: "cc-by"
• visibility optional
  • Type: "public" | "private" | "unlisted"
  • Description: Who can see this? public (show in "all images" + accessible to anyone), unlisted (in album if album is public + accessible with link), or private (never on profile + owner only). Defaults to public
  • Example: "public"
• expiration optional
  • Type: string
  • Description: When should this expire? Try "7d", "30d", or "never"
  • Example: "30d"
• encrypt optional
  • Type: boolean
  • Description: Encrypt image at rest with AES-256-GCM
• turnstile_token optional
  • Type: string
  • Description: Cloudflare Turnstile token for bot protection
  • Example: "eyJ..."

Responses:

201: Image resource created with upload URL

Response 201:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

409: Conflict - Resource already exists

Response 409:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /images/{id}

Authentication Required

This endpoint requires authentication: Bearer

Returns a single image by ID. Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Image resource or array of resources (for batch requests)

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

PATCH /images/{id}

Authentication Required

This endpoint requires authentication: Bearer

Updates image metadata (filename, album, tags, alt text, etc.). Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Request Body:

• filename optional
  • Type: string
  • Description: Rename the file - old URLs will redirect
  • Example: "renamed-sunset.jpg"
• album optional
  • Type: string
  • Description: Move to a different album
  • Example: "nature-photos"
• tags optional
  • Type: string[]
  • Description: Replace all tags with these ones
  • Example: ["nature","ocean"]
• alt optional
  • Type: string
  • Description: Update the alt text
  • Example: "An even more stunning sunset over the Pacific"
• nsfw optional
  • Type: boolean
  • Description: Change NSFW status
• license optional
  • Type: "all-rights-reserved" | "cc0" | "pd" | "cc-by" | "cc-by-sa" | "cc-by-nc" | "cc-by-nc-sa" | "cc-by-nd" | "cc-by-nc-nd" | "mit" | "apache-2.0" | "gpl-3.0"
  • Description: Change the license
  • Example: "cc-by-sa"
• visibility optional
  • Type: "public" | "private" | "unlisted"
  • Description: Change visibility - public (show in "all images" + accessible to anyone), unlisted (in album if album is public + accessible with link), or private (never on profile + owner only)
  • Example: "private"
• expiration optional
  • Type: string
  • Description: Change when it expires
  • Example: "never"
• is_private optional
  • Type: boolean
  • Description: Alternative way to set privacy

Responses:

200: Updated image resource

Response 200:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

409: Conflict - Resource already exists

Response 409:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /images/{id}

Authentication Required

This endpoint requires authentication: Bearer

Soft-deletes an image (marks as deleted but keeps data for recovery). Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Image deleted successfully

Response 200:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images/{id}/restore

Authentication Required

This endpoint requires authentication: Bearer

Restores a soft-deleted image. Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Restored image resource

Response 200:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /images/{id}/permanent

Authentication Required

This endpoint requires authentication: Bearer

Permanently deletes an image from R2 storage and database. ONLY works on images that have already been soft-deleted. Returns 401 if unauthorized, 404 if not found, or 400 if image is not deleted.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Image permanently deleted

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /images/{id}/variants

Authentication Required

This endpoint requires authentication: Bearer

Returns a list of all existing variants (preset and custom) for an image. Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: List of existing variants

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images/{id}/variants

Authentication Required

This endpoint requires authentication: Bearer

Triggers generation of image variants (thumbnails, optimized versions) in the background. Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Request Body:

• variants required
  • Type: "original" | "w128" | "w256" | "w512" | "w1024" | "w1536" | "w2048" | "thumb" | "og-image"[]
  • Description: List of variant presets to generate
  • Example: ["thumbnail","preview"]

Responses:

202: Variant generation queued

Response 202:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images/{id}/complete

Authentication Required

This endpoint requires authentication: Bearer

Marks an image upload as complete after the file has been uploaded to R2. Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Upload completed successfully

Response 200:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /images/{id}/ai

Retrieve AI-generated classification, caption, and metadata for a specific image

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: AI analysis data

Response 200:

• image_id required
  • Type: string
  • Description: Image ID
  • Example: "abc123def456"
• labels required
  • Type: string[]
  • Description: Classification labels
  • Example: ["cat","animal","pet"]
• label_scores required
  • Type: number[]
  • Description: Confidence scores for each label (0-1)
  • Example: [0.95,0.87,0.82]
• caption required
  • Type: string
  • Description: AI-generated caption describing the image
  • Example: "A fluffy orange cat sitting on a windowsill"
• colors required
  • Type: object[]
  • Description: Dominant colors extracted from the image
• nsfw_score required
  • Type: number
  • Description: NSFW content score (0-1, higher = more likely NSFW)
  • Example: 0.02
• nsfw_flagged required
  • Type: boolean
  • Description: Whether the image was flagged as NSFW
• model_version required
  • Type: string
  • Description: AI model version used for analysis
  • Example: "resnet-50"
• processing_time_ms required
  • Type: number
  • Description: Time taken to process the image (milliseconds)
  • Example: 1250
• created_at required
  • Type: string
  • Description: When the analysis was created
  • Example: "2025-11-22T10:30:00Z"

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images/{id}/ai/analyze

Manually trigger AI classification, caption generation, and analysis for an image. Useful for testing or reprocessing.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: AI analysis completed

Response 200:

• image_id required
  • Type: string
  • Description: Image ID
  • Example: "abc123def456"
• labels required
  • Type: string[]
  • Description: Classification labels
  • Example: ["cat","animal","pet"]
• label_scores required
  • Type: number[]
  • Description: Confidence scores for each label (0-1)
  • Example: [0.95,0.87,0.82]
• caption required
  • Type: string
  • Description: AI-generated caption describing the image
  • Example: "A fluffy orange cat sitting on a windowsill"
• colors required
  • Type: object[]
  • Description: Dominant colors extracted from the image
• nsfw_score required
  • Type: number
  • Description: NSFW content score (0-1, higher = more likely NSFW)
  • Example: 0.02
• nsfw_flagged required
  • Type: boolean
  • Description: Whether the image was flagged as NSFW
• model_version required
  • Type: string
  • Description: AI model version used for analysis
  • Example: "resnet-50"
• processing_time_ms required
  • Type: number
  • Description: Time taken to process the image (milliseconds)
  • Example: 1250
• created_at required
  • Type: string
  • Description: When the analysis was created
  • Example: "2025-11-22T10:30:00Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images/{id}/replace

Authentication Required

This endpoint requires authentication: Bearer

Replace an existing image file with a new one while preserving the image ID, filename, and album. Optionally update metadata (tags, alt text, visibility). Existing variants will be deleted and regenerated. Returns a signed upload URL for the new file. Returns 401 if unauthorized or 404 if not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Request Body:

• content_type optional
  • Type: string
  • Description: MIME type of the new file - we'll detect it if you don't provide it
  • Example: "image/jpeg"
• size_bytes optional
  • Type: integer
  • Description: New file size in bytes - max 100MB
  • Example: 1048576
• width optional
  • Type: integer
  • Description: Width in pixels of the new file
  • Example: 1920
• height optional
  • Type: integer
  • Description: Height in pixels of the new file
  • Example: 1080
• tags optional
  • Type: string[]
  • Description: Update tags when replacing
  • Example: ["nature","sunset","beach"]
• alt optional
  • Type: string
  • Description: Update alt text when replacing
  • Example: "A stunning sunset over the Pacific Ocean"
• nsfw optional
  • Type: boolean
  • Description: Update NSFW flag when replacing
• license optional
  • Type: "all-rights-reserved" | "cc0" | "pd" | "cc-by" | "cc-by-sa" | "cc-by-nc" | "cc-by-nc-sa" | "cc-by-nd" | "cc-by-nc-nd" | "mit" | "apache-2.0" | "gpl-3.0"
  • Description: Update license when replacing
  • Example: "cc-by"
• visibility optional
  • Type: "public" | "private" | "unlisted"
  • Description: Update visibility when replacing
  • Example: "public"
• expiration optional
  • Type: string
  • Description: Update expiration when replacing
  • Example: "30d"

Responses:

200: Image ready for replacement with upload URL

Response 200:

• id required
  • Type: string
  • Description: Unique image identifier
  • Example: "img_abc123"
• owner required
  • Type: string
  • Description: Owner email address
  • Example: "user@example.com"
• filename required
  • Type: string
  • Description: Image filename with extension
  • Example: "sunset.jpg"
• album required
  • Type: string
  • Description: Album slug this image belongs to
  • Example: "vacation-2024"
• tags required
  • Type: string[]
  • Description: Tags associated with this image
  • Example: ["nature","sunset","beach"]
• urls required
  • Type: object
  • Description: Image URLs for different variants
• upload required
  • Type: object
  • Description: Upload details (only present immediately after image creation)
• info required
  • Type: object
  • Description: Image file information
• status required
  • Type: object
  • Description: Image status information
• alt required
  • Type: string
  • Description: Alt text for accessibility
  • Example: "A beautiful sunset over the ocean"
• nsfw required
  • Type: boolean
  • Description: Whether image contains NSFW content
• license required
  • Type: string
  • Description: Image license type
  • Example: "cc-by"
• visibility required
  • Type: string
  • Description: Image visibility setting
  • Example: "public"
• expiration_date required
  • Type: string
  • Description: Auto-delete expiration date (null for permanent)
• is_private required
  • Type: boolean
  • Description: Whether image requires authentication to view
• is_favourited required
  • Type: boolean
  • Description: Whether the current user has favourited this image
• created_at required
  • Type: string
  • Description: Image creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /images/{id}/token

Authentication Required

This endpoint requires authentication: Bearer

Generate a time-limited access token for an encrypted image. Returns 400 if image is not encrypted.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: abc123

Request Body:

• variant optional
  • Type: string
  • Description: Variant to generate token for (default: original)
  • Example: "thumbnail"
  • Default: "original"
• expires_in optional
  • Type: integer
  • Description: Token lifetime in seconds (min: 5min, max: 7 days, default: 1 hour)
  • Example: 3600
  • Default: 3600

Responses:

200: Access token generated successfully

400: Image not encrypted or invalid parameters

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Albums

Albums let you organise your images into folders. They relate to physical directories on-disk in the bucket, but can also have custom metadata and settings.

GET /albums

Authentication Required

This endpoint requires authentication: Bearer

Returns a list of all albums for the authenticated user. Returns 401 if unauthorized.

Responses:

200: List of albums retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /albums

Authentication Required

This endpoint requires authentication: Bearer

Creates a new album for organizing images. Album slugs must be unique and contain only lowercase letters, numbers, and hyphens. Returns 400 for validation errors, 401 if unauthorized, or 409 if album already exists.

Request Body:

• album required
  • Type: string
  • Description: Slug for the album - lowercase letters, numbers, hyphens
  • Example: "vacation-2024"
• title required
  • Type: string
  • Description: Display name for the album
  • Example: "Summer Vacation 2024"
• description optional
  • Type: string
  • Description: What this album is about
  • Example: "Photos from our summer vacation to Hawaii"
• permission optional
  • Type: "public" | "private"
  • Description: Public profile permission - public or private. Defaults to private
  • Example: "private"

Responses:

201: Album created successfully

Response 201:

• album required
  • Type: string
  • Description: Album slug (unique identifier)
  • Example: "vacation-2024"
• title required
  • Type: string
  • Description: Human-readable album title
  • Example: "Summer Vacation 2024"
• description required
  • Type: string
  • Description: Album description
  • Example: "Photos from our summer vacation"
• count required
  • Type: integer
  • Description: Number of images in this album
  • Example: 42
• created_at required
  • Type: string
  • Description: Album creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• cover_url optional
  • Type: string
  • Description: URL of album cover image (if set)
  • Example: "https://cdn.pixelflare.cc/user/vacation/cover.jpg/thumb"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

409: Conflict - Resource already exists

Response 409:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /albums/{album}

Authentication Required

This endpoint requires authentication: Bearer

Returns details about a specific album, including image count. Returns 401 if unauthorized or 404 if album not found.

Parameters:

• album (path) required
  • Type: string
  • Description: Album slug
  • Example: vacation-2024

Responses:

200: Album details retrieved successfully

Response 200:

• album required
  • Type: string
  • Description: Album slug (unique identifier)
  • Example: "vacation-2024"
• title required
  • Type: string
  • Description: Human-readable album title
  • Example: "Summer Vacation 2024"
• description required
  • Type: string
  • Description: Album description
  • Example: "Photos from our summer vacation"
• count required
  • Type: integer
  • Description: Number of images in this album
  • Example: 42
• created_at required
  • Type: string
  • Description: Album creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• cover_url optional
  • Type: string
  • Description: URL of album cover image (if set)
  • Example: "https://cdn.pixelflare.cc/user/vacation/cover.jpg/thumb"

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

PATCH /albums/{album}

Authentication Required

This endpoint requires authentication: Bearer

Updates an album's title or description. The album slug cannot be changed. Returns 400 for validation errors, 401 if unauthorized, or 404 if album not found.

Parameters:

• album (path) required
  • Type: string
  • Description: Album slug
  • Example: vacation-2024

Request Body:

• title optional
  • Type: string
  • Description: New name for the album
  • Example: "Updated Vacation Photos"
• description optional
  • Type: string
  • Description: New description
  • Example: "Updated description"
• permission optional
  • Type: "public" | "private"
  • Description: Change public profile permission
  • Example: "public"

Responses:

200: Album updated successfully

Response 200:

• album required
  • Type: string
  • Description: Album slug (unique identifier)
  • Example: "vacation-2024"
• title required
  • Type: string
  • Description: Human-readable album title
  • Example: "Summer Vacation 2024"
• description required
  • Type: string
  • Description: Album description
  • Example: "Photos from our summer vacation"
• count required
  • Type: integer
  • Description: Number of images in this album
  • Example: 42
• created_at required
  • Type: string
  • Description: Album creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at required
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• cover_url optional
  • Type: string
  • Description: URL of album cover image (if set)
  • Example: "https://cdn.pixelflare.cc/user/vacation/cover.jpg/thumb"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /albums/{album}

Authentication Required

This endpoint requires authentication: Bearer

Permanently deletes an album. This does not delete the images in the album, they will be moved to the default "images" album. Returns 401 if unauthorized or 404 if album not found.

Parameters:

• album (path) required
  • Type: string
  • Description: Album slug
  • Example: vacation-2024

Responses:

204: Album deleted successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Tags

Images can have zero or more tags, to make searching and organisation easier. The tags endpoint let you fetch, create, edit and delete tags, but won't affect the images themselves.

GET /tags

Authentication Required

This endpoint requires authentication: Bearer

Returns a list of all tags for the authenticated user, sorted by usage count (descending). Returns 401 if unauthorized.

Responses:

200: List of tags retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /tags

Authentication Required

This endpoint requires authentication: Bearer

Creates a new tag for organizing images. Tag names are automatically normalized to lowercase slugs. Returns 400 for validation errors, 401 if unauthorized, or 409 if tag already exists.

Request Body:

• tag required
  • Type: string
  • Description: Tag name - I'll convert it to lowercase
  • Example: "nature"
• description optional
  • Type: string
  • Description: What this tag means
  • Example: "Photos of natural landscapes and wildlife"
• color optional
  • Type: string
  • Description: Colour for this tag - uses Tailwind colour names
  • Example: "red"

Responses:

201: Tag created successfully

Response 201:

• tag required
  • Type: string
  • Description: Tag slug (unique identifier)
  • Example: "nature"
• description optional
  • Type: string
  • Description: Tag description
  • Example: "Photos of natural landscapes and wildlife"
• color optional
  • Type: string
  • Description: Tag color in hex format
  • Example: "#22c55e"
• count required
  • Type: integer
  • Description: Number of images with this tag
  • Example: 156
• created_at optional
  • Type: string
  • Description: Tag creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at optional
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

409: Conflict - Resource already exists

Response 409:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /tags/{tag}

Authentication Required

This endpoint requires authentication: Bearer

Returns details about a specific tag, including usage count. Returns 401 if unauthorized or 404 if tag not found.

Parameters:

• tag (path) required
  • Type: string
  • Description: Tag slug
  • Example: nature

Responses:

200: Tag details retrieved successfully

Response 200:

• tag required
  • Type: string
  • Description: Tag slug (unique identifier)
  • Example: "nature"
• description optional
  • Type: string
  • Description: Tag description
  • Example: "Photos of natural landscapes and wildlife"
• color optional
  • Type: string
  • Description: Tag color in hex format
  • Example: "#22c55e"
• count required
  • Type: integer
  • Description: Number of images with this tag
  • Example: 156
• created_at optional
  • Type: string
  • Description: Tag creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at optional
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

PATCH /tags/{tag}

Authentication Required

This endpoint requires authentication: Bearer

Updates a tag's description or other metadata. The tag slug cannot be changed. Returns 400 for validation errors, 401 if unauthorized, or 404 if tag not found.

Parameters:

• tag (path) required
  • Type: string
  • Description: Tag slug
  • Example: nature

Request Body:

• description optional
  • Type: string
  • Description: New description for this tag
  • Example: "Updated tag description"
• color optional
  • Type: string
  • Description: New colour - use Tailwind colour names
  • Example: "pink"

Responses:

200: Tag updated successfully

Response 200:

• tag required
  • Type: string
  • Description: Tag slug (unique identifier)
  • Example: "nature"
• description optional
  • Type: string
  • Description: Tag description
  • Example: "Photos of natural landscapes and wildlife"
• color optional
  • Type: string
  • Description: Tag color in hex format
  • Example: "#22c55e"
• count required
  • Type: integer
  • Description: Number of images with this tag
  • Example: 156
• created_at optional
  • Type: string
  • Description: Tag creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• updated_at optional
  • Type: string
  • Description: Last update timestamp
  • Example: "2025-11-10T22:00:00.000Z"

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /tags/{tag}

Authentication Required

This endpoint requires authentication: Bearer

Permanently deletes a tag. This does not delete the images associated with this tag, only the tag association. Returns 401 if unauthorized or 404 if tag not found.

Parameters:

• tag (path) required
  • Type: string
  • Description: Tag slug
  • Example: nature

Responses:

200: Tag deleted successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Favourites

Mark and retrieve your favorite images for quick access and (where supported) offline viewing.

POST /images/{id}/favourite

Authentication Required

This endpoint requires authentication: Bearer

Marks an image as favourited. Returns 401 if unauthorized or 404 if image not found.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Image added to favourites successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /images/{id}/favourite

Authentication Required

This endpoint requires authentication: Bearer

Removes the favourite mark from an image. Returns 401 if unauthorized.

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID
  • Example: img_abc123

Responses:

200: Image removed from favourites successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /favourites

Authentication Required

This endpoint requires authentication: Bearer

Returns a paginated list of all favourited images for the authenticated user. Returns 401 if unauthorized.

Parameters:

• limit (query) optional
  • Type: integer
  • Description: Number of items per page
  • Example: 10
  • Default: 10
• cursor (query) optional
  • Type: string
  • Description: Pagination cursor from previous response
  • Example: img_xyz789

Responses:

200: Favourited images retrieved successfully

Response 200:

• data required
  • Type: any[]
  • Description: Array of items in this page
• next_cursor required
  • Type: string
  • Description: Cursor for next page (null if no more pages)
  • Example: "img_xyz789"

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Analytics

Track CDN usage, bandwidth consumption, and image performance metrics with detailed breakdowns.

GET /analytics/usage

Authentication Required

This endpoint requires authentication: Bearer

Returns overall usage statistics for the authenticated user including storage, bandwidth, and request counts. Returns 401 if unauthorized.

Parameters:

• days (query) optional
  • Type: string
  • Description: Number of days to include in statistics (default: 30, max: 90)
  • Example: 30
• offset (query) optional
  • Type: string
  • Description: Number of days to offset the period (default: 0). Use offset=30 for previous 30-day period.
  • Example: 0

Responses:

200: Usage statistics retrieved successfully

Response 200:

• enabled required
  • Type: boolean
  • Description: Whether analytics is enabled for this account
  • Example: true
• period required
  • Type: object
  • Description: Time period for the statistics
• storage required
  • Type: object
  • Description: Storage usage statistics
• bandwidth required
  • Type: object
  • Description: Bandwidth usage statistics
• requests required
  • Type: object
  • Description: Request count statistics

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /analytics/images/{id}

Authentication Required

This endpoint requires authentication: Bearer

Returns detailed consumption statistics for one or more images. Supports comma-separated IDs for batch requests (e.g., /analytics/images/:id1,:id2,:id3). Returns single object for one ID, array for multiple IDs. Returns 401 if unauthorized, 403 if not owned by user, or 404 if image not found (single ID only).

Parameters:

• id (path) required
  • Type: string
  • Description: Image ID or comma-separated IDs (e.g., id1,id2,id3)
  • Example: img_abc123
• days (query) optional
  • Type: string
  • Description: Number of days to include in statistics (default: 30, max: 90)
  • Example: 30
• offset (query) optional
  • Type: string
  • Description: Number of days to offset the period (default: 0)
  • Example: 0

Responses:

200: Image statistics retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

403: Forbidden - Insufficient permissions

Response 403:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /analytics/flows

Authentication Required

This endpoint requires authentication: Bearer

Returns image request flows data for Sankey diagram visualization, showing top images by request count with album and variant breakdown. Returns 401 if unauthorized.

Parameters:

• days (query) optional
  • Type: string
  • Description: Number of days to include in statistics (default: 30, max: 90)
  • Example: 30
• offset (query) optional
  • Type: string
  • Description: Number of days to offset the period (default: 0)
  • Example: 0
• limit (query) optional
  • Type: string
  • Description: Maximum number of flow records to return (default: 10, max: 200)
  • Example: 10

Responses:

200: Image flows retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /analytics/referrers/timeline

Authentication Required

This endpoint requires authentication: Bearer

Returns daily request counts for the top N referrer domains over the specified period. Referrers are grouped by domain for cleaner visualization. Useful for tracking referrer trends. Returns 401 if unauthorized.

Parameters:

• days (query) optional
  • Type: string
  • Description: Number of days to include in statistics (default: 30, max: 90)
  • Example: 30
• offset (query) optional
  • Type: string
  • Description: Number of days to offset the period (default: 0)
  • Example: 0
• top (query) optional
  • Type: string
  • Description: Number of top referrer domains to include (default: 10, max: 20)
  • Example: 10

Responses:

200: Referrer timeline retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /analytics/countries/timeline

Authentication Required

This endpoint requires authentication: Bearer

Returns daily request and bandwidth counts for the top N countries over the specified period. Useful for tracking geographic traffic trends. Returns 401 if unauthorized.

Parameters:

• days (query) optional
  • Type: string
  • Description: Number of days to include in statistics (default: 30, max: 90)
  • Example: 30
• offset (query) optional
  • Type: string
  • Description: Number of days to offset the period (default: 0)
  • Example: 0
• top (query) optional
  • Type: string
  • Description: Number of top countries to include (default: 10, max: 20)
  • Example: 10

Responses:

200: Country timeline retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /analytics/usage-limits

Authentication Required

This endpoint requires authentication: Bearer

Returns current usage and limit information for the authenticated user. Shows quota status and plan tier. Returns 401 if unauthorized.

Responses:

200: Usage limit information retrieved successfully

Response 200:

• enabled required
  • Type: boolean
  • Description: Whether usage limits are enabled
  • Example: true
• current required
  • Type: integer
  • Description: Current number of images uploaded
  • Example: 245
• limit required
  • Type: integer
  • Description: Maximum images allowed for user plan (null = unlimited)
  • Example: 1000
• percentage required
  • Type: number
  • Description: Usage percentage (0-100+)
  • Example: 24.5
• plan required
  • Type: string
  • Description: User plan tier (free, starter, pro, unlimited)
  • Example: "free"
• grace_percentage required
  • Type: number
  • Description: Grace buffer percentage over limit
  • Example: 1

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Audit Logs

View audit logs of all API actions and mutations. Track who did what, when, and from where.

GET /audit-logs

Authentication Required

This endpoint requires authentication: Bearer

Returns a paginated list of audit log entries with optional filtering by action, resource type, status, and date range. Returns 503 if audit logging is disabled.

Parameters:

• limit (query) optional
  • Type: integer
  • Description: Number of logs to return (max 200)
  • Example: 10
  • Default: 10
• cursor (query) optional
  • Type: string
  • Description: Pagination cursor from previous response
  • Example: log_xyz789
• action (query) optional
  • Type: string
  • Description: Filter by action type
  • Example: image.create
• resource_type (query) optional
  • Type: string
  • Description: Filter by resource type
  • Example: image
• status (query) optional
  • Type: "success" | "failure"
  • Description: Filter by status
  • Example: success
• date_from (query) optional
  • Type: string
  • Description: Filter logs from this date (YYYY-MM-DD)
  • Example: 2025-01-01
• date_to (query) optional
  • Type: string
  • Description: Filter logs up to this date (YYYY-MM-DD)
  • Example: 2025-12-31

Responses:

200: List of audit logs retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

503: Service Unavailable - Service temporarily unavailable

Response 503:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /audit-logs/stats

Authentication Required

This endpoint requires authentication: Bearer

Returns aggregated statistics about audit logs for the authenticated user. Returns 503 if audit logging is disabled.

Parameters:

• days (query) optional
  • Type: integer
  • Description: Number of days to include in statistics (1-365)
  • Example: 30
  • Default: 30

Responses:

200: Audit log statistics retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

503: Service Unavailable - Service temporarily unavailable

Response 503:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /audit-logs/export

Authentication Required

This endpoint requires authentication: Bearer

Exports audit logs matching the specified filters as a CSV file. Returns 503 if audit logging is disabled.

Parameters:

• action (query) optional
  • Type: string
  • Description: Filter by action type
  • Example: image.create
• resource_type (query) optional
  • Type: string
  • Description: Filter by resource type
  • Example: image
• status (query) optional
  • Type: "success" | "failure"
  • Description: Filter by status
  • Example: success
• date_from (query) optional
  • Type: string
  • Description: Filter logs from this date (YYYY-MM-DD)
  • Example: 2025-01-01
• date_to (query) optional
  • Type: string
  • Description: Filter logs up to this date (YYYY-MM-DD)
  • Example: 2025-12-31

Responses:

200: CSV file generated successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

503: Service Unavailable - Service temporarily unavailable

Response 503:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /audit-logs/status

Returns whether audit logging is enabled on this instance. No authentication required.

Responses:

200: Audit logging status retrieved successfully

---

API Keys

Manage API keys for programmatic access. Supports scoped permissions and expiration.

📖 Authentication Guide

GET /keys

Authentication Required

This endpoint requires authentication: Bearer

Returns a list of all API keys for the authenticated user. The key values are not returned (only shown on creation). Returns 401 if unauthorized.

Responses:

200: List of API keys retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /keys

Authentication Required

This endpoint requires authentication: Bearer

Creates a new API key with specified scopes and optional expiration. The key value is only returned once on creation - store it securely! Returns 400 for validation errors or 401 if unauthorized.

Request Body:

• name optional
  • Type: string
  • Description: Name to help you remember what this key is for
  • Example: "CI/CD Pipeline Key"
• scopes required
  • Type: "read" | "write" | "delete"[]
  • Description: What can this key do? Pick at least one
  • Example: ["read","write"]
• expires_in_days optional
  • Type: integer
  • Description: Days until expiry - max 365
  • Example: 90
• allowed_ips optional
  • Type: string[]
  • Description: Limit to specific IPs or CIDR ranges - leave empty to allow all
  • Example: ["192.168.1.1","10.0.0.0/24"]

Responses:

201: API key created successfully

Response 201:

• key_id required
  • Type: string
  • Description: Unique key identifier
  • Example: "key_abc123"
• key optional
  • Type: string
  • Description: API key value (only present on creation, store securely!)
  • Example: "pxf_1234567890abcdef1234567890abcdef"
• scopes required
  • Type: string[]
  • Description: Permissions granted to this API key
  • Example: ["read","write"]
• name required
  • Type: string
  • Description: Human-readable key name
  • Example: "CI/CD Pipeline Key"
• expires_at required
  • Type: string
  • Description: Key expiration timestamp (null for no expiration)
  • Example: "2026-11-10T22:00:00.000Z"
• last_used_at required
  • Type: string
  • Description: Last time this key was used
  • Example: "2025-11-10T21:00:00.000Z"
• revoked_at required
  • Type: string
  • Description: Key revocation timestamp (null if active)
• created_at required
  • Type: string
  • Description: Key creation timestamp
  • Example: "2025-11-10T22:00:00.000Z"
• allowed_ips required
  • Type: string[]
  • Description: IP addresses or CIDR ranges allowed to use this key (null allows all)
  • Example: ["192.168.1.1","10.0.0.0/24"]

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /keys/{keyId}

Authentication Required

This endpoint requires authentication: Bearer

Permanently revokes an API key. The key will no longer be able to authenticate. Returns 401 if unauthorized or 404 if key not found.

Parameters:

• keyId (path) required
  • Type: string
  • Description: API key ID
  • Example: key_abc123

Responses:

204: API key revoked successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Backup

Configure S3 backup for redundancy. Supports automatic sync and encryption.

GET /backup/config

Retrieve the current S3 backup configuration for the authenticated user

Responses:

200: Backup configuration retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /backup/config

Configure S3-compatible storage for automated image backups

Request Body:

• enabled required
  • Type: boolean
  • Description:
• s3_endpoint required
  • Type: string
  • Description:
• s3_region required
  • Type: string
  • Description:
• s3_bucket required
  • Type: string
  • Description:
• s3_path_prefix optional
  • Type: string
  • Description:
• s3_access_key_id required
  • Type: string
  • Description:
• s3_secret_access_key required
  • Type: string
  • Description:

Responses:

200: Backup configuration updated successfully

201: Backup configuration created successfully

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

PATCH /backup/config

Partially update S3 backup configuration fields

Request Body:

• enabled optional
  • Type: boolean
  • Description:
• s3_endpoint optional
  • Type: string
  • Description:
• s3_region optional
  • Type: string
  • Description:
• s3_bucket optional
  • Type: string
  • Description:
• s3_path_prefix optional
  • Type: string
  • Description:
• s3_access_key_id optional
  • Type: string
  • Description:
• s3_secret_access_key optional
  • Type: string
  • Description:

Responses:

200: Backup configuration updated successfully

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /backup/config

Remove S3 backup configuration and encrypted credentials

Responses:

204: Backup configuration deleted successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /backup/test

Validate S3 credentials and bucket access

Responses:

200: Connection test completed

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /backup/sync

Manually trigger backup sync for pending images

Responses:

202: Backup sync queued successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /backup/stats

Retrieve backup sync statistics and status counts

Responses:

200: Backup statistics retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Settings

Manage user preferences including theme, language, accessibility options, and default upload settings.

GET /settings

Authentication Required

This endpoint requires authentication: Bearer

Returns user preferences for appearance, accessibility, and upload defaults. Returns default values for new users.

Responses:

200: Settings retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

PATCH /settings

Authentication Required

This endpoint requires authentication: Bearer

Partially update user settings. Only provided fields will be updated. Returns merged settings with defaults.

Request Body:

• theme optional
  • Type: "auto" | "light" | "dark" | "dracula" | "night" | "winter" | "synthwave" | "valentine" | "aqua" | "lofi" | "dim" | "pastel" | "business" | "nord" | "sunset" | "fantasy" | "cupcake" | "emerald"
  • Description:
• language optional
  • Type: "en" | "es" | "fr" | "zh" | "hi" | "ar" | "pt" | "de" | "id" | "ru" | "ko" | "it"
  • Description:
• accessibility optional
  • Type: object
  • Description:
• upload optional
  • Type: object
  • Description:
• image_view_mode optional
  • Type: "regular" | "expanded"
  • Description:
• embed_url_format optional
  • Type: "full" | "short"
  • Description:
• embed_use_custom_domain optional
  • Type: boolean
  • Description:
• embed_enabled_formats optional
  • Type: string[]
  • Description:
• saved_custom_variant optional
  • Type: object
  • Description:
• delete_variant_id optional
  • Type: string
  • Description:
• update_variant optional
  • Type: object
  • Description:

Responses:

200: Settings updated successfully

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Custom Domains

Configure custom subdomains for serving images from your own domain (e.g., cdn.yourdomain.com).

GET /custom-domain

Authentication Required

This endpoint requires authentication: Bearer

Returns the custom domain configuration for the authenticated user. Returns 404 if no custom domain is configured.

Responses:

200: Custom domain retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: No custom domain configured

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /custom-domain

Authentication Required

This endpoint requires authentication: Bearer

Configures a custom subdomain for serving images. Only one domain per user is allowed. If a domain already exists, it will be replaced. The domain must be verified via DNS (CNAME or TXT record) before it becomes active.

Request Body:

• hostname required
  • Type: string
  • Description: The custom subdomain (e.g., cdn.example.com). Root domains are not supported.

Responses:

200: Custom domain updated successfully

201: Custom domain created successfully

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

409: Hostname already in use by another user

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

503: Custom domains feature is not enabled

---

DELETE /custom-domain

Authentication Required

This endpoint requires authentication: Bearer

Removes the custom domain configuration for the authenticated user. The domain will be immediately removed from Cloudflare and the cache will be invalidated.

Responses:

204: Custom domain deleted successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: No custom domain configured

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /custom-domain/verify

Authentication Required

This endpoint requires authentication: Bearer

Manually triggers a verification check for the custom domain. Queries Cloudflare API to check if DNS records are correctly configured.

Responses:

200: Verification check completed

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: No custom domain configured

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Webhooks

Configure webhooks to receive real-time HTTP notifications when events occur (e.g., image uploaded, album created). Includes HMAC-SHA256 signatures for security.

📖 Webhook Guide

POST /webhooks

Authentication Required

This endpoint requires authentication: Bearer

Create a new webhook to receive HTTP POST notifications when events occur. Maximum 10 webhooks per user.

Request Body:

• url required
  • Type: string
  • Description: HTTPS URL to receive webhook POST requests
  • Example: "https://example.com/webhooks/pixelflare"
• events required
  • Type: "image.uploaded" | "image.updated" | "image.deleted" | "image.permanently_deleted" | "image.restored" | "album.created" | "album.updated" | "album.deleted"[]
  • Description: Array of events to subscribe to
  • Example: ["image.uploaded","image.deleted"]
• description optional
  • Type: string
  • Description: Optional description for this webhook
  • Example: "Production webhook for image events"

Responses:

201: Webhook created successfully (secret only returned once)

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /webhooks

Authentication Required

This endpoint requires authentication: Bearer

Get all webhooks for the authenticated user

Responses:

200: List of webhooks (secrets not included)

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /webhooks/{id}

Authentication Required

This endpoint requires authentication: Bearer

Get details of a specific webhook

Parameters:

• id (path) required
  • Type: string
  • Description:
  • Example: wh_abc123

Responses:

200: Webhook details (secret not included)

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

PATCH /webhooks/{id}

Authentication Required

This endpoint requires authentication: Bearer

Update webhook URL, events, description, or enabled status

Parameters:

• id (path) required
  • Type: string
  • Description:
  • Example: wh_abc123

Request Body:

• url optional
  • Type: string
  • Description:
  • Example: "https://example.com/webhooks/pixelflare-v2"
• events optional
  • Type: "image.uploaded" | "image.updated" | "image.deleted" | "image.permanently_deleted" | "image.restored" | "album.created" | "album.updated" | "album.deleted"[]
  • Description:
  • Example: ["image.uploaded"]
• description optional
  • Type: string
  • Description:
  • Example: "Updated webhook description"
• enabled optional
  • Type: boolean
  • Description:
  • Example: true

Responses:

200: Webhook updated successfully

400: Bad Request - Invalid input or validation error

Response 400:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

DELETE /webhooks/{id}

Authentication Required

This endpoint requires authentication: Bearer

Permanently delete a webhook

Parameters:

• id (path) required
  • Type: string
  • Description:
  • Example: wh_abc123

Responses:

204: Webhook deleted successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

POST /webhooks/{id}/test

Authentication Required

This endpoint requires authentication: Bearer

Send a test event to verify webhook is configured correctly

Parameters:

• id (path) required
  • Type: string
  • Description:
  • Example: wh_abc123

Responses:

200: Test result

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /webhooks/{id}/deliveries

Authentication Required

This endpoint requires authentication: Bearer

Get recent delivery attempts for a webhook (last 100)

Parameters:

• id (path) required
  • Type: string
  • Description:
  • Example: wh_abc123

Responses:

200: List of recent deliveries

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Status

Check API health, service status, and system information.

GET /status

Returns public system status including dependency health, feature availability, and app version. No authentication required. Use this endpoint for monitoring and health checks.

Responses:

200: System status retrieved successfully

Response 200:

• status required
  • Type: "ok" | "degraded" | "error"
  • Description: Overall system status: ok (all dependencies healthy), degraded (optional dependencies down), error (critical dependencies down)
  • Example: "ok"
• timestamp required
  • Type: string
  • Description: ISO 8601 timestamp of status check
  • Example: "2025-12-01T14:30:00.123Z"
• app required
  • Type: object
  • Description: Application metadata
• features required
  • Type: object
  • Description: Available features and capabilities
• dependencies required
  • Type: object
  • Description: Health status of external dependencies

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /status/detailed

Authentication Required

This endpoint requires authentication: Bearer

Returns detailed system status including migration version, resource counts, scheduled jobs, and binding information. Requires authentication. In production, sensitive details are redacted. In development, full binding IDs are shown.

Responses:

200: Detailed status retrieved successfully

401: Unauthorised - Authentication required

Response 401:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Public Profiles

Public (unauthenticated) endpoints for viewing user profiles, albums, and images. No authentication required.

GET /public/users/:owner

Returns a user's public profile information and statistics. No authentication required.

Parameters:

• owner (path) required
  • Type: string
  • Description: User owner ID / username
  • Example: alice

Responses:

200: Public profile retrieved successfully

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /public/users/:owner/albums

Returns a paginated list of public albums for a user. No authentication required.

Parameters:

• owner (path) required
  • Type: string
  • Description: User owner ID / username
  • Example: alice
• limit (query) optional
  • Type: integer
  • Description: Number of items per page
  • Example: 10
  • Default: 10
• cursor (query) optional
  • Type: string
  • Description: Pagination cursor from previous response
  • Example: img_xyz789

Responses:

200: Public albums list retrieved successfully

Response 200:

• data required
  • Type: any[]
  • Description: Array of items in this page
• next_cursor required
  • Type: string
  • Description: Cursor for next page (null if no more pages)
  • Example: "img_xyz789"

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /public/users/:owner/albums/:slug

Returns a public album with its images (filtered to public and inherit permissions). No authentication required.

Parameters:

• owner (path) required
  • Type: string
  • Description: User owner ID / username
  • Example: alice
• slug (path) required
  • Type: string
  • Description: Album slug
  • Example: vacation-2024
• limit (query) optional
  • Type: integer
  • Description: Number of items per page
  • Example: 10
  • Default: 10
• cursor (query) optional
  • Type: string
  • Description: Pagination cursor from previous response
  • Example: img_xyz789

Responses:

200: Public album with images retrieved successfully

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /public/users/:owner/images

Returns paginated list of public images for a user (includes orphan images and images in private albums that are marked public). No authentication required.

Parameters:

• owner (path) required
  • Type: string
  • Description: User owner ID / username
  • Example: alice
• limit (query) optional
  • Type: integer
  • Description: Number of items per page
  • Example: 10
  • Default: 10
• cursor (query) optional
  • Type: string
  • Description: Pagination cursor from previous response
  • Example: img_xyz789

Responses:

200: Public images list retrieved successfully

Response 200:

• data required
  • Type: any[]
  • Description: Array of items in this page
• next_cursor required
  • Type: string
  • Description: Cursor for next page (null if no more pages)
  • Example: "img_xyz789"

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

GET /public/users/:owner/albums/:slug/images/:filename

Returns a single public image with album context and navigation (prev/next images). Works regardless of album permission - only checks if the image itself is public. No authentication required.

Parameters:

• owner (path) required
  • Type: string
  • Description: User owner ID / username
  • Example: alice
• slug (path) required
  • Type: string
  • Description: Album slug
  • Example: vacation-2024
• filename (path) required
  • Type: string
  • Description: Image filename
  • Example: beach-sunset.jpg

Responses:

200: Public image retrieved successfully

404: Not Found - Resource does not exist

Response 404:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

429: Too Many Requests - Rate limit exceeded

Response 429:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

500: Internal Server Error - Unexpected server error

Response 500:

• code required
  • Type: string
  • Description: Machine-readable error code
  • Example: "VALIDATION_ERROR"
• message required
  • Type: string
  • Description: Human-readable error message
  • Example: "Request validation failed"
• details optional
  • Type: object
  • Description: Additional error details (field-specific validation errors)
  • Example: {"filename":"Filename is required"}

---

Image Serving

Public CDN routes for accessing and serving images. These endpoints deliver your images globally via Cloudflare's edge network with automatic caching and image transformations.

📖 CDN Usage Guide

GET /i/{id}

Serve an image using its short ID, with optional custom transformations.

Path format: /i/{id}

Benefits:

• Shorter URLs (6 characters instead of full path)
• Stable links (unaffected by renames/moves)
• Ideal for sharing and embedding
• Custom transformations via query parameters

Examples:

https://pixelflare.cc/i/ab12xy
https://pixelflare.cc/i/ab12xy?w=400&h=300&fit=cover

Parameters:

• id (path) required
  • Type: string
  • Description: Short image ID (6 characters)
• w (query) optional
  • Type: integer
  • Description: Width in pixels (1-9999)
• h (query) optional
  • Type: integer
  • Description: Height in pixels (1-9999)
• fit (query) optional
  • Type: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze"
  • Description: Resize fit mode
• q (query) optional
  • Type: integer
  • Description: Quality (1-100)
• f (query) optional
  • Type: "auto" | "avif" | "webp" | "jpeg" | "png"
  • Description: Output format
• g (query) optional
  • Type: "auto" | "center" | "left" | "right" | "top" | "bottom" | "face"
  • Description: Gravity/focus point
• trim (query) optional
  • Type: string
  • Description: Crop margins (e.g., top:10,left:20)
• blur (query) optional
  • Type: integer
  • Description: Blur radius (1-250)
• sharpen (query) optional
  • Type: integer
  • Description: Sharpen amount (1-10)
• br (query) optional
  • Type: number
  • Description: Brightness (0.5-2.0)
• co (query) optional
  • Type: number
  • Description: Contrast (0.5-2.0)
• sat (query) optional
  • Type: number
  • Description: Saturation (0-2.0)
• gam (query) optional
  • Type: number
  • Description: Gamma (0.5-2.0)
• r (query) optional
  • Type: "0" | "90" | "180" | "270"
  • Description: Rotation angle (0, 90, 180, 270)
• flip (query) optional
  • Type: "h" | "v" | "hv"
  • Description: Flip direction (h=horizontal, v=vertical, hv=both)
• bg (query) optional
  • Type: string
  • Description: Background color (hex without #)
• meta (query) optional
  • Type: "keep" | "copyright" | "none"
  • Description: Metadata handling

Responses:

200: Image successfully served

403: Image is private

404: Image not found

410: Image deleted

429: Too many custom transformation requests

---

GET /i/{id}/{variant}

Serve a specific image variant using the short ID format, with optional custom transformations.

Path format: /i/{id}/{variant}

Examples:

https://pixelflare.cc/i/ab12xy/w512
https://pixelflare.cc/i/ab12xy/w512?sharpen=5&q=90

This combines the benefits of short URLs with on-demand image transformation. Query params override variant preset.

Parameters:

• id (path) required
  • Type: string
  • Description: Short image ID (6 characters)
• variant (path) required
  • Type: "original" | "w128" | "w256" | "w512" | "w1024" | "w1536" | "w2048" | "thumb" | "og-image"
  • Description:
• w (query) optional
  • Type: integer
  • Description: Width in pixels (1-9999)
• h (query) optional
  • Type: integer
  • Description: Height in pixels (1-9999)
• fit (query) optional
  • Type: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze"
  • Description: Resize fit mode
• q (query) optional
  • Type: integer
  • Description: Quality (1-100)
• f (query) optional
  • Type: "auto" | "avif" | "webp" | "jpeg" | "png"
  • Description: Output format
• g (query) optional
  • Type: "auto" | "center" | "left" | "right" | "top" | "bottom" | "face"
  • Description: Gravity/focus point
• trim (query) optional
  • Type: string
  • Description: Crop margins (e.g., top:10,left:20)
• blur (query) optional
  • Type: integer
  • Description: Blur radius (1-250)
• sharpen (query) optional
  • Type: integer
  • Description: Sharpen amount (1-10)
• br (query) optional
  • Type: number
  • Description: Brightness (0.5-2.0)
• co (query) optional
  • Type: number
  • Description: Contrast (0.5-2.0)
• sat (query) optional
  • Type: number
  • Description: Saturation (0-2.0)
• gam (query) optional
  • Type: number
  • Description: Gamma (0.5-2.0)
• r (query) optional
  • Type: "0" | "90" | "180" | "270"
  • Description: Rotation angle (0, 90, 180, 270)
• flip (query) optional
  • Type: "h" | "v" | "hv"
  • Description: Flip direction (h=horizontal, v=vertical, hv=both)
• bg (query) optional
  • Type: string
  • Description: Background color (hex without #)
• meta (query) optional
  • Type: "keep" | "copyright" | "none"
  • Description: Metadata handling

Responses:

200: Image variant served

400: Invalid variant

403: Image is private

404: Image not found

410: Image deleted

429: Rate limited

---

GET /{owner}/{album}/{filename}

Serve an image at its original size or apply custom transformations via query parameters.

Path format: /{owner}/{album}/{filename}

Features:

• Global edge caching via Cloudflare CDN
• Automatic content-type detection
• Support for private images with authentication
• CORS enabled for cross-origin requests
• ETag support for efficient caching
• Custom transformations via query parameters (w, h, fit, q, f, g, etc.)

Examples:

https://pixelflare.cc/alice/vacation-2024/sunset.jpg
https://pixelflare.cc/alice/vacation-2024/sunset.jpg?w=800&h=600&fit=cover&q=85

Parameters:

• owner (path) required
  • Type: string
  • Description: Image owner username
• album (path) required
  • Type: string
  • Description: Album slug
• filename (path) required
  • Type: string
  • Description: Image filename (with extension)
• w (query) optional
  • Type: integer
  • Description: Width in pixels (1-9999)
• h (query) optional
  • Type: integer
  • Description: Height in pixels (1-9999)
• fit (query) optional
  • Type: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze"
  • Description: Resize fit mode
• q (query) optional
  • Type: integer
  • Description: Quality (1-100)
• f (query) optional
  • Type: "auto" | "avif" | "webp" | "jpeg" | "png"
  • Description: Output format
• g (query) optional
  • Type: "auto" | "center" | "left" | "right" | "top" | "bottom" | "face"
  • Description: Gravity/focus point
• trim (query) optional
  • Type: string
  • Description: Crop margins (e.g., top:10,left:20)
• blur (query) optional
  • Type: integer
  • Description: Blur radius (1-250)
• sharpen (query) optional
  • Type: integer
  • Description: Sharpen amount (1-10)
• br (query) optional
  • Type: number
  • Description: Brightness (0.5-2.0)
• co (query) optional
  • Type: number
  • Description: Contrast (0.5-2.0)
• sat (query) optional
  • Type: number
  • Description: Saturation (0-2.0)
• gam (query) optional
  • Type: number
  • Description: Gamma (0.5-2.0)
• r (query) optional
  • Type: "0" | "90" | "180" | "270"
  • Description: Rotation angle (0, 90, 180, 270)
• flip (query) optional
  • Type: "h" | "v" | "hv"
  • Description: Flip direction (h=horizontal, v=vertical, hv=both)
• bg (query) optional
  • Type: string
  • Description: Background color (hex without #)
• meta (query) optional
  • Type: "keep" | "copyright" | "none"
  • Description: Metadata handling

Responses:

200: Image successfully served

403: Image is private and requires authentication

404: Image not found

410: Image has been deleted

429: Too many custom transformation requests

---

GET /{owner}/{album}/{filename}/{variant}

Serve a specific image variant (resized/optimized version) or apply custom transformations via query parameters.

Path format: /{owner}/{album}/{filename}/{variant}

Available variants: original, w128, w256, w512, w1024, w1536, w2048, thumb, og-image

Features:

• On-demand image transformation (if variant doesn't exist)
• Automatic format optimization (WebP when supported)
• Smart caching (variants are cached after first generation)
• Fallback to original for unsupported formats (e.g., SVG)
• Custom transformations via query parameters override variant preset

Examples:

https://pixelflare.cc/alice/vacation-2024/sunset.jpg/w1024
https://pixelflare.cc/alice/vacation-2024/sunset.jpg/w1024?blur=10&sharpen=5

When query params are provided, they override the variant preset.

Parameters:

• owner (path) required
  • Type: string
  • Description: Image owner username
• album (path) required
  • Type: string
  • Description: Album slug
• filename (path) required
  • Type: string
  • Description: Image filename (with extension)
• variant (path) required
  • Type: "original" | "w128" | "w256" | "w512" | "w1024" | "w1536" | "w2048" | "thumb" | "og-image"
  • Description:
• w (query) optional
  • Type: integer
  • Description: Width in pixels (1-9999)
• h (query) optional
  • Type: integer
  • Description: Height in pixels (1-9999)
• fit (query) optional
  • Type: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze"
  • Description: Resize fit mode
• q (query) optional
  • Type: integer
  • Description: Quality (1-100)
• f (query) optional
  • Type: "auto" | "avif" | "webp" | "jpeg" | "png"
  • Description: Output format
• g (query) optional
  • Type: "auto" | "center" | "left" | "right" | "top" | "bottom" | "face"
  • Description: Gravity/focus point
• trim (query) optional
  • Type: string
  • Description: Crop margins (e.g., top:10,left:20)
• blur (query) optional
  • Type: integer
  • Description: Blur radius (1-250)
• sharpen (query) optional
  • Type: integer
  • Description: Sharpen amount (1-10)
• br (query) optional
  • Type: number
  • Description: Brightness (0.5-2.0)
• co (query) optional
  • Type: number
  • Description: Contrast (0.5-2.0)
• sat (query) optional
  • Type: number
  • Description: Saturation (0-2.0)
• gam (query) optional
  • Type: number
  • Description: Gamma (0.5-2.0)
• r (query) optional
  • Type: "0" | "90" | "180" | "270"
  • Description: Rotation angle (0, 90, 180, 270)
• flip (query) optional
  • Type: "h" | "v" | "hv"
  • Description: Flip direction (h=horizontal, v=vertical, hv=both)
• bg (query) optional
  • Type: string
  • Description: Background color (hex without #)
• meta (query) optional
  • Type: "keep" | "copyright" | "none"
  • Description: Metadata handling

Responses:

200: Image variant successfully served (or original if variant generation not supported)

400: Invalid variant specified

403: Image is private and requires authentication

404: Image not found

410: Image has been deleted

429: Rate limit exceeded for variant generation

---

---

Additional Resources

• Interactive API Docs - Test endpoints with Scalar UI
• OpenAPI Spec - Download the OpenAPI JSON specification
• Authentication Guide - Learn about API authentication
• Rate Limiting - Understand rate limits

Support

For issues or questions, visit:

• GitHub Issues
• Documentation
• Community Forum