Authentication Module Media Trips Lists Locations Tags Jobs Albums OpenAPI Spec

Clippy Travels API

REST API for accessing travel photos and trips

Authentication

All API endpoints require authentication via API key:

API keys have scopes: read (GET endpoints), write (create/update), admin (full access)

Module

GET /api/module/active Public Get active website module

Returns the currently active website module/theme. This is a public endpoint that does not require authentication.

GET /api/module/active

{
  "success": true,
  "active": "windows",
  "module": {
    "name": "Windows",
    "directory": "windows"
  }
}

Available modules:

  • classic - Classic travel website layout
  • windows - Windows-inspired tile design

Media

GET /api/media/search Read Search and filter photos
ParameterTypeDescription
trip_idint|stringFilter by trip ID (comma-separated for multiple)
tagsstringFilter by tag slugs or IDs (comma-separated)
exclude_tagsstringExclude photos with these tags
date_fromdateFilter by date (YYYY-MM-DD)
date_todateFilter by date (YYYY-MM-DD)
yearintFilter by year
monthintFilter by month (1-12)
typestringFilter by type: photo, video
has_locationboolFilter by GPS data presence
bboxstringBounding box: sw_lat,sw_lng,ne_lat,ne_lng
camerastringFilter by camera make/model
limitintResults per page (max 100, default 50)
offsetintPagination offset
sortstringSort field: taken_at, created_at, display_order
orderstringSort order: ASC, DESC
 
GET /api/media/search?tags=food,travel&limit=20

{
  "success": true,
  "data": [
    {
      "id": 123,
      "url": "https://...",
      "thumbnail": "https://...",
      "width": 4000,
      "height": 3000,
      "taken_at": "2024-01-15 14:30:00",
      "location": { "lat": 35.6762, "lng": 139.6503 },
      "trip": { "id": 1, "name": "Tokyo 2024", "slug": "tokyo-2024" },
      "tags": [
        { "id": 1, "name": "Food", "slug": "food", "color": "#f59e0b" }
      ]
    }
  ],
  "pagination": { "total": 150, "limit": 20, "offset": 0, "has_more": true }
}
GET /api/media/get Read Get single photo by ID
ParameterTypeDescription
idintRequired Photo ID
 
GET /api/media/get?id=123

{
  "success": true,
  "data": {
    "id": 123,
    "url": "https://cdn.example.com/photos/abc123.jpg",
    "thumbnail": "https://cdn.example.com/thumbs/abc123.jpg",
    "width": 4000,
    "height": 3000,
    "taken_at": "2024-01-15 14:30:00",
    "location": { "lat": 35.6762, "lng": 139.6503 },
    "trip": { "id": 1, "name": "Tokyo 2024", "slug": "tokyo-2024" },
    "camera_info": { "make": "Sony", "model": "A7IV", "lens": "24-70mm f/2.8" },
    "exposure_info": { "aperture": "f/2.8", "shutter_speed": "1/250", "iso": 400 },
    "navigation": { "prev_id": 122, "next_id": 124 }
  }
}
GET /api/media/filters Read Get available filter options

Returns available years, cameras, and other filter options based on existing photos.

GET /api/media/filters

{
  "success": true,
  "filters": {
    "years": [
      { "year": 2024, "count": 450 },
      { "year": 2023, "count": 320 }
    ],
    "cameras": [
      { "make": "Sony", "model": "A7IV", "count": 280 },
      { "make": "Apple", "model": "iPhone 15 Pro", "count": 150 }
    ],
    "trips": [
      { "id": 1, "name": "Tokyo 2024", "slug": "tokyo-2024", "photo_count": 125 }
    ],
    "date_range": { "min": "2023-01-15", "max": "2024-12-20" },
    "media_types": { "photo": 720, "video": 50 },
    "location": { "with_location": 680, "without_location": 90 }
  }
}

Trips

GET /api/trips/list Read List all published trips

Returns all published trips with photo counts.

GET /api/trips/list

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Tokyo 2024",
      "slug": "tokyo-2024",
      "location": "Tokyo, Japan",
      "description": "Spring trip exploring Tokyo",
      "trip_date": "2024-03-15",
      "photo_count": 125,
      "cover_photo": { "id": 45, "thumbnail": "https://..." }
    },
    {
      "id": 2,
      "name": "Iceland Adventure",
      "slug": "iceland-adventure",
      "location": "Iceland",
      "trip_date": "2024-01-10",
      "photo_count": 89
    }
  ]
}
GET /api/trips/get Read Get single trip by ID or slug
ParameterTypeDescription
idintTrip ID
slugstringTrip slug (alternative to ID)
 
