> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Photos API reference

> API reference for Google Photos: every `googlephotos.api.*` operation with input and output types.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Albums

### addEnrichment

`albums.addEnrichment`

Add a text note or a location to an app-created album, at a chosen position

**Risk:** `write`

```ts theme={null}
await corsair.googlephotos.api.albums.addEnrichment({ albumId: 'ABcDeFgHiJkLmNoP', text: 'Day one' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `albumId` | `string` | Yes | An album id from albums.create or albums.list |
| `text` | `string \| null` | No | A text note to add |
| `location` | `object \| null` | No | — |
| `position` | `object` | No | — |

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locationName?: string | null,
>   latlng?: {
>     latitude: number,
>     longitude: number
>   } | null
> } | null
> ```

> [accordion] position full type
>
> ```ts theme={null}
> {
>   position: POSITION_TYPE_UNSPECIFIED | FIRST_IN_ALBUM | LAST_IN_ALBUM | AFTER_MEDIA_ITEM | AFTER_ENRICHMENT_ITEM,
>   relativeMediaItemId?: string | null,
>   relativeEnrichmentItemId?: string | null
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `enrichmentItem` | `object \| null` | No | The new enrichment, named by its id |

> [accordion] enrichmentItem full type
>
> ```ts theme={null}
> {
>   id?: string | null
> } | null
> ```

***

### batchAddMediaItems

`albums.batchAddMediaItems`

Add up to 50 media items to an app-created album

**Risk:** `write`

```ts theme={null}
await corsair.googlephotos.api.albums.batchAddMediaItems({ albumId: 'ABcDeFgHiJkLmNoP', mediaItemIds: ['AbCdEf123'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `albumId` | `string` | Yes | An album id from albums.create or albums.list |
| `mediaItemIds` | `string[]` | Yes | 1 to 50 distinct ids per call |

**Output:** *empty object*

***

### batchRemoveMediaItems

`albums.batchRemoveMediaItems`

Remove up to 50 media items from an album. The items stay in the library, so this is reversible by adding them back

**Risk:** `destructive`

```ts theme={null}
await corsair.googlephotos.api.albums.batchRemoveMediaItems({ albumId: 'ABcDeFgHiJkLmNoP', mediaItemIds: ['AbCdEf123'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `albumId` | `string` | Yes | An album id from albums.create or albums.list |
| `mediaItemIds` | `string[]` | Yes | 1 to 50 distinct ids per call |

**Output:** *empty object*

***

### create

`albums.create`

Create an album with a title

**Risk:** `write`

```ts theme={null}
await corsair.googlephotos.api.albums.create({ title: 'Holiday 2026' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `title` | `string` | Yes | The album name, at most 500 characters |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A persistent album id |
| `title` | `string \| null` | No | At most 500 characters |
| `productUrl` | `string \| null` | No | — |
| `isWriteable` | `boolean \| null` | No | True when the granted scopes allow adding items |
| `mediaItemsCount` | `string \| null` | No | int64 as a string, not a number |
| `coverPhotoBaseUrl` | `string \| null` | No | A prefix that needs a size parameter, like a media baseUrl |
| `coverPhotoMediaItemId` | `string \| null` | No | — |
| `shareInfo` | `object \| null` | No | — |

> [accordion] shareInfo full type
>
> ```ts theme={null}
> {
>   sharedAlbumOptions?: {
>     isCollaborative?: boolean | null,
>     isCommentable?: boolean | null
>   } | null,
>   shareableUrl?: string | null,
>   shareToken?: string | null,
>   isOwned?: boolean | null,
>   isJoinable?: boolean | null,
>   isJoined?: boolean | null
> } | null
> ```

***

### get

`albums.get`

Read one album this app created

**Risk:** `read`

```ts theme={null}
await corsair.googlephotos.api.albums.get({ albumId: 'ABcDeFgHiJkLmNoP' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `albumId` | `string` | Yes | An album id from albums.create or albums.list |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A persistent album id |
| `title` | `string \| null` | No | At most 500 characters |
| `productUrl` | `string \| null` | No | — |
| `isWriteable` | `boolean \| null` | No | True when the granted scopes allow adding items |
| `mediaItemsCount` | `string \| null` | No | int64 as a string, not a number |
| `coverPhotoBaseUrl` | `string \| null` | No | A prefix that needs a size parameter, like a media baseUrl |
| `coverPhotoMediaItemId` | `string \| null` | No | — |
| `shareInfo` | `object \| null` | No | — |

> [accordion] shareInfo full type
>
> ```ts theme={null}
> {
>   sharedAlbumOptions?: {
>     isCollaborative?: boolean | null,
>     isCommentable?: boolean | null
>   } | null,
>   shareableUrl?: string | null,
>   shareToken?: string | null,
>   isOwned?: boolean | null,
>   isJoinable?: boolean | null,
>   isJoined?: boolean | null
> } | null
> ```

***

### list

`albums.list`

List the albums this app created; since March 2025 the API reads nothing else

**Risk:** `read`

```ts theme={null}
await corsair.googlephotos.api.albums.list({ pageSize: 20 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `pageSize` | `number \| null` | No | 1 to 50. The API default is 20 |
| `pageToken` | `string \| null` | No | nextPageToken from a previous page of the same call |
| `excludeNonAppCreatedData` | `boolean \| null` | No | Leave out albums the app did not create. Reads of the user's whole library need a scope Google removed in March 2025, so this is effectively the only data a current scope can see |

Only albums this app created are readable; the wide-read scope was removed in 2025.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `albums` | `object[] \| null` | No | Absent when the account has no albums |
| `nextPageToken` | `string \| null` | No | — |

> [accordion] albums full type
>
> ```ts theme={null}
> {
>   id: string,
>   title?: string | null,
>   productUrl?: string | null,
>   isWriteable?: boolean | null,
>   mediaItemsCount?: string | null,
>   coverPhotoBaseUrl?: string | null,
>   coverPhotoMediaItemId?: string | null,
>   shareInfo?: {
>     sharedAlbumOptions?: {
>       isCollaborative?: boolean | null,
>       isCommentable?: boolean | null
>     } | null,
>     shareableUrl?: string | null,
>     shareToken?: string | null,
>     isOwned?: boolean | null,
>     isJoinable?: boolean | null,
>     isJoined?: boolean | null
>   } | null
> }[] | null
> ```

***

### update

`albums.update`

Rename an app-created album (sends the title update mask)

**Risk:** `write`

```ts theme={null}
await corsair.googlephotos.api.albums.update({ albumId: 'ABcDeFgHiJkLmNoP', title: 'Holiday 2026 (edited)' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `albumId` | `string` | Yes | An album id from albums.create or albums.list |
| `title` | `string` | Yes | At most 500 characters |

Sends PATCH with the `title` mask. The API also accepts `coverPhotoMediaItemId`, which this plugin does not expose yet.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A persistent album id |
| `title` | `string \| null` | No | At most 500 characters |
| `productUrl` | `string \| null` | No | — |
| `isWriteable` | `boolean \| null` | No | True when the granted scopes allow adding items |
| `mediaItemsCount` | `string \| null` | No | int64 as a string, not a number |
| `coverPhotoBaseUrl` | `string \| null` | No | A prefix that needs a size parameter, like a media baseUrl |
| `coverPhotoMediaItemId` | `string \| null` | No | — |
| `shareInfo` | `object \| null` | No | — |

> [accordion] shareInfo full type
>
> ```ts theme={null}
> {
>   sharedAlbumOptions?: {
>     isCollaborative?: boolean | null,
>     isCommentable?: boolean | null
>   } | null,
>   shareableUrl?: string | null,
>   shareToken?: string | null,
>   isOwned?: boolean | null,
>   isJoinable?: boolean | null,
>   isJoined?: boolean | null
> } | null
> ```

***

## Media Items

### batchGet

`mediaItems.batchGet`

Read up to 50 app-created media items by id, with a per-id status

**Risk:** `read`

```ts theme={null}
await corsair.googlephotos.api.mediaItems.batchGet({ mediaItemIds: ['AbCdEf123', 'GhIjKl456'] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `mediaItemIds` | `string[]` | Yes | 1 to 50 distinct ids to read in one call |

Each requested id gets an entry, and a failed id carries a status instead of an item.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `mediaItemResults` | `object[]` | Yes | One entry per requested id. An entry can carry a status error instead of an item |

> [accordion] mediaItemResults full type
>
> ```ts theme={null}
> {
>   status?: {
>     code?: number | null,
>     message?: string | null,
>     details?: Record<string, any>[] | null
>   } | null,
>   mediaItem?: {
>     id: string,
>     filename?: string | null,
>     mimeType?: string | null,
>     description?: string | null,
>     productUrl?: string | null,
>     baseUrl?: string | null,
>     mediaMetadata?: {
>       creationTime?: string | null,
>       width?: string | null,
>       height?: string | null,
>       photo?: {
>         cameraMake?: string | null,
>         cameraModel?: string | null,
>         focalLength?: number | null,
>         apertureFNumber?: number | null,
>         isoEquivalent?: number | null,
>         exposureTime?: string | null
>       } | null,
>       video?: {
>         cameraMake?: string | null,
>         cameraModel?: string | null,
>         fps?: number | null,
>         status?: string | null
>       } | null
>     } | null,
>     contributorInfo?: {
>       profilePictureBaseUrl?: string | null,
>       displayName?: string | null
>     } | null
>   } | null
> }[]
> ```

***

### create

`mediaItems.create`

Upload bytes and create up to 50 media items, optionally in an album; uploads count toward the user's Google storage past 25MB

**Risk:** `write`

```ts theme={null}
await corsair.googlephotos.api.mediaItems.create({ newMediaItems: [{ file: { url: 'https://example.com/beach.jpg', contentType: 'image/jpeg' }, description: 'Beach day' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `newMediaItems` | `object[]` | Yes | 1 to 50 items per call; the API refuses more |
| `albumId` | `string \| null` | No | Also add the items to this album, which must be app-created |
| `albumPosition` | `object \| null` | No | — |

Each file is a public URL or base64 (up to 200 MB). The endpoint uploads them, then creates up to 50 items from the returned tokens; a failed item carries a status code.

> [accordion] newMediaItems full type
>
> ```ts theme={null}
> {
>   file: string | {
>     url: string,
>     filename?: string,
>     contentType?: string
>   } | {
>     base64: string,
>     filename?: string,
>     contentType?: string
>   },
>   fileName?: string | null,
>   description?: string | null
> }[]
> ```

> [accordion] albumPosition full type
>
> ```ts theme={null}
> {
>   position: POSITION_TYPE_UNSPECIFIED | FIRST_IN_ALBUM | LAST_IN_ALBUM | AFTER_MEDIA_ITEM | AFTER_ENRICHMENT_ITEM,
>   relativeMediaItemId?: string | null,
>   relativeEnrichmentItemId?: string | null
> } | null
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `newMediaItemResults` | `object[]` | Yes | One entry per submitted item, in the order they were sent, each with its own status |

> [accordion] newMediaItemResults full type
>
> ```ts theme={null}
> {
>   uploadToken?: string | null,
>   status?: {
>     code?: number | null,
>     message?: string | null,
>     details?: Record<string, any>[] | null
>   } | null,
>   mediaItem?: {
>     id: string,
>     filename?: string | null,
>     mimeType?: string | null,
>     description?: string | null,
>     productUrl?: string | null,
>     baseUrl?: string | null,
>     mediaMetadata?: {
>       creationTime?: string | null,
>       width?: string | null,
>       height?: string | null,
>       photo?: {
>         cameraMake?: string | null,
>         cameraModel?: string | null,
>         focalLength?: number | null,
>         apertureFNumber?: number | null,
>         isoEquivalent?: number | null,
>         exposureTime?: string | null
>       } | null,
>       video?: {
>         cameraMake?: string | null,
>         cameraModel?: string | null,
>         fps?: number | null,
>         status?: string | null
>       } | null
>     } | null,
>     contributorInfo?: {
>       profilePictureBaseUrl?: string | null,
>       displayName?: string | null
>     } | null
>   } | null
> }[]
> ```

***

### get

`mediaItems.get`

Read one media item this app created

**Risk:** `read`

```ts theme={null}
await corsair.googlephotos.api.mediaItems.get({ mediaItemId: 'AbCdEf123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `mediaItemId` | `string` | Yes | A media item id from a search or a batchCreate result |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A persistent id, stable between sessions |
| `filename` | `string \| null` | No | — |
| `mimeType` | `string \| null` | No | e.g. `image/jpeg` |
| `description` | `string \| null` | No | — |
| `productUrl` | `string \| null` | No | A Google Photos link the user can open when signed in |
| `baseUrl` | `string \| null` | No | A prefix for the bytes, valid for 60 minutes. A parameter must be appended before it can be fetched (`=d` for photo bytes, `=dv` for video bytes, `=w<w>-h<h>` for a scaled copy); the exported mediaBytesUrl helper builds it |
| `mediaMetadata` | `object \| null` | No | — |
| `contributorInfo` | `object \| null` | No | — |

> [accordion] mediaMetadata full type
>
> ```ts theme={null}
> {
>   creationTime?: string | null,
>   width?: string | null,
>   height?: string | null,
>   photo?: {
>     cameraMake?: string | null,
>     cameraModel?: string | null,
>     focalLength?: number | null,
>     apertureFNumber?: number | null,
>     isoEquivalent?: number | null,
>     exposureTime?: string | null
>   } | null,
>   video?: {
>     cameraMake?: string | null,
>     cameraModel?: string | null,
>     fps?: number | null,
>     status?: string | null
>   } | null
> } | null
> ```

> [accordion] contributorInfo full type
>
> ```ts theme={null}
> {
>   profilePictureBaseUrl?: string | null,
>   displayName?: string | null
> } | null
> ```

***

### list

`mediaItems.list`

List the media items this app created, 25 per page by default

**Risk:** `read`

```ts theme={null}
await corsair.googlephotos.api.mediaItems.list({ pageSize: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `pageSize` | `number \| null` | No | 1 to 100. The API default is 25 |
| `pageToken` | `string \| null` | No | nextPageToken from a previous page of the same call |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `mediaItems` | `object[] \| null` | No | — |
| `nextPageToken` | `string \| null` | No | — |

> [accordion] mediaItems full type
>
> ```ts theme={null}
> {
>   id: string,
>   filename?: string | null,
>   mimeType?: string | null,
>   description?: string | null,
>   productUrl?: string | null,
>   baseUrl?: string | null,
>   mediaMetadata?: {
>     creationTime?: string | null,
>     width?: string | null,
>     height?: string | null,
>     photo?: {
>       cameraMake?: string | null,
>       cameraModel?: string | null,
>       focalLength?: number | null,
>       apertureFNumber?: number | null,
>       isoEquivalent?: number | null,
>       exposureTime?: string | null
>     } | null,
>     video?: {
>       cameraMake?: string | null,
>       cameraModel?: string | null,
>       fps?: number | null,
>       status?: string | null
>     } | null
>   } | null,
>   contributorInfo?: {
>     profilePictureBaseUrl?: string | null,
>     displayName?: string | null
>   } | null
> }[] | null
> ```

***

### search

`mediaItems.search`

Search the media items this app created with date, content, feature and media-type filters, or list one app-created album

**Risk:** `read`

```ts theme={null}
await corsair.googlephotos.api.mediaItems.search({ albumId: 'ABcDeFgHiJkLmNoP', pageSize: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `albumId` | `string \| null` | No | Search inside one album. Cannot be combined with filters |
| `filters` | `object \| null` | No | — |
| `orderBy` | `MediaMetadata.creation_time desc \| MediaMetadata.creation_time \| null` | No | Only usable with a date filter, and not with content, media type or feature filters. `desc` is newest first, which is also the default |
| `pageSize` | `number \| null` | No | 1 to 100. The API default is 25 |
| `pageToken` | `string \| null` | No | nextPageToken from a previous page of the same call |

Send `albumId` or `filters`, never both; the API answers 400 for that combination.

> [accordion] filters full type
>
> ```ts theme={null}
> {
>   dateFilter?: {
>     dates?: {
>       year?: number | null,
>       month?: number | null,
>       day?: number | null
>     }[],
>     ranges?: {
>       startDate?: {
>         year?: number | null,
>         month?: number | null,
>         day?: number | null
>       },
>       endDate?: {
>         year?: number | null,
>         month?: number | null,
>         day?: number | null
>       }
>     }[]
>   },
>   contentFilter?: {
>     includedContentCategories?: (NONE | LANDSCAPES | RECEIPTS | CITYSCAPES | LANDMARKS | SELFIES | PEOPLE | PETS | WEDDINGS | BIRTHDAYS | DOCUMENTS | TRAVEL | ANIMALS | FOOD | SPORT | NIGHT | PERFORMANCES | WHITEBOARDS | SCREENSHOTS | UTILITY | ARTS | CRAFTS | FASHION | HOUSES | GARDENS | FLOWERS | HOLIDAYS)[],
>     excludedContentCategories?: (NONE | LANDSCAPES | RECEIPTS | CITYSCAPES | LANDMARKS | SELFIES | PEOPLE | PETS | WEDDINGS | BIRTHDAYS | DOCUMENTS | TRAVEL | ANIMALS | FOOD | SPORT | NIGHT | PERFORMANCES | WHITEBOARDS | SCREENSHOTS | UTILITY | ARTS | CRAFTS | FASHION | HOUSES | GARDENS | FLOWERS | HOLIDAYS)[]
>   },
>   mediaTypeFilter?: {
>     mediaTypes?: (ALL_MEDIA | VIDEO | PHOTO)[]
>   },
>   featureFilter?: {
>     includedFeatures?: (NONE | FAVORITES)[]
>   },
>   includeArchivedMedia?: boolean,
>   excludeNonAppCreatedData?: boolean
> } | null
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `mediaItems` | `object[] \| null` | No | Absent when nothing matched |
| `nextPageToken` | `string \| null` | No | Its presence is the only reliable sign that more pages exist |

> [accordion] mediaItems full type
>
> ```ts theme={null}
> {
>   id: string,
>   filename?: string | null,
>   mimeType?: string | null,
>   description?: string | null,
>   productUrl?: string | null,
>   baseUrl?: string | null,
>   mediaMetadata?: {
>     creationTime?: string | null,
>     width?: string | null,
>     height?: string | null,
>     photo?: {
>       cameraMake?: string | null,
>       cameraModel?: string | null,
>       focalLength?: number | null,
>       apertureFNumber?: number | null,
>       isoEquivalent?: number | null,
>       exposureTime?: string | null
>     } | null,
>     video?: {
>       cameraMake?: string | null,
>       cameraModel?: string | null,
>       fps?: number | null,
>       status?: string | null
>     } | null
>   } | null,
>   contributorInfo?: {
>     profilePictureBaseUrl?: string | null,
>     displayName?: string | null
>   } | null
> }[] | null
> ```

***

### update

`mediaItems.update`

Change an app-created media item's description, the only editable field

**Risk:** `write`

```ts theme={null}
await corsair.googlephotos.api.mediaItems.update({ mediaItemId: 'AbCdEf123', description: 'Sunset over the bay' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `mediaItemId` | `string` | Yes | A media item id from a search or a batchCreate result |
| `description` | `string` | Yes | The new description, under 1000 characters. The only field the API lets an update change |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | A persistent id, stable between sessions |
| `filename` | `string \| null` | No | — |
| `mimeType` | `string \| null` | No | e.g. `image/jpeg` |
| `description` | `string \| null` | No | — |
| `productUrl` | `string \| null` | No | A Google Photos link the user can open when signed in |
| `baseUrl` | `string \| null` | No | A prefix for the bytes, valid for 60 minutes. A parameter must be appended before it can be fetched (`=d` for photo bytes, `=dv` for video bytes, `=w<w>-h<h>` for a scaled copy); the exported mediaBytesUrl helper builds it |
| `mediaMetadata` | `object \| null` | No | — |
| `contributorInfo` | `object \| null` | No | — |

> [accordion] mediaMetadata full type
>
> ```ts theme={null}
> {
>   creationTime?: string | null,
>   width?: string | null,
>   height?: string | null,
>   photo?: {
>     cameraMake?: string | null,
>     cameraModel?: string | null,
>     focalLength?: number | null,
>     apertureFNumber?: number | null,
>     isoEquivalent?: number | null,
>     exposureTime?: string | null
>   } | null,
>   video?: {
>     cameraMake?: string | null,
>     cameraModel?: string | null,
>     fps?: number | null,
>     status?: string | null
>   } | null
> } | null
> ```

> [accordion] contributorInfo full type
>
> ```ts theme={null}
> {
>   profilePictureBaseUrl?: string | null,
>   displayName?: string | null
> } | null
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.