Docs
Developer Portal

API reference

Photos

Your photo library: the timeline, photos, albums, links, uploads, Takeout imports, tokens, exports and your activity log.
Read the Guide
GET/v1/hooks/photos/links/:token

What a Photos link opens: its title, how many photos, whether locations are kept and downloads allowed, or that it needs its password. No authentication; the visit is in the owner's log.

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

curl 'https://api.cactive.com.au/v1/hooks/photos/links/{token}'
Send it from this page with your session or a key.

Response 200

{
  needsPassword: true
} | {
  needsPassword: false
  title: string
  count: number
  keepLocation: boolean
  download: boolean
  expiresAt?: number
  owner?: string
}
POST/v1/hooks/photos/links/:token/unlock

Checks a link's password and answers a 12-hour grant (send it as x-si-link-grant). 10 wrong passwords per link per 15 minutes lock it. No authentication.

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

Request body

  • passwordstringrequired

    1–200 characters.

curl -X POST 'https://api.cactive.com.au/v1/hooks/photos/links/{token}/unlock' \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  grant: string
  expiresAt: number
}
GET/v1/hooks/photos/links/:token/photos

The link's photos (thumbnails), oldest first, in pages.

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

Query parameters

  • cursorstring

    Up to 2,000 characters.

curl 'https://api.cactive.com.au/v1/hooks/photos/links/{token}/photos'
Send it from this page with your session or a key.

Response 200

{
  title: string
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    name: string
    takenAt: number
    width?: number
    height?: number
    duration?: number
    thumbUrl?: string
    location?: {
      lat: number
      lon: number
    }
  }[]
  cursor?: string
}
GET/v1/hooks/photos/links/:token/photos/:photoId

One photo through the link: its preview (and video), or the original when downloads are on (download=1).

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Query parameters

  • download"0" | "1"
curl 'https://api.cactive.com.au/v1/hooks/photos/links/{token}/photos/{photoId}'
Send it from this page with your session or a key.

Response 200

{
  name: string
  previewUrl?: string
  videoUrl?: string
  motionUrl?: string
  downloadUrl?: string
  location?: {
    lat: number
    lon: number
  }
}
POST/v1/hooks/photos/links/:token/archives

A ZIP of everything in the link (when downloads are on).

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

curl -X POST 'https://api.cactive.com.au/v1/hooks/photos/links/{token}/archives'
Send it from this page with your session or a key.

Response 202

{
  archive: {
    archiveId: string
    status: "queued" | "building" | "ready" | "failed"
    name: string
    files: number
    bytes: number
    url?: string
    error?: string
  }
}
GET/v1/hooks/photos/links/:token/archives/:archiveId

A link's ZIP: its status, and a one-hour download link once ready. No authentication.

Auth
None.

Path parameters

  • token

    A secret from a link: an issue automation rule's incoming-webhook token (shown once when issued), a map's share link, a notification recipient's confirm and unsubscribe link, a Drive public link (/l/<token>), a Vehicles drive's share link, or a Mirage interaction's token (itk_…, sent with the interaction, good for 15 minutes), or the token in the link to a file of a message Mirage sent to Discord, or a Marketing link's sealed token (a tracked click, the open pixel, unsubscribe and the preference centre, a double opt-in confirmation); or a Food recipe's public link (/r/<token>) or a household's calendar feed.

  • archiveId

    ZIP download id (zip_…).

curl 'https://api.cactive.com.au/v1/hooks/photos/links/{token}/archives/{archiveId}'
Send it from this page with your session or a key.

Response 200

{
  archive: {
    archiveId: string
    status: "queued" | "building" | "ready" | "failed"
    name: string
    files: number
    bytes: number
    url?: string
    error?: string
  }
}
GET/v1/me/photos/library

The library: its settings, storage (shared with Drive's personal space) and counts. Made on first use.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/library' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  library: {
    driveId: string
    settings: {
      ai: {
        faces: boolean
        objects: boolean
        memories: boolean
      }
      keepLocation: boolean
      vehicles: boolean
    }
    usage: {
      bytes: number
      files: number
      limit: number
    }
    counts: {
      photos: number
      favourites: number
      albums: number
      archive: number
      trash: number
    }
  }
}
PATCH/v1/me/photos/settings

