photoslibrary, photoslibrary.readonly and photoslibrary.sharing scopes and restricted the Library API to content the app created. Three things follow, and this plugin is shaped around them:
- The scopes that remain are
photoslibrary.appendonly,photoslibrary.readonly.appcreateddataandphotoslibrary.edit.appcreateddata. All three are requested here. - Reads only reach albums and media items this app created. No API searches the rest of a user’s library any more. To work with other photos, the Google Photos Picker API lets the user pick items in a Picker session and gives the app only those; it is a different API with its own flow and is not part of this plugin.
albums.share,albums.unshareand everysharedAlbums.*method were removed. The plugin exposes none of them.
- Uploading is two steps, done here in one call.
mediaItems.createposts the bytes to/uploads, reads back an upload token, then sends up to 50 tokens tomediaItems:batchCreate. Eachfileis a public URL,{ url }or{ base64 }, with an optionalfilenameandcontentType, up to 200 MB. A partial failure answers 207 with a status per item, so check eachnewMediaItemResults[].status. - Uploads count toward the user’s storage past 25MB. Google asks an app to tell the user this.
- Google asks for a different request shape per list. Albums default to 20 per page and cap at 50; media items default to 25 and cap at 100. Both are paginated with
nextPageToken. filtersandalbumIdcannot be combined. The API answers 400, so the plugin refuses it before the request.orderByonly works with a date filter. The two accepted values areMediaMetadata.creation_time desc(newest first, the default) andMediaMetadata.creation_time.- A base URL is not fetchable, and it expires. A parameter must be appended:
=dfor a photo’s original bytes,=dvfor a video’s bytes, or=w<width>-h<height>for a scaled copy (a thumbnail for a video) with an optional-cto crop. A base URL works for 60 minutes after the read that returned it.mediaBytesUrl(item, options)builds the URL and picks=dvwhen the item is a video. - Updates change one field each.
albums.updaterenames an album (thetitlemask) andmediaItems.updatechanges a media item’s description (thedescriptionmask, the only one the API accepts). - A 429 needs at least 30 seconds before a retry. That is the upload guide’s rule. The plugin waits 30 seconds, or longer when Google’s
Retry-Afterasks for more. A 429 that reports the spent daily quota (10,000 requests per project per day) is not retried, since no wait within the call can clear it. - No service accounts. Google states the Library API does not support them, so every call is made as a signed-in user.
- 13 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- OAuth 2.0 (Recommended)
Open hub.corsair.dev, navigate to your project, and enter the client ID and client secret from your Google Photos OAuth app.More: OAuth 2.0
4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Find the photos in an app-created albumWhat’s next
API reference
Every
googlephotos.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.