Google Photos Library Albums API

openapi: 3.2.0
info:
  title: Photos Library Albums API
  version: v1
  description: Generated from Google's published Discovery document for Photos Library API (photoslibrary v1, revision 20261110). 9 operation(s).
  contact:
    name: Google
    url: https://developers.google.com/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://photoslibrary.googleapis.com
tags:
- name: Albums
paths:
  /v1/albums/{albumsId}:share:
    post:
      operationId: photoslibrary.albums.share
      summary: Share albums
      description: Marks an album as shared and accessible to other users. This action can only be performed on albums which were created by the developer via the API.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareAlbumRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareAlbumResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary.sharing
      - apiKey: []
      tags:
      - Albums
  /v1/albums/{albumsId}:
    patch:
      operationId: photoslibrary.albums.patch
      summary: Patch albums
      description: Update the app created album with the specified `id`. Only the `id`, `title` and `cover_photo_media_item_id` fields of the album are read. The album must have been created by the developer via the API.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      - name: updateMask
        in: query
        required: false
        description: Required. Indicate what fields in the provided album to update. The only valid values are `title` and `cover_photo_media_item_id`.
        schema:
          type: string
          format: google-fieldmask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Album'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata
      - apiKey: []
      tags:
      - Albums
    get:
      operationId: photoslibrary.albums.get
      summary: Get albums
      description: Returns the app created album based on the specified `albumId`. The `albumId` must be the ID of an album created by your app.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary
        - https://www.googleapis.com/auth/photoslibrary.readonly
        - https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
      - apiKey: []
      tags:
      - Albums
  /v1/albums/{albumsId}:batchRemoveMediaItems:
    post:
      operationId: photoslibrary.albums.batchRemoveMediaItems
      summary: Batch remove media items albums
      description: Removes one or more app created media items from a specified app created album. The media items and the album must have been created by the developer via the API. Partial success is not supported. The entire request will fail and no action will be performed on the album if an invalid media item or album is specified.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRemoveMediaItemsFromAlbumRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRemoveMediaItemsFromAlbumResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary
        - https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata
      - apiKey: []
      tags:
      - Albums
  /v1/albums/{albumsId}:unshare:
    post:
      operationId: photoslibrary.albums.unshare
      summary: Unshare albums
      description: Marks a previously shared album as private. This means that the album is no longer shared and all the non-owners will lose access to the album. All non-owner content will be removed from the album. If a non-owner has previously added the album to their library, they will retain all photos in their library. This action can only be performed on albums which were created by the developer via the API.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnshareAlbumRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnshareAlbumResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary.sharing
      - apiKey: []
      tags:
      - Albums
  /v1/albums/{albumsId}:addEnrichment:
    post:
      operationId: photoslibrary.albums.addEnrichment
      summary: Add enrichment albums
      description: Adds an enrichment at a specified position in an app created created album.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddEnrichmentToAlbumRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddEnrichmentToAlbumResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary
        - https://www.googleapis.com/auth/photoslibrary.appendonly
        - https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata
        - https://www.googleapis.com/auth/photoslibrary.sharing
      - apiKey: []
      tags:
      - Albums
  /v1/albums:
    post:
      operationId: photoslibrary.albums.create
      summary: Create albums
      description: Creates an album in a user's Google Photos library.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlbumRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary
        - https://www.googleapis.com/auth/photoslibrary.appendonly
        - https://www.googleapis.com/auth/photoslibrary.sharing
      - apiKey: []
      tags:
      - Albums
    get:
      operationId: photoslibrary.albums.list
      summary: List albums
      description: Lists all albums created by your app.
      parameters:
      - name: excludeNonAppCreatedData
        in: query
        required: false
        description: If set, the results exclude media items that were not created by this app. Defaults to false (all albums are returned). This field is ignored if the photoslibrary.readonly.appcreateddata scope is used.
        schema:
          type: boolean
      - name: pageSize
        in: query
        required: false
        description: Maximum number of albums to return in the response. Fewer albums might be returned than the specified number. The default `pageSize` is 20, the maximum is 50.
        schema:
          format: int32
          type: integer
      - name: pageToken
        in: query
        required: false
        description: A continuation token to get the next page of the results. Adding this to the request returns the rows after the `pageToken`. The `pageToken` should be the value returned in the `nextPageToken` parameter in the response to the `listAlbums` request.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAlbumsResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary
        - https://www.googleapis.com/auth/photoslibrary.readonly
        - https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
      - apiKey: []
      tags:
      - Albums
  /v1/albums/{albumsId}:batchAddMediaItems:
    post:
      operationId: photoslibrary.albums.batchAddMediaItems
      summary: Batch add media items albums
      description: Adds one or more app created media items in a user's Google Photos library to an app created album. The media items and albums must have been created by the developer via the API. Media items are added to the end of the album. If multiple media items are given, they are added in the order specified in this call. Each album can contain up to 20,000 media items. Partial success is not supported. The entire request will fail if an invalid media item or album is specified.
      parameters:
      - name: albumsId
        in: path
        required: true
        description: Resource name segment (albumsId).
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchAddMediaItemsToAlbumRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchAddMediaItemsToAlbumResponse'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/photoslibrary
        - https://www.googleapis.com/auth/photoslibrary.appendonly
        - https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata
        - https://www.googleapis.com/auth/photoslibrary.sharing
      - apiKey: []
      tags:
      - Albums
