API
Photos
Your photo library: the timeline, photos, albums, links, uploads, Takeout imports, tokens, exports and your activity log.
See Photos. Every route is under /v1/me/photos: your own library, for you signed in, or your photo token (si_pho_…; photos:upload for uploads, photos:read for reading). Organization keys and the phone assistant never reach it; Caity reads it, never changes it, only while you allow her, and each of her requests is in your activity log. Links anyone can open are under /v1/hooks/photos without authentication.
Uploads: POST uploads (with the file's sha256 to skip one already in the library) answers the part size and links for the first parts; PUT each part's bytes to its link, ask POST uploads/:uploadId/parts for more, then POST uploads/:uploadId/complete. With singlePart: true the whole file goes to urls["1"] and size can be left out. Details and previews follow in the background (processed).
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
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. |
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. |
GET /v1/hooks/photos/links/:token/photos | The link's photos (thumbnails), oldest first, in pages. |
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). |
POST /v1/hooks/photos/links/:token/archives | A ZIP of everything in the link (when downloads are on). |
GET /v1/hooks/photos/links/:token/archives/:archiveId | A link's ZIP: its status, and a one-hour download link once ready. No authentication. |
GET /v1/me/photos/library | The library: its settings, storage (shared with Drive's personal space) and counts. Made on first use. |
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). |
GET /v1/me/photos/days | Photos per local day on the timeline (newest first), for the scrubber and the grid's layout. |
GET /v1/me/photos/timeline | Timeline photos taken between from and to (ms), newest first. |
GET /v1/me/photos/lists/:list | Favourites, the archive or the trash, newest first. |
POST /v1/me/photos/trash/empty | Deletes everything in the trash for good (the files from Drive too). |
POST /v1/me/photos/photos/batch | Several photos by id (the map's pins, a selection), in the order asked. |
POST /v1/me/photos/photos/state | Favourite, unfavourite, archive, unarchive, move to the trash, restore or delete forever (trashed photos only). |
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. |
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). |
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. |
PUT /v1/me/photos/photos/:photoId/poster | A video's poster frame, made in the browser (JPEG or WebP, base64, up to 1 MB). |
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. |
GET /v1/me/photos/map | Every located photo as a point (id, latitude, longitude, time), for the map. |
GET /v1/me/photos/albums | Your albums, most recently changed first, with covers and how many links show each. |
POST /v1/me/photos/albums | Creates an album, optionally with photos. |
GET /v1/me/photos/albums/:albumId | An album and a page of its photos, in its sort order. |
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). |
DELETE /v1/me/photos/albums/:albumId | Deletes the album (its photos stay in the library) and turns off its links. |
POST /v1/me/photos/albums/:albumId/photos | Adds photos to an album (up to 20,000 in one album). Ones already there stay. |
POST /v1/me/photos/albums/:albumId/photos/remove | Takes photos out of an album; they stay in the library. |
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. |
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. |
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. |
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. |
GET /v1/me/photos/shared | Albums shared with the person (through them, their groups, circles or organisations), and offers waiting for them. |
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). |
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). |
POST /v1/me/photos/shared/:albumId/photos | A contributor adds photos from their own library (they stay theirs); keepLocation shares where they were taken. |
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. |
PATCH /v1/me/photos/shared/:albumId/photos/:photoId | The photo's owner shows or hides where it was taken. |
POST /v1/me/photos/shared/:albumId/leave | Takes all the person's photos and comments out and gives back a share made to them. |
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). |
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. |
DELETE /v1/me/photos/shared/:albumId/photos/:photoId/comments/:commentId | Deletes a comment: its author's, or any for the album's owner. |
GET /v1/me/photos/shared/:albumId/people | Whom a comment in the album can mention: people who still see it. |
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. |
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. |
PATCH /v1/me/photos/partner | From when the partner sees photos (null: all) and whether they see where they were taken. |
DELETE /v1/me/photos/partner | Ends partner sharing at once (the partner, an offer or an invitation). |
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). |
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). |
POST /v1/me/photos/partners/:userId/leave | The partner stops seeing the library. |
GET /v1/me/photos/links | Links anyone can open: albums and chosen photos. |
POST /v1/me/photos/links | A link to an album or to chosen photos: view only, locations removed unless keepLocation, optional expiry and password. |
PATCH /v1/me/photos/links/:linkId | Changes a link: password null removes it; rotate makes a new address (the old one stops working). |
DELETE /v1/me/photos/links/:linkId | Turns a link off: it stops working at once. |
POST /v1/me/photos/uploads/check | Which of these SHA-256 hashes are already in the library (skip uploading them). |
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. |
POST /v1/me/photos/uploads/:uploadId/parts | Links for more parts of an upload (an hour each). |
GET /v1/me/photos/uploads/:uploadId | The parts already stored (resuming). |
POST /v1/me/photos/uploads/:uploadId/complete | Finishes an upload: the photo (details and previews follow in the background), or the one it duplicates. |
DELETE /v1/me/photos/uploads/:uploadId | Abandons an upload and the parts it stored. |
GET /v1/me/photos/imports | Google Takeout imports, newest first. |
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. |
GET /v1/me/photos/imports/:importId | An import with the parts each of its uploads has stored (resuming). |
POST /v1/me/photos/imports/:importId/files/:index/parts | Links for the parts of one archive's upload (index: its place in files). |
POST /v1/me/photos/imports/:importId/start | Completes the archives' uploads and starts importing (in the background; re-imports skip what's there). |
POST /v1/me/photos/imports/:importId/cancel | Stops an import; what it imported stays. |
DELETE /v1/me/photos/imports/:importId | Removes a finished, failed or canceled import (and its uploaded archives). Imported photos stay. |
GET /v1/me/photos/tokens | Personal tokens for uploading (iPhone Shortcut, Mac sync) and reading (MCP). |
POST /v1/me/photos/tokens | Makes a token; its secret is in the answer only. |
DELETE /v1/me/photos/tokens/:tokenId | Removes a photo token: it stops working at once. |
GET /v1/me/photos/exports | Full exports of the library: ZIPs of every original with an index of dates, places, albums and descriptions. |
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. |
GET /v1/me/photos/exports/:exportId | An export with each ZIP's status and its download link (a day) once ready. |
GET /v1/me/photos/log | The owner's personal log: every change and access (theirs, their tokens', link visitors'). |
GET /v1/me/photos/access | Who can see what: links, tokens, and any of the library's files shared through Drive. |