Opt-in features (faces, objects and text, memories: nothing runs while off), whether new links keep locations, and whether Vehicles may suggest photos for the person's own cars' drives (vehicles, on until turned off; vehiclesNoticed closes the note that it's on; docs/vehicles/drive-media.md).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • aiobject
  • ai.facesboolean
  • ai.objectsboolean
  • ai.memoriesboolean
  • keepLocationboolean
  • vehiclesboolean
  • vehiclesNoticedtrue

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/settings' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai": {
      "faces": true,
      "objects": true,
      "memories": true
    },
    "keepLocation": true,
    "vehicles": true
  }'
Send it from this page with your session or a key.

Response 200

{
  library: {
    driveId: string
    settings: {
      ai: {
        faces: boolean
        objects: boolean
        memories: boolean
      }
      keepLocation: boolean
      vehicles: boolean
    }
    usage: {
      bytes: number
      files: number
      limit: number
    }
    counts: {
      photos: number
      favourites: number
      albums: number
      archive: number
      trash: number
    }
  }
}
GET/v1/me/photos/days

Photos per local day on the timeline (newest first), for the scrubber and the grid's layout.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/days' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  days: {
    day: string
    count: number
  }[]
}
GET/v1/me/photos/timeline

Timeline photos taken between from and to (ms), newest first.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • cursorstring

    Up to 2,000 characters.

  • limitinteger

    1–500. Coerced from a string.

  • frominteger

    Coerced from a string.

  • tointeger

    Coerced from a string.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/timeline' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }[]
  cursor?: string
}
GET/v1/me/photos/lists/:list

Favourites, the archive or the trash, newest first.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • list

    favourites, archive or trash.

Query parameters

  • cursorstring

    Up to 2,000 characters.

  • limitinteger

    1–500. Coerced from a string.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/lists/{list}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }[]
  cursor?: string
}
POST/v1/me/photos/trash/empty

Deletes everything in the trash for good (the files from Drive too).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/trash/empty' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  deleted: number
}
POST/v1/me/photos/photos/batch

Several photos by id (the map's pins, a selection), in the order asked.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • photoIdsstring[]required

    1–200 items. Each 3–64 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/photos/batch' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "photoIds": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }[]
}
POST/v1/me/photos/photos/state

Favourite, unfavourite, archive, unarchive, move to the trash, restore or delete forever (trashed photos only).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • photoIdsstring[]required

    1–500 items. Each 3–64 characters.

  • action"favourite" | "unfavourite" | "archive" | "unarchive" | "trash" | "restore" | "delete"required

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/photos/state' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "photoIds": [
      "example"
    ],
    "action": "favourite"
  }'
Send it from this page with your session or a key.

Response 200

{
  changed: string[]
}
GET/v1/me/photos/photos/:photoId

A photo's details: when (and from where that's known) and where it was taken, camera, size, description, albums, and one-hour links to show it (and a Live Photo's video). Logged as opened.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/photos/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photo: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
    description?: string
    location?: {
      lat: number
      lon: number
      altitude?: number
      from: "file" | "edit" | "sidecar"
    }
    camera?: {
      make?: string
      model?: string
      lens?: string
      exposure?: string
      fNumber?: number
      iso?: number
      focal?: number
    }
    takenFrom: "file" | "client" | "edit" | "added" | "sidecar"
    local?: string
    offset?: number
    source: "mcp" | "agent" | "drive" | "edited" | "web" | "shortcut" | "takeout" | "picker" | "mirage"
    addedAt: number
    displayUrl?: string
    motionUrl?: string
    albums: {
      albumId: string
      title: string
    }[]
    versions: number
  }
}
PATCH/v1/me/photos/photos/:photoId