components:
  schemas:
    CreateAlbumRequest:
      description: Request to create an album in Google Photos.
      type: object
      properties:
        album:
          $ref: '#/components/schemas/Album'
          description: Required. The album to be created.
    Location:
      description: Represents a physical location.
      properties:
        locationName:
          description: Name of the location to be displayed.
          type: string
        latlng:
          $ref: '#/components/schemas/LatLng'
          description: Position of the location on the map.
      type: object
    AlbumPosition:
      properties:
        relativeEnrichmentItemId:
          description: The enrichment item to which the position is relative to. Only used when position type is AFTER_ENRICHMENT_ITEM.
          type: string
        relativeMediaItemId:
          description: The media item to which the position is relative to. Only used when position type is AFTER_MEDIA_ITEM.
          type: string
        position:
          description: Type of position, for a media or enrichment item.
          enum:
          - POSITION_TYPE_UNSPECIFIED
          - FIRST_IN_ALBUM
          - LAST_IN_ALBUM
          - AFTER_MEDIA_ITEM
          - AFTER_ENRICHMENT_ITEM
          type: string
      description: Specifies a position in an album.
      type: object
    ShareAlbumRequest:
      description: Request to make an album shared in Google Photos.
      properties:
        sharedAlbumOptions:
          $ref: '#/components/schemas/SharedAlbumOptions'
          description: Options to be set when converting the album to a shared album.
      type: object
    UnshareAlbumRequest:
      description: Request to unshare a shared album in Google Photos.
      type: object
      properties: {}
    LatLng:
      properties:
        longitude:
          type: number
          description: The longitude in degrees. It must be in the range [-180.0, +180.0].
          format: double
        latitude:
          format: double
          description: The latitude in degrees. It must be in the range [-90.0, +90.0].
          type: number
      type: object
      description: An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.
    ShareAlbumResponse:
      description: Response to successfully sharing an album.
      type: object
      properties:
        shareInfo:
          $ref: '#/components/schemas/ShareInfo'
          description: Output only. Information about the shared album.
    MapEnrichment:
      type: object
      description: An enrichment containing a map, showing origin and destination locations.
      properties:
        origin:
          $ref: '#/components/schemas/Location'
          description: Origin location for this enrichment item.
        destination:
          $ref: '#/components/schemas/Location'
          description: Destination location for this enrichemt item.
    LocationEnrichment:
      description: An enrichment containing a single location.
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Location'
          description: Location for this enrichment item.
    BatchRemoveMediaItemsFromAlbumRequest:
      properties:
        mediaItemIds:
          items:
            type: string
          description: Required. Identifiers of the MediaItems to be removed. Must not contain repeated identifiers and cannot be empty. The maximum number of media items that can be removed in one call is 50.
          type: array
      description: Request to remove a list of media items from an album.
      type: object
    BatchAddMediaItemsToAlbumResponse:
      description: Response for adding media items to an album.
      type: object
      properties: {}
    BatchAddMediaItemsToAlbumRequest:
      type: object
      properties:
        mediaItemIds:
          items:
            type: string
          type: array
          description: Required. Identifiers of the MediaItems to be added. The maximum number of media items that can be added in one call is 50.
      description: Request to add media items to an app created album.
    UnshareAlbumResponse:
      type: object
      description: Response of a successful unshare of a shared album.
      properties: {}
    GoogleRpcError:
      type: object
      description: The error envelope every Google API returns.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            status:
              type: string
            details:
              type: array
              items:
                type: object
    BatchRemoveMediaItemsFromAlbumResponse:
      type: object
      properties: {}
      description: Response for successfully removing all specified media items from the album.
    AddEnrichmentToAlbumRequest:
      type: object
      properties:
        newEnrichmentItem:
          $ref: '#/components/schemas/NewEnrichmentItem'
          description: Required. The enrichment to be added.
        albumPosition:
          $ref: '#/components/schemas/AlbumPosition'
          description: Required. The position in the app created album where the enrichment is to be inserted.
      description: Request to add an enrichment to a specific album at a specific position.
    AddEnrichmentToAlbumResponse:
      type: object
      properties:
        enrichmentItem:
          $ref: '#/components/schemas/EnrichmentItem'
          description: Output only. Enrichment which was added.
      description: The enrichment item that's created.
    NewEnrichmentItem:
      properties:
        textEnrichment:
          $ref: '#/components/schemas/TextEnrichment'
          description: Text to be added to the app created album.
        locationEnrichment:
          $ref: '#/components/schemas/LocationEnrichment'
          description: Location to be added to the app created album.
        mapEnrichment:
          $ref: '#/components/schemas/MapEnrichment'
          description: Map to be added to the app created album.
      type: object
      description: A new enrichment item to be added to an app created album, used by the `albums.addEnrichment` call.
    ListAlbumsResponse:
      properties:
        albums:
          items:
            $ref: '#/components/schemas/Album'
          description: Output only. List of albums shown in the Albums tab of the user's Google Photos app.
          type: array
        nextPageToken:
          type: string
          description: Output only. Token to use to get the next set of albums. Populated if there are more albums to retrieve for this request.
      description: List of albums requested.
      type: object
    TextEnrichment:
      properties:
        text:
          description: Text for this enrichment item.
          type: string
      type: object
      description: An enrichment containing text.
    Album:
      description: Representation of an album in Google Photos. Albums are containers for media items. If an album has been shared by the application, it contains an extra `shareInfo` property.
      properties:
        isWriteable:
          description: '[Output only] True if you can create media items in this album. This field is based on the scopes granted and permissions of the album. If the scopes are changed or permissions of the album are changed, this field is updated.'
          type: boolean
        title:
          description: Name of the album displayed to the user in their Google Photos account. This string shouldn't be more than 500 characters.
          type: string
        coverPhotoMediaItemId:
          type: string
          description: Identifier for the media item associated with the cover photo.
        productUrl:
          description: '[Output only] Google Photos URL for the album. The user needs to be signed in to their Google Photos account to access this link.'
          type: string
        id:
          description: Identifier for the album. This is a persistent identifier that can be used between sessions to identify this album.
          type: string
        shareInfo:
          $ref: '#/components/schemas/ShareInfo'
          description: '[Output only] Information related to shared albums. This field is only populated if the album is a shared album, the developer created the album and the user has granted the `photoslibrary.sharing` scope.'
        mediaItemsCount:
          format: int64
          description: '[Output only] The number of media items in the album.'
          type: string
        coverPhotoBaseUrl:
          type: string
          description: '[Output only] A URL to the cover photo''s bytes. This shouldn''t be used as is. Parameters should be appended to this URL before use. See the [developer documentation](https://developers.google.com/photos/library/guides/access-media-items#base-urls) for a complete list of supported parameters. For example, `''=w2048-h1024''` sets the dimensions of the cover photo to have a width of 2048 px and height of 1024 px.'
      type: object
    ShareInfo:
      type: object
      properties:
        sharedAlbumOptions:
          $ref: '#/components/schemas/SharedAlbumOptions'
          description: Options that control whether someone can add media items to, or comment on a shared album.
        shareToken:
          description: A token that is used to join, leave, or retrieve the details of a shared album on behalf of a user who isn't the owner. A `shareToken` is invalidated if the owner turns off link sharing in the Google Photos app, or if the album is unshared.
          type: string
        isJoined:
          description: True if the user is joined to the album. This is always true for the owner of the album.
          type: boolean
        shareableUrl:
          type: string
          description: A link to the shared Google Photos album. Anyone with the link can view the contents of the album, so it should be treated with care. The `shareableUrl` parameter is only returned if the album has link sharing turned on. If a user is already joined to an album that isn't link-shared, they can use the album's [`productUrl`](https://developers.google.com/photos/library/reference/rest/v1/albums#Album) to access it instead. A `shareableUrl` is invalidated if the owner turns off link sharing in the Google Photos app, or if the album is unshared.
        isOwned:
          type: boolean
          description: True if the user owns the album.
        isJoinable:
          description: True if the album can be joined by users.
          type: boolean
      description: Information about albums that are shared. This information is only included if you created the album, it is shared and you have the sharing scope.
    EnrichmentItem:
      type: object
      properties:
        id:
          description: Identifier of the enrichment item.
          type: string
      description: An enrichment item.
    SharedAlbumOptions:
      description: Options that control the sharing of an album.
      properties:
        isCollaborative:
          description: True if the shared album allows collaborators (users who have joined the album) to add media items to it. Defaults to false.
          type: boolean
        isCommentable:
          description: True if the shared album allows collaborators (users who have joined the album) to add comments to the album. Defaults to false.
          type: boolean
      type: object
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: API key; accepted by methods that do not need user data.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/photoslibrary.readonly: View your Google Photos library
            https://www.googleapis.com/auth/photoslibrary: See, upload, and organize items in your Google Photos library
            https://www.googleapis.com/auth/photoslibrary.edit.appcreateddata: Edit the info in your photos, videos, and albums created within this app, including titles, descriptions, and covers
            https://www.googleapis.com/auth/photoslibrary.sharing: Manage and add to shared albums on your behalf
            https://www.googleapis.com/auth/photoslibrary.appendonly: Add to your Google Photos library
            https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata: Manage photos added by this app
externalDocs:
  url: https://developers.google.com/photos/
x-provenance:
  method: harvested
  publisher: Google
  source: https://photoslibrary.googleapis.com/$discovery/rest?version=v1
  note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261110)