GET /api/trips/get?slug=tokyo-2024

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Tokyo 2024",
    "slug": "tokyo-2024",
    "location": "Tokyo, Japan",
    "description": "Spring trip exploring Tokyo and surrounding areas",
    "trip_date": "2024-03-15",
    "photo_count": 125,
    "video_count": 8,
    "date_range": { "start": "2024-03-15", "end": "2024-03-22" },
    "cover_photo": { "id": 45, "url": "https://...", "thumbnail": "https://..." },
    "tags": [
      { "id": 1, "name": "Travel", "slug": "travel", "color": "#3b82f6" }
    ]
  }
}

Lists (Curated Collections)

GET /api/lists/list Read List all curated lists
ParameterTypeDescription
include_unpublishedboolInclude unpublished lists
include_hiddenboolInclude hidden lists
 
GET /api/lists/list

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Best of 2024",
      "slug": "best-of-2024",
      "description": "Top photos from 2024",
      "photo_count": 25,
      "is_published": true,
      "has_password": false,
      "thumbnail": { "url": "https://...", "thumbnail": "https://..." }
    }
  ],
  "total": 1
}
GET /api/lists/get Read Get single list with photos
ParameterTypeDescription
idintList ID
slugstringList slug (alternative to ID)
passwordstringPassword if list is protected
 
GET /api/lists/get?slug=best-of-2024

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Best of 2024",
    "slug": "best-of-2024",
    "photos": [
      { "id": 123, "url": "https://...", "thumbnail": "https://..." }
    ]
  }
}
POST /api/lists/create Write Create a new list
ParameterTypeDescription
namestringRequired List name
descriptionstringOptional description
passwordstringOptional password protection
is_publishedboolPublished status
is_hiddenboolHidden (direct link only)
publish_atdatetimeScheduled publish date
POST /api/lists/add-photo Write Add photo(s) to list
ParameterTypeDescription
list_idintRequired List ID
photo_idintSingle photo ID
photo_idsarrayMultiple photo IDs
POST /api/lists/remove-photo Write Remove photo(s) from list
ParameterTypeDescription
list_idintRequired List ID
photo_idintSingle photo ID
photo_idsarrayMultiple photo IDs
DELETE /api/lists/delete Admin Delete a list
ParameterTypeDescription
idintRequired List ID

Locations

GET /api/locations/countries Read List countries with photo counts 
GET /api/locations/countries

{
  "success": true,
  "data": [
    {
      "country": "Japan",
      "photo_count": 450,
      "trips": [{ "id": 1, "name": "Tokyo 2024", "slug": "tokyo-2024", "photo_count": 125 }],
      "lists": [{ "id": 1, "name": "Best of 2024", "slug": "best-of-2024", "photo_count": 15 }],
      "thumbnail": {
        "photo_id": 123,
        "url": "https://cdn.example.com/photo.jpg",
        "thumbnail_url": "https://cdn.example.com/thumb.jpg"
      }
    }
  ],
  "total": 15
}
GET /api/locations/territories Read List territories/regions with photo counts
ParameterTypeDescription
countrystringFilter by country name
 
GET /api/locations/territories?country=United States

{
  "success": true,
  "data": [
    {
      "region": "Alaska",
      "country": "United States",
      "photo_count": 85,
      "trips": [{ "id": 2, "name": "Alaska 2024", "slug": "alaska-2024", "photo_count": 85 }],
      "lists": [],
      "thumbnail": {
        "photo_id": 456,
        "url": "https://cdn.example.com/photo.jpg",
        "thumbnail_url": "https://cdn.example.com/thumb.jpg"
      }
    }
  ],
  "total": 5
}
GET /api/locations/cities Read List cities with photo counts
ParameterTypeDescription
countrystringFilter by country name
 
GET /api/locations/cities?country=Japan

{
  "success": true,
  "data": [
    { "city": "Tokyo", "country": "Japan", "photo_count": 280 },
    { "city": "Kyoto", "country": "Japan", "photo_count": 95 }
  ]
}
GET /api/locations/region Read Query photos by bounding box
ParameterTypeDescription
lat1floatRequired SW latitude
lng1floatRequired SW longitude
lat2floatRequired NE latitude
lng2floatRequired NE longitude
limitintResults per page (max 100)
offsetintPagination offset
 
GET /api/locations/region?lat1=35.6&lng1=139.6&lat2=35.8&lng2=139.9

{
  "success": true,
  "data": [...photos...],
  "pagination": { "total": 280, "limit": 50, "offset": 0 },
  "bounding_box": { "sw": {...}, "ne": {...} }
}
GET /api/locations/thumbnail Read Get representative photo for location
ParameterTypeDescription
countrystringCountry name
citystringCity name
 
GET /api/locations/thumbnail?country=Japan

{
  "success": true,
  "data": {
    "photo": { "id": 123, "url": "https://...", "thumbnail": "https://..." },
    "location": { "country": "Japan" }
  }
}

