Developers
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
    left?: {
      what: string
      count: number
    }[]
  }
}
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
    left?: {
      what: string
      count: number
    }[]
  }
}
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
    codec?: string
    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
    codec?: string
    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
    codec?: string
    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
    codec?: string
    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" | "phone" | "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
    codec?: string
    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" | "phone" | "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). transcode=1 with inline=1, for a video the browser can't play: its preview transcode, pending while it's made, or the original with unplayable.

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"
  • transcode"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
  transcoded?: boolean
  unplayable?: boolean
  pending?: undefined
} | {
  pending: true
  name: string
  mime: string
  url?: undefined
}
| {
  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
    codec?: string
    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
    codec?: string
    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
    sharedWith: number
    keepLocation: boolean
  }[]
}
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
    sharedWith: number
    keepLocation: boolean
  }
}
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
    sharedWith: number
    keepLocation: boolean
  }
  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
    codec?: string
    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, and whether members of a shared album see where your own photos in it were taken (keepLocation).

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"
  • keepLocationboolean

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
    sharedWith: number
    keepLocation: boolean
  }
}
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
    sharedWith: number
    keepLocation: boolean
  }
}
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
    sharedWith: number
    keepLocation: boolean
  }
}
GET/v1/me/photos/albums/:albumId/sharing

Who an album is shared with (the sharing service's view), whom its owner can choose (their organisations, groups and circles), and its location setting.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}/sharing' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  sharing: {
    resource: string
    type: string
    app: string
    label: string
    owner: {
      spaceId: string
      kind: "org" | "personal"
      name: null | string
      you: boolean
    }
    you: {
      capabilities: string[]
      via: {
        kind: "role" | "owner" | "container"
        detail?: string
        capabilities: string[]
      } | {
        kind: "link" | "grant"
        resource: string
        inherited: boolean
        principal: string
        source: string
        preset?: string
        capabilities: string[]
        params?: {
          [key: string]: boolean | string | number
        }
        notBefore?: number
        expiresAt?: number
        schedule?: {
          tz: string
          windows: {
            days?: object
            from: string
            to: string
            dates?: object
          }[]
        }
        approval?: string[]
        assistants?: boolean
        paused?: true
      }[]
      canShare: boolean
    }
    grants: null | {
      resource: string
      principal: string
      kind: "user" | "key" | "org" | "link" | "group" | "circle"
      name: null | string
      email: null | string
      deleted: boolean
      source: string
      status: "active" | "pending"
      capabilities: string[]
      preset: null | string
      notBefore: null | number
      expiresAt: null | number
      schedule: null | {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
      params: null | {
        [key: string]: boolean | string | number
      }
      assistants: boolean
      approval: string[]
      includeGuests: boolean
      external: boolean
      blocked: null | string
      acceptBy: null | number
      pausedUntil: null | number
      grantedBy: {
        id: string
        name: null | string
      }
      createdAt: string
      updatedAt: string
      rev: number
    }[]
    links: null | {
      linkId: string
      resource: string
      audience: "org" | "anyone" | "signed_in"
      capabilities: string[]
      preset: null | string
      expiresAt: null | number
      passwordProtected: boolean
      blocked: null | string
      createdBy: {
        id: string
        name: null | string
      }
      createdAt: string
    }[]
    invitations: null | {
      invitationId: string
      principal: string
      email: string
      capabilities: string[]
      preset: null | string
      notBefore: null | number
      expiresAt: null | number
      schedule: null | {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
      params: null | {
        [key: string]: boolean | string | number
      }
      assistants: boolean
      approval: string[]
      offerEnds: number
      invitedBy: {
        id: string
        name: null | string
      }
      createdAt: string
    }[]
    policy: null | {
      externalSharing: "off" | "accounts" | "links"
      allowedDomains: string[]
      linkMaxDays: null | number
    }
  }
  choices: {
    orgs: {
      orgId: string
      name: string
    }[]
    groups: {
      teamId: string
      name: string
      orgId: string
      orgName: string
    }[]
    circles: {
      circleId: string
      name: string
    }[]
  }
  keepLocation: boolean
}
POST/v1/me/photos/albums/:albumId/sharing

Shares it with one of the owner's organisations, a group or circle they're in, or a person by address (who accepts first): Viewer or Contributor.

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

Path parameters

  • albumId

    Album id (alb_…).

Request body

  • toobject | objectrequired
  • preset"viewer" | "contributor"required
  • messagestring

    Up to 500 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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}/sharing' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": {},
    "preset": "viewer"
  }'
