API Reference

PixelFlare provides a RESTful API for programmatic image management.

Base URL

https://api.yourdomain.com/v1

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer <your_api_key>

Or via Cloudflare Access JWT:

Cf-Access-Jwt-Assertion: <jwt_token>

Images

List Images

GET /v1/images

Query parameters:

• limit - Number of results (default: 50, max: 100)
• cursor - Pagination cursor
• album - Filter by album slug
• tag - Filter by tag
• include_deleted - Include soft-deleted images

Response:

{
  "data": [
    {
      "id": "abc123",
      "filename": "beach.jpg",
      "album": "vacation",
      "owner": "alice",
      "content_type": "image/jpeg",
      "size": 1048576,
      "tags": ["beach", "summer"],
      "is_private": false,
      "created_at": "2025-01-01T00:00:00Z",
      "cdn_url": "https://cdn.example.com/alice/vacation/beach.jpg"
    }
  ],
  "next_cursor": "xyz789"
}

Create Image

POST /v1/images

Request:

{
  "filename": "beach.jpg",
  "album": "vacation",
  "tags": ["beach", "summer"],
  "alt": "Sunset over the beach",
  "is_private": false,
  "turnstile_token": "..."
}

Response includes upload_url for uploading the file.

Get Image

GET /v1/images/:id

Update Image

PATCH /v1/images/:id

Request:

{
  "filename": "beach-sunset.jpg",
  "album": "photos",
  "tags": ["beach", "sunset"],
  "alt": "Beautiful sunset"
}

Delete Image

DELETE /v1/images/:id

Soft deletes the image. Can be restored within 30 days.

Generate Variants

POST /v1/images/:id/variants

Request:

{
  "variants": ["w512", "thumb"]
}

Response: 202 Accepted with ImageResource

Albums

List Albums

GET /v1/albums

Create Album

POST /v1/albums

Request:

{
  "slug": "vacation-2025",
  "title": "Vacation 2025",
  "description": "Summer vacation photos"
}

Get Album

GET /v1/albums/:slug

Update Album

PATCH /v1/albums/:slug

Delete Album

DELETE /v1/albums/:slug

Tags

List Tags

GET /v1/tags

Response:

{
  "data": [
    { "tag": "beach", "count": 15 },
    { "tag": "vacation", "count": 23 }
  ]
}

API Keys

List API Keys

GET /v1/keys

Create API Key

POST /v1/keys

Request:

{
  "name": "My App",
  "scopes": ["images:read", "images:write"]
}

Response (key only shown once):

{
  "id": "key_abc123",
  "name": "My App",
  "key": "pxf_abc123...",
  "scopes": ["images:read", "images:write"],
  "created_at": "2025-01-01T00:00:00Z"
}

Revoke API Key

DELETE /v1/keys/:id

CDN URLs

Images are served from the CDN:

https://cdn.yourdomain.com/{owner}/{album}/{filename}
https://cdn.yourdomain.com/{owner}/{album}/{filename}/{variant}
https://cdn.yourdomain.com/{shortId}

Available variants:

• w128, w256, w512, w1024, w1536, w2048 - Width-constrained
• thumb - 128x128 square thumbnail
• og-image - 1200x630 social media card

Rate Limits

• Upload: 10 requests/minute burst, 1000/day
• API: Standard Cloudflare limits
• CDN Variant Miss: 100 requests/minute per IP

Error Responses

All errors follow this format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable message",
  "details": {}
}

Common error codes:

• INVALID_REQUEST - Malformed request
• UNAUTHORIZED - Missing or invalid authentication
• FORBIDDEN - Authenticated but not authorized
• NOT_FOUND - Resource not found
• RATE_LIMITED - Rate limit exceeded
• INVALID_FILE_TYPE - Unsupported image format
• FILE_TOO_LARGE - File exceeds 100MB limit

Examples

Upload Workflow

# 1. Create image metadata
curl -X POST https://api.yourdomain.com/v1/images \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.jpg", "album": "photos"}'

# Response includes upload_url

# 2. Upload file to signed URL
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

# 3. Image is now available on CDN
# https://cdn.yourdomain.com/owner/photos/photo

Filtering

# Get all images in an album
curl "https://api.yourdomain.com/v1/images?album=vacation" \
  -H "Authorization: Bearer $API_KEY"

# Get all images with a tag
curl "https://api.yourdomain.com/v1/images?tag=beach" \
  -H "Authorization: Bearer $API_KEY"