Tags

GET /api/tags/list Read List all tags
ParameterTypeDescription
include_statsboolInclude photo/trip counts
 
GET /api/tags/list?include_stats=true

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Food",
      "slug": "food",
      "color": "#f59e0b",
      "description": "Food and restaurant photos",
      "photo_count": 89,
      "trip_count": 5
    },
    {
      "id": 2,
      "name": "Landscape",
      "slug": "landscape",
      "color": "#22c55e",
      "photo_count": 156,
      "trip_count": 8
    }
  ]
}
POST /api/tags/create Write Create a new tag
ParameterTypeDescription
namestringRequired Tag name
colorstringHex color (default: #6366f1)
descriptionstringOptional description
 
POST /api/tags/create
Content-Type: application/json

{ "name": "Architecture", "color": "#8b5cf6", "description": "Buildings and structures" }

{
  "success": true,
  "data": {
    "id": 5,
    "name": "Architecture",
    "slug": "architecture",
    "color": "#8b5cf6",
    "description": "Buildings and structures"
  }
}
POST /api/tags/photo Write Add/remove tag from photo(s)
ParameterTypeDescription
photo_idintSingle photo ID
photo_idsarrayMultiple photo IDs (for bulk)
tag_idintSingle tag ID
tag_idsarrayMultiple tag IDs (for bulk)
actionstring"add" or "remove" (default: add)
 
POST /api/tags/photo
Content-Type: application/json

{ "photo_ids": [123, 124, 125], "tag_id": 1, "action": "add" }

{
  "success": true,
  "message": "Tag added to 3 photos",
  "affected": 3
}
POST /api/tags/trip Write Add/remove tag from trip
ParameterTypeDescription
trip_idintRequired Trip ID
tag_idintTag ID (for add/remove)
tag_idsarrayTag IDs (for "set" action)
actionstring"add", "remove", or "set"
 
POST /api/tags/trip
Content-Type: application/json

{ "trip_id": 1, "tag_ids": [1, 2, 3], "action": "set" }

{
  "success": true,
  "message": "Trip tags updated",
  "tags": [
    { "id": 1, "name": "Travel", "slug": "travel" },
    { "id": 2, "name": "Food", "slug": "food" },
    { "id": 3, "name": "City", "slug": "city" }
  ]
}

Jobs

GET /api/jobs/status Admin Get job status
ParameterTypeDescription
idintRequired Job ID
 
GET /api/jobs/status?id=42

{
  "success": true,
  "data": {
    "id": 42,
    "type": "import",
    "status": "running",
    "progress": 45,
    "total_items": 100,
    "processed_items": 45,
    "failed_items": 2,
    "created_at": "2024-01-15 10:30:00",
    "started_at": "2024-01-15 10:30:05"
  }
}
POST /api/jobs/cancel Admin Cancel a pending/running job
ParameterTypeDescription
job_idintRequired Job ID
 
POST /api/jobs/cancel
Content-Type: application/json

{ "job_id": 42 }

{ "success": true, "message": "Job cancelled" }
POST /api/jobs/resume Admin Resume a paused/cancelled job
ParameterTypeDescription
job_idintRequired Job ID
 
POST /api/jobs/resume
Content-Type: application/json

{ "job_id": 42 }

{ "success": true, "message": "Job resumed" }
POST /api/jobs/revert Admin Revert a completed job (delete imported photos)
ParameterTypeDescription
job_idintRequired Job ID
 
POST /api/jobs/revert
Content-Type: application/json

{ "job_id": 42 }

{ "success": true, "message": "Job reverted, 45 photos deleted" }

Albums (Sync)

GET /api/albums/diff Admin Get sync diff between local and Immich
ParameterTypeDescription
trip_idintRequired Trip ID
album_idstringRequired Immich album ID
 
GET /api/albums/diff?trip_id=1&album_id=abc-123

{
  "success": true,
  "data": {
    "to_add": 15,
    "to_remove": 3,
    "unchanged": 107,
    "new_assets": [
      { "id": "xyz-456", "filename": "IMG_001.jpg", "taken_at": "2024-01-15" }
    ],
    "removed_assets": [
      { "id": "xyz-789", "filename": "IMG_050.jpg" }
    ]
  }
}
POST /api/albums/sync Admin Execute album sync
ParameterTypeDescription
trip_idintRequired Trip ID
album_idstringRequired Immich album ID
actionstring"full", "add", or "remove"
 
POST /api/albums/sync
Content-Type: application/json

{ "trip_id": 1, "album_id": "abc-123", "action": "full" }

{
  "success": true,
  "data": {
    "job_id": 43,
    "status": "pending",
    "action": "full",
    "items_to_process": 15
  }
}