Send it from this page with your session or a key.

Response 201

{
  kind: "grant"
  grant: {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
        dates?: string[]
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }
} | {
  kind: "invitation"
  invitation: {
    invitationId: string
    principal: string
    email: string
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
        dates?: string[]
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    offerEnds: number
    invitedBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }
}
PATCH/v1/me/photos/albums/:albumId/sharing/:principal

Makes someone you shared an album with a Viewer or a Contributor (rev from the album's sharing). A viewer keeps the photos they added.

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

Path parameters

  • albumId

    Album id (alb_…).

  • principal

    Who a grant is to, URL-encoded: user:usr_…, group:team_…, circle:cir_…, org:org_… or key:key_…. An invitation to an address with no account is named by its invitationId, never its address.

Request body

  • preset"viewer" | "contributor"required
  • revintegerrequired

    ≥ 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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}/sharing/{principal}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "preset": "viewer",
    "rev": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  grant: {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
        dates?: string[]
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }
}
DELETE/v1/me/photos/albums/:albumId/sharing/:principal

Ends a share (or withdraws an invitation, by its gin_ id) at once; whoever no longer sees the album has their photos taken out.

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

Path parameters

  • albumId

    Album id (alb_…).

  • principal

    Who a grant is to, URL-encoded: user:usr_…, group:team_…, circle:cir_…, org:org_… or key:key_…. An invitation to an address with no account is named by its invitationId, never its address.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/albums/{albumId}/sharing/{principal}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  removed: number
}
GET/v1/me/photos/shared

Albums shared with the person (through them, their groups, circles or organisations), and offers waiting for them.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/shared' \
  -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
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    owner: {
      userId: string
      name: null | string
    }
    role: "owner" | "viewer" | "contributor"
    keepLocation: boolean
    canLeave: boolean
    updatedAt: number
  }[]
  offers: {
    key: string
    albumId: string
    title: string
    owner: {
      userId: string
      name: null | string
    }
    role: "viewer" | "contributor"
    acceptBy: number
  }[]
}
GET/v1/me/photos/shared/:albumId

A shared album and a page of everyone's photos as the person may see them (locations only where their owners share them).

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/shared/{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
    coverUrl?: string
    sort: "oldest" | "newest" | "added"
    owner: {
      userId: string
      name: null | string
    }
    role: "owner" | "viewer" | "contributor"
    keepLocation: boolean
    canLeave: boolean
    updatedAt: number
  }
  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
    }
    by: {
      userId: string
      name: null | string
    }
    mine: boolean
    locationShared: boolean
  }[]
  cursor?: string
}
GET/v1/me/photos/shared/:albumId/photos/:photoId

One photo: its preview or video (5-minute links), and the original with download=1 (cleaned unless its location is shared).

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

Path parameters

  • albumId

    Album id (alb_…).

  • photoId

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

Query parameters

  • download"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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/photos/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
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/me/photos/shared/:albumId/photos

A contributor adds photos from their own library (they stay theirs); keepLocation shares where they were taken.

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.

  • keepLocationboolean

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/shared/{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

{
  added: number
}
POST/v1/me/photos/shared/:albumId/photos/remove

Takes the person's own photos out (the owner: anyone's); mine takes out every one of theirs.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/photos/remove' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  removed: number
}
PATCH/v1/me/photos/shared/:albumId/photos/:photoId

The photo's owner shows or hides where it was taken.

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