Description, capture time (takenAt, ms; null goes back to the file's) and location (null removes it; "file" goes back to the file's).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Request body

  • descriptionstringor null

    Up to 2,000 characters.

  • favouriteboolean
  • takenAtintegeror null
  • locationobject | null | "file"

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/photos/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "example",
    "favourite": true,
    "takenAt": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  photo: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
    description?: string
    location?: {
      lat: number
      lon: number
      altitude?: number
      from: "file" | "edit" | "sidecar"
    }
    camera?: {
      make?: string
      model?: string
      lens?: string
      exposure?: string
      fNumber?: number
      iso?: number
      focal?: number
    }
    takenFrom: "file" | "client" | "edit" | "added" | "sidecar"
    local?: string
    offset?: number
    source: "mcp" | "agent" | "drive" | "edited" | "web" | "shortcut" | "takeout" | "picker" | "mirage"
    addedAt: number
    displayUrl?: string
    motionUrl?: string
    albums: {
      albumId: string
      title: string
    }[]
    versions: number
  }
}
GET/v1/me/photos/photos/:photoId/original

A one-hour link to the original (inline=1 to show it; motion=1 for a Live Photo's video).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Query parameters

  • inline"0" | "1"
  • motion"0" | "1"

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/photos/{photoId}/original' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  url: string
  name: string
  mime: string
  size?: number
  expiresIn: number
}
PUT/v1/me/photos/photos/:photoId/poster

A video's poster frame, made in the browser (JPEG or WebP, base64, up to 1 MB).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • photoId

    Photo id: the photo's file in Drive (fil_…).

Request body

  • imagestringrequired

    10–1,400,000 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X PUT 'https://api.cactive.com.au/v1/me/photos/photos/{photoId}/poster' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  photo: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }
}
GET/v1/me/photos/search

Search by when (from/to, ms), where (a box: south,west,north,east; or near=lat,lon with km), words in names and descriptions, type and favourites.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • cursorstring

    Up to 2,000 characters.

  • limitinteger

    1–500. Coerced from a string.

  • frominteger

    Coerced from a string.

  • tointeger

    Coerced from a string.

  • bboxstring

    Up to 100 characters.

  • nearstring

    Up to 60 characters.

  • kmnumber

    0.1–5000. Coerced from a string.

  • qstring

    Up to 200 characters.

  • type"photo" | "video" | "live" | "raw"
  • favourite"0" | "1"
  • archived"0" | "1"

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/search' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }[]
  cursor?: string
  total: number
  truncated: boolean
}
GET/v1/me/photos/map

Every located photo as a point (id, latitude, longitude, time), for the map.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/map' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  points: [string, number, number, number][]
}
GET/v1/me/photos/albums

Your albums, most recently changed first, with covers and how many links show each.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/albums' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  albums: {
    albumId: string
    title: string
    description?: string
    count: number
    coverId?: string
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    createdAt: number
    updatedAt: number
    links: number
  }[]
}
POST/v1/me/photos/albums

Creates an album, optionally with photos.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • titlestringrequired

    1–200 characters.

  • descriptionstring

    Up to 2,000 characters.

  • photoIdsstring[]

    Up to 500 items. Each 3–64 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/albums' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Example"
  }'
Send it from this page with your session or a key.

Response 201

{
  album: {
    albumId: string
    title: string
    description?: string
    count: number
    coverId?: string
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    createdAt: number
    updatedAt: number
    links: number
  }
}
GET/v1/me/photos/albums/:albumId

An album and a page of its photos, in its sort order.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • albumId

    Album id (alb_…).

Query parameters

  • cursorstring

    Up to 2,000 characters.

  • limitinteger

    1–500. Coerced from a string.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  album: {
    albumId: string
    title: string
    description?: string
    count: number
    coverId?: string
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    createdAt: number
    updatedAt: number
    links: number
  }
  photos: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }[]
  cursor?: string
}
PATCH/v1/me/photos/albums/:albumId

Renames an album, changes its description, cover (a photo in it; null for the first) or order.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • albumId

    Album id (alb_…).