Path parameters

  • albumId

    Album id (alb_…).

  • photoId

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

Request body

  • keepLocationbooleanrequired

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/photos/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "keepLocation": true
  }'
Send it from this page with your session or a key.

Response 200

{
  keepLocation: boolean
}
POST/v1/me/photos/shared/:albumId/leave

Takes all the person's photos and comments out and gives back a share made to them.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/leave' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  removed: number
  left: boolean
}
GET/v1/me/photos/shared/:albumId/photos/:photoId/comments

A photo's comments, oldest first, by people who still see the album (docs/photos.md → Comments).

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

Path parameters

  • albumId

    Album id (alb_…).

  • 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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/photos/{photoId}/comments' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  comments: {
    commentId: string
    photoId: string
    by: {
      userId: string
      name: null | string
    }
    text: string
    people: {
      userId: string
      name: null | string
    }[]
    createdAt: number
    mine: boolean
    canDelete: boolean
  }[]
}
POST/v1/me/photos/shared/:albumId/photos/:photoId/comments

Comments on a photo; <@usr_…> mentions people who see the album (at most 10), who hear by push, as does the photo's owner.

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

Path parameters

  • albumId

    Album id (alb_…).

  • photoId

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

Request body

  • textstringrequired

    1–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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/photos/{photoId}/comments' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "example"
  }'
Send it from this page with your session or a key.

Response 201

{
  comment: {
    commentId: string
    photoId: string
    by: {
      userId: string
      name: null | string
    }
    text: string
    people: {
      userId: string
      name: null | string
    }[]
    createdAt: number
    mine: boolean
    canDelete: boolean
  }
}
DELETE/v1/me/photos/shared/:albumId/photos/:photoId/comments/:commentId

Deletes a comment: its author's, or any for the album's owner.

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

Path parameters

  • albumId

    Album id (alb_…).

  • photoId

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

  • commentId

    Comment id (icm_…).

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/photos/{photoId}/comments/{commentId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  deleted: true
}
GET/v1/me/photos/shared/:albumId/people

Whom a comment in the album can mention: people who still see it.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/shared/{albumId}/people' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  people: {
    userId: string
    name: null | string
  }[]
}
GET/v1/me/photos/partner

Partner sharing (docs/photos.md → Partner sharing): whom the library is shared with, its settings, and partners' libraries shared with the person.

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/partner' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  sharing: {
    resource: string
    type: string
    app: string
    label: string
    owner: {
      spaceId: string
      kind: "org" | "personal"
      name: null | string
      you: boolean
    }
    you: {
      capabilities: string[]
      via: {
        kind: "role" | "owner" | "container"
        detail?: string
        capabilities: string[]
      } | {
        kind: "link" | "grant"
        resource: string
        inherited: boolean
        principal: string
        source: string
        preset?: string
        capabilities: string[]
        params?: {
          [key: string]: boolean | string | number
        }
        notBefore?: number
        expiresAt?: number
        schedule?: {
          tz: string
          windows: {
            days?: object
            from: string
            to: string
            dates?: object
          }[]
        }
        approval?: string[]
        assistants?: boolean
        paused?: true
      }[]
      canShare: boolean
    }
    grants: null | {
      resource: string
      principal: string
      kind: "user" | "key" | "org" | "link" | "group" | "circle"
      name: null | string
      email: null | string
      deleted: boolean
      source: string
      status: "active" | "pending"
      capabilities: string[]
      preset: null | string
      notBefore: null | number
      expiresAt: null | number
      schedule: null | {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
      params: null | {
        [key: string]: boolean | string | number
      }
      assistants: boolean
      approval: string[]
      includeGuests: boolean
      external: boolean
      blocked: null | string
      acceptBy: null | number
      pausedUntil: null | number
      grantedBy: {
        id: string
        name: null | string
      }
      createdAt: string
      updatedAt: string
      rev: number
    }[]
    links: null | {
      linkId: string
      resource: string
      audience: "org" | "anyone" | "signed_in"
      capabilities: string[]
      preset: null | string
      expiresAt: null | number
      passwordProtected: boolean
      blocked: null | string
      createdBy: {
        id: string
        name: null | string
      }
      createdAt: string
    }[]
    invitations: null | {
      invitationId: string
      principal: string
      email: string
      capabilities: string[]
      preset: null | string
      notBefore: null | number
      expiresAt: null | number
      schedule: null | {
        tz: string
        windows: {
          days?: object
          from: string
          to: string
          dates?: object
        }[]
      }
      params: null | {
        [key: string]: boolean | string | number
      }
      assistants: boolean
      approval: string[]
      offerEnds: number
      invitedBy: {
        id: string
        name: null | string
      }
      createdAt: string
    }[]
    policy: null | {
      externalSharing: "off" | "accounts" | "links"
      allowedDomains: string[]
      linkMaxDays: null | number
    }
  }
  since?: number
  keepLocation: boolean
  libraries: {
    owner: {
      userId: string
      name: null | string
    }
    since?: number
  }[]
  offers: {
    key: string
    owner: {
      userId: string
      name: null | string
    }
    acceptBy: number
  }[]
}
POST/v1/me/photos/partner

Offers the library to one person by address (they accept first); refused while a partner, an offer or an invitation exists.

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

Request body

  • emailstringrequired

    Up to 254 characters. Email address.

  • sinceintegeror null

    -10000000000000–10000000000000.

  • keepLocationboolean

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/partner' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "person@example.com"
  }'
Send it from this page with your session or a key.

Response 201

{
  kind: "grant"
  grant: {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
        dates?: string[]
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }
} | {
  kind: "invitation"
  invitation: {
    invitationId: string
    principal: string
    email: string
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days?: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
        dates?: string[]
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    offerEnds: number
    invitedBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }
}
PATCH/v1/me/photos/partner

From when the partner sees photos (null: all) and whether they see where they were taken.

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

Request body

  • sinceintegeror null

    -10000000000000–10000000000000.

  • keepLocationboolean

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X PATCH 'https://api.cactive.com.au/v1/me/photos/partner' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "since": 1,
    "keepLocation": true
  }'
Send it from this page with your session or a key.

Response 200

{
  keepLocation: boolean
  since?: number
}
DELETE/v1/me/photos/partner

Ends partner sharing at once (the partner, an offer or an invitation).

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X DELETE 'https://api.cactive.com.au/v1/me/photos/partner' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  stopped: number
}
GET/v1/me/photos/partners/:userId

A page of a partner's library, newest first (5-minute links, no metadata; locations only if the owner shows them).

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

Path parameters

  • userId

    A member's user id (usr_…).

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/partners/{userId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  owner: {
    userId: string
    name: null | string
  }
  since?: number
  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/me/photos/partners/:userId/photos/:photoId

One of a partner's photos: its preview or video, and the original with download=1 (cleaned unless locations show).

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

Path parameters

  • userId

    A member's user id (usr_…).

  • photoId

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

Query parameters

  • download"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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:read
curl 'https://api.cactive.com.au/v1/me/photos/partners/{userId}/photos/{photoId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
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/me/photos/partners/:userId/leave

The partner stops seeing the library.

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

Path parameters

  • userId

    A member's user id (usr_…).

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.
  • 403Shared albums are for the person signed in.
  • 403Sharing isn't available to the phone assistant.
  • 403Sharing is changed by you, not by the assistant.
  • 403Missing scope sharing:write
curl -X POST 'https://api.cactive.com.au/v1/me/photos/partners/{userId}/leave' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  left: true
}
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" | "phone"

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
    codec?: string
    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
    codec?: string
    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
  }[]
  partner: null | {
    name: null | string
    pending: boolean
  }
  driveShares: {
    itemId: string
    name: string
    principalId: string
    role: string
  }[]
  driveLinks: {
    itemId: string
    name: string
  }[]
}