Request body

  • titlestring

    1–200 characters.

  • descriptionstringor null

    Up to 2,000 characters.

  • coverIdstringor null

    3–64 characters.

  • sort"oldest" | "newest" | "added"

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Example",
    "description": "example",
    "coverId": "<coverId>"
  }'
Send it from this page with your session or a key.

Response 200

{
  album: {
    albumId: string
    title: string
    description?: string
    count: number
    coverId?: string
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    createdAt: number
    updatedAt: number
    links: number
  }
}
DELETE/v1/me/photos/albums/:albumId

Deletes the album (its photos stay in the library) and turns off its links.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • albumId

    Album id (alb_…).

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

POST/v1/me/photos/albums/:albumId/photos

Adds photos to an album (up to 20,000 in one album). Ones already there stay.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • albumId

    Album id (alb_…).

Request body

  • photoIdsstring[]required

    1–500 items. Each 3–64 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}/photos' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "photoIds": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  album: {
    albumId: string
    title: string
    description?: string
    count: number
    coverId?: string
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    createdAt: number
    updatedAt: number
    links: number
  }
}
POST/v1/me/photos/albums/:albumId/photos/remove

Takes photos out of an album; they stay in the library.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • albumId

    Album id (alb_…).

Request body

  • photoIdsstring[]required

    1–500 items. Each 3–64 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}/photos/remove' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "photoIds": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  album: {
    albumId: string
    title: string
    description?: string
    count: number
    coverId?: string
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    createdAt: number
    updatedAt: number
    links: number
  }
}
GET/v1/me/photos/links

Links anyone can open: albums and chosen photos.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  links: {
    linkId: string
    url: string
    albumId?: string
    photoCount?: number
    title: string
    keepLocation: boolean
    download: boolean
    expiresAt?: number
    hasPassword: boolean
    visits: number
    lastVisitAt?: number
    createdAt: number
  }[]
}
POST/v1/me/photos/links

A link to an album or to chosen photos: view only, locations removed unless keepLocation, optional expiry and password.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • albumIdstring

    3–64 characters.

  • photoIdsstring[]

    1–500 items. Each 3–64 characters.

  • titlestring

    Up to 200 characters.

  • keepLocationboolean
  • downloadboolean
  • expiresAtinteger

    > 0.

  • passwordstring

    4–200 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/links' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "albumId": "<albumId>",
    "photoIds": [
      "example"
    ],
    "title": "Example"
  }'
Send it from this page with your session or a key.

Response 201

{
  link: {
    linkId: string
    url: string
    albumId?: string
    photoCount?: number
    title: string
    keepLocation: boolean
    download: boolean
    expiresAt?: number
    hasPassword: boolean
    visits: number
    lastVisitAt?: number
    createdAt: number
  }
}
PATCH/v1/me/photos/links/:linkId

Changes a link: password null removes it; rotate makes a new address (the old one stops working).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • linkId

    Link id (ilk_… for issue links, irl_… for remote links, plk_… for Photos links, lnk_… for sharing links and a drive's share links: not the link's secret).

Request body

  • titlestring

    Up to 200 characters.

  • keepLocationboolean
  • downloadboolean
  • expiresAtintegeror null

    > 0.

  • passwordstringor null

    4–200 characters.

  • rotateboolean

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/links/{linkId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Example",
    "keepLocation": true,
    "download": true
  }'
Send it from this page with your session or a key.

Response 200

{
  link: {
    linkId: string
    url: string
    albumId?: string
    photoCount?: number
    title: string
    keepLocation: boolean
    download: boolean
    expiresAt?: number
    hasPassword: boolean
    visits: number
    lastVisitAt?: number
    createdAt: number
  }
}
DELETE/v1/me/photos/links/:linkId

Turns a link off: it stops working at once.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • linkId

    Link id (ilk_… for issue links, irl_… for remote links, plk_… for Photos links, lnk_… for sharing links and a drive's share links: not the link's secret).

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/links/{linkId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

POST/v1/me/photos/uploads/check

Which of these SHA-256 hashes are already in the library (skip uploading them).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • hashesstring[]required

    1–1,000 items. Each matches ^[0-9a-f]{64}$.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
  • 403This token can't do that (it needs photos:upload).
curl -X POST 'https://api.cactive.com.au/v1/me/photos/uploads/check' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "hashes": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  existing: {
    [key: string]: string
  }
}
POST/v1/me/photos/uploads

Starts an upload into the library: answers Drive's part links (PUT each part, then complete), or duplicate with the photo when sha256 is already there. singlePart (iPhone Shortcuts) sends the whole file to one link; its size may then be left out.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • namestringrequired

    1–255 characters.

  • extstring

    Up to 10 characters.

  • sizeinteger

    ≥ 0.

  • mimestring

    Up to 200 characters.

  • sha256string

    Matches ^[0-9a-f]{64}$.

  • takenAtinteger
  • albumIdstring

    3–64 characters.

  • pairWithstring

    3–64 characters.

  • singlePartboolean
  • source"web" | "shortcut" | "agent" | "edited"

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
  • 403This token can't do that (it needs photos:upload).
curl -X POST 'https://api.cactive.com.au/v1/me/photos/uploads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example"
  }'
Send it from this page with your session or a key.

Response 201

{
  duplicate: false
  uploadId: string
  itemId: string
  partSize: number
  partCount: number
  urls: {
    [key: number]: string
  }
  contentType: string
  name: string
} | {
  duplicate: true
  photo: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }
}
POST/v1/me/photos/uploads/:uploadId/parts

Links for more parts of an upload (an hour each).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • uploadId

    Upload id (dup_…), from starting the upload.

Request body

  • partNumbersinteger[]required

    1–100 items. Each 1–10000.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
  • 403This token can't do that (it needs photos:upload).
curl -X POST 'https://api.cactive.com.au/v1/me/photos/uploads/{uploadId}/parts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "partNumbers": [
      1
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  urls: {
    [key: number]: string
  }
  expiresIn: number
}
GET/v1/me/photos/uploads/:uploadId

The parts already stored (resuming).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • uploadId

    Upload id (dup_…), from starting the upload.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
  • 403This token can't do that (it needs photos:upload).
curl 'https://api.cactive.com.au/v1/me/photos/uploads/{uploadId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  uploadId: string
  name: string
  size: number
  partSize: number
  partCount: number
  parts: {
    partNumber: number
    size?: number
  }[]
  expiresAt: number
}
POST/v1/me/photos/uploads/:uploadId/complete

Finishes an upload: the photo (details and previews follow in the background), or the one it duplicates.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • uploadId

    Upload id (dup_…), from starting the upload.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
  • 403This token can't do that (it needs photos:upload).
curl -X POST 'https://api.cactive.com.au/v1/me/photos/uploads/{uploadId}/complete' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  photo: {
    photoId: string
    kind: "raw" | "video" | "live" | "photo"
    state: "main" | "archive" | "trash" | "motion"
    name: string
    mime: string
    size: number
    takenAt: number
    day: string
    width?: number
    height?: number
    duration?: number
    favourite: boolean
    thumbUrl?: string
    located: boolean
    pairId?: string
    processed: boolean
    trashedAt?: number
  }
  duplicate: boolean
}
DELETE/v1/me/photos/uploads/:uploadId

Abandons an upload and the parts it stored.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • uploadId

    Upload id (dup_…), from starting the upload.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
  • 403This token can't do that (it needs photos:upload).
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/uploads/{uploadId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/me/photos/imports

Google Takeout imports, newest first.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/imports' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  imports: {
    importId: string
    status: "queued" | "canceled" | "done" | "failed" | "running" | "uploading"
    files: {
      name: string
      size: number
      format: "zip" | "tgz"
      from: "upload" | "drive"
      uploaded: boolean
    }[]
    entries: number
    processed: number
    imported: number
    duplicates: number
    skipped: number
    failed: number
    albums: number
    bytes: number
    error?: string
    problems: string[]
    createdAt: number
    startedAt?: number
    finishedAt?: number
  }[]
}
POST/v1/me/photos/imports

A Takeout import: archives to upload (files: name and size of each .zip or .tgz; answers an upload per file) or archives already in Drive (driveItemIds, personal files). Start it once they're uploaded.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • filesobject[]

    1–100 items.

  • files[].namestringrequired

    1–255 characters.

  • files[].sizeintegerrequired

    1–107374182400.

  • driveItemIdsstring[]

    1–100 items. Each 3–64 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/imports' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "files": [
      {
        "name": "Example",
        "size": 1
      }
    ],
    "driveItemIds": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  import: {
    importId: string
    status: "queued" | "canceled" | "done" | "failed" | "running" | "uploading"
    files: {
      name: string
      size: number
      format: "zip" | "tgz"
      from: "upload" | "drive"
      uploaded: boolean
    }[]
    entries: number
    processed: number
    imported: number
    duplicates: number
    skipped: number
    failed: number
    albums: number
    bytes: number
    error?: string
    problems: string[]
    createdAt: number
    startedAt?: number
    finishedAt?: number
  }
  uploads: {
    index: number
    partSize: number
    partCount: number
    urls?: {
      [key: number]: string
    }
    parts?: {
      partNumber: number
      size?: number
    }[]
  }[]
}
GET/v1/me/photos/imports/:importId

An import with the parts each of its uploads has stored (resuming).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/imports/{importId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  import: {
    importId: string
    status: "queued" | "canceled" | "done" | "failed" | "running" | "uploading"
    files: {
      name: string
      size: number
      format: "zip" | "tgz"
      from: "upload" | "drive"
      uploaded: boolean
    }[]
    entries: number
    processed: number
    imported: number
    duplicates: number
    skipped: number
    failed: number
    albums: number
    bytes: number
    error?: string
    problems: string[]
    createdAt: number
    startedAt?: number
    finishedAt?: number
  }
  uploads: {
    index: number
    partSize: number
    partCount: number
    urls?: {
      [key: number]: string
    }
    parts?: {
      partNumber: number
      size?: number
    }[]
  }[]
}
POST/v1/me/photos/imports/:importId/files/:index/parts

Links for the parts of one archive's upload (index: its place in files).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

  • index

    The attachment's position in the message, from 0; or a Takeout archive's place in its import's files.

Request body

  • partNumbersinteger[]required

    1–100 items. Each 1–10000.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/imports/{importId}/files/{index}/parts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "partNumbers": [
      1
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  urls: {
    [key: number]: string
  }
  expiresIn: number
}
POST/v1/me/photos/imports/:importId/start

Completes the archives' uploads and starts importing (in the background; re-imports skip what's there).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/imports/{importId}/start' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  import: {
    importId: string
    status: "queued" | "canceled" | "done" | "failed" | "running" | "uploading"
    files: {
      name: string
      size: number
      format: "zip" | "tgz"
      from: "upload" | "drive"
      uploaded: boolean
    }[]
    entries: number
    processed: number
    imported: number
    duplicates: number
    skipped: number
    failed: number
    albums: number
    bytes: number
    error?: string
    problems: string[]
    createdAt: number
    startedAt?: number
    finishedAt?: number
  }
}
POST/v1/me/photos/imports/:importId/cancel

Stops an import; what it imported stays.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/imports/{importId}/cancel' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  import: {
    importId: string
    status: "queued" | "canceled" | "done" | "failed" | "running" | "uploading"
    files: {
      name: string
      size: number
      format: "zip" | "tgz"
      from: "upload" | "drive"
      uploaded: boolean
    }[]
    entries: number
    processed: number
    imported: number
    duplicates: number
    skipped: number
    failed: number
    albums: number
    bytes: number
    error?: string
    problems: string[]
    createdAt: number
    startedAt?: number
    finishedAt?: number
  }
}
DELETE/v1/me/photos/imports/:importId

Removes a finished, failed or canceled import (and its uploaded archives). Imported photos stay.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • importId

    Takeout import id (imp_…); under me/food a Food import (fim_…); under vehicles an import of a car's history (vim_…), as the imports list gives it.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/imports/{importId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/me/photos/tokens

Personal tokens for uploading (iPhone Shortcut, Mac sync) and reading (MCP).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/tokens' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  tokens: {
    tokenId: string
    name: string
    scopes: ("photos:upload" | "photos:read")[]
    createdAt: number
    lastUsedAt?: number
    expiresAt?: number
  }[]
}
POST/v1/me/photos/tokens

Makes a token; its secret is in the answer only.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • namestringrequired

    1–100 characters.

  • scopes("photos:upload" | "photos:read")[]required

    At least 1 item.

  • expiresAtinteger

    > 0.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/tokens' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "scopes": [
      "photos:upload"
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  token: {
    tokenId: string
    name: string
    scopes: ("photos:upload" | "photos:read")[]
    createdAt: number
    lastUsedAt?: number
    expiresAt?: number
  }
  secret: string
}
DELETE/v1/me/photos/tokens/:tokenId

Removes a photo token: it stops working at once.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • tokenId

    Photo token id (pht_…), not the token itself.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/tokens/{tokenId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

GET/v1/me/photos/exports

Full exports of the library: ZIPs of every original with an index of dates, places, albums and descriptions.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/exports' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  exports: {
    exportId: string
    status: "queued" | "ready" | "failed"
    files: number
    bytes: number
    createdAt: number
    expiresAt: number
    archives: {
      archiveId: string
      name: string
      status: string
      files: number
      bytes: number
      url?: string
    }[]
  }[]
}
POST/v1/me/photos/exports

Starts a full export of the library (originals as ZIPs of up to 10,000 files and 10 GB, with photos.json and albums.json). Ask for it until it's ready.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl -X POST 'https://api.cactive.com.au/v1/me/photos/exports' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 202

{
  export: {
    exportId: string
    status: "queued" | "ready" | "failed"
    files: number
    bytes: number
    createdAt: number
    expiresAt: number
    archives: {
      archiveId: string
      name: string
      status: string
      files: number
      bytes: number
      url?: string
    }[]
  }
}
GET/v1/me/photos/exports/:exportId

An export with each ZIP's status and its download link (a day) once ready.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • exportId

    An export's id (pex_… for Photos, oex_… for an organization).

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/exports/{exportId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  export: {
    exportId: string
    status: "queued" | "ready" | "failed"
    files: number
    bytes: number
    createdAt: number
    expiresAt: number
    archives: {
      archiveId: string
      name: string
      status: string
      files: number
      bytes: number
      url?: string
    }[]
  }
}
GET/v1/me/photos/log

The owner's personal log: every change and access (theirs, their tokens', link visitors').

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • cursorstring

    Up to 2,000 characters.

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/log' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  events: {
    activityId: string
    action: string
    actorId: string
    actorLabel?: string
    at: number
    detail: {
      [key: string]: unknown
    }
  }[]
  cursor?: string
}
GET/v1/me/photos/access

Who can see what: links, tokens, and any of the library's files shared through Drive.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Caity can look at your photos but not change them.
  • 403This token can't do that (it needs photos:read).
  • 403Photos are only for the person signed in, or their own photo token.
curl 'https://api.cactive.com.au/v1/me/photos/access' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  links: {
    linkId: string
    url: string
    albumId?: string
    photoCount?: number
    title: string
    keepLocation: boolean
    download: boolean
    expiresAt?: number
    hasPassword: boolean
    visits: number
    lastVisitAt?: number
    createdAt: number
  }[]
  tokens: {
    tokenId: string
    name: string
    scopes: ("photos:upload" | "photos:read")[]
    createdAt: number
    lastUsedAt?: number
    expiresAt?: number
  }[]
  driveShares: {
    itemId: string
    name: string
    principalId: string
    role: string
  }[]
  driveLinks: {
    itemId: string
    name: string
  }[]
}