Google Cloud Storage Objects API

openapi: 3.1.0
info:
  title: Google Cloud Storage JSON BucketAccessControls Objects API
  description: RESTful API for managing Google Cloud Storage resources including buckets and objects. Cloud Storage allows you to store and retrieve data on Google's infrastructure with high durability, availability, and scalability. The JSON API provides programmatic access to create, configure, and manage storage buckets, upload and download objects, control access permissions, and manage object metadata.
  version: v1
  contact:
    name: Google Cloud Storage
    url: https://cloud.google.com/storage/docs/json_api
  termsOfService: https://cloud.google.com/terms
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://storage.googleapis.com/storage/v1
  description: Google Cloud Storage JSON API v1
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Objects
  description: Operations for managing objects within Cloud Storage buckets
paths:
  /b/{bucket}/o:
    get:
      operationId: listObjects
      summary: Google Cloud Storage List Objects
      description: Retrieves a list of objects matching the criteria. The authenticated user must have the storage.objects.list permission for the bucket. Lists objects in a bucket, optionally filtering by a prefix and delimiter to emulate directory listing.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: delimiter
        in: query
        required: false
        description: Returns results in a directory-like mode. Items will contain only objects whose names, aside from the prefix, do not contain delimiter. Objects whose names, aside from the prefix, contain delimiter will have their name truncated after the delimiter, returned in prefixes. Duplicate prefixes are omitted.
        schema:
          type: string
        example: /
      - name: endOffset
        in: query
        required: false
        description: Filter results to objects whose names are lexicographically before endOffset. If startOffset is also set, the objects listed have names between startOffset (inclusive) and endOffset (exclusive).
        schema:
          type: string
      - name: includeFoldersAsPrefixes
        in: query
        required: false
        description: Only applicable if delimiter is set to /. If true, will also include folders and managed folders (besides objects) in the returned prefixes.
        schema:
          type: boolean
      - name: includeTrailingDelimiter
        in: query
        required: false
        description: If true, objects that end in exactly one instance of delimiter will have their metadata included in items in addition to prefixes.
        schema:
          type: boolean
      - name: matchGlob
        in: query
        required: false
        description: Filter results to objects and prefixes that match this glob pattern. Supports *, **, ?, and [...] character classes.
        schema:
          type: string
      - name: maxResults
        in: query
        required: false
        description: Maximum number of items plus prefixes to return in a single page of responses. The service may return fewer than this value.
        schema:
          type: integer
          minimum: 1
          default: 1000
      - name: pageToken
        in: query
        required: false
        description: A previously-returned page token representing part of the larger set of results to view.
        schema:
          type: string
      - name: prefix
        in: query
        required: false
        description: Filter results to objects whose names begin with this prefix.
        schema:
          type: string
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to noAcl.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: noAcl
      - name: softDeleted
        in: query
        required: false
        description: If true, only lists soft-deleted object versions.
        schema:
          type: boolean
      - name: startOffset
        in: query
        required: false
        description: Filter results to objects whose names are lexicographically equal to or after startOffset.
        schema:
          type: string
      - name: versions
        in: query
        required: false
        description: If true, lists all versions of an object as distinct results. The default is false.
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Successful response with a list of objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}/o/{object}:
    get:
      operationId: getObject
      summary: Google Cloud Storage Get an Object
      description: Retrieves an object or its metadata. The authenticated user must have the storage.objects.get permission for the object. By default, this returns the object metadata. Use alt=media to download the object data.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - $ref: '#/components/parameters/objectName'
      - name: alt
        in: query
        required: false
        description: Data format for the response. Use json for metadata or media to download the object data.
        schema:
          type: string
          enum:
          - json
          - media
          default: json
      - name: generation
        in: query
        required: false
        description: If present, selects a specific revision of this object.
        schema:
          type: integer
          format: int64
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object.
        schema:
          type: integer
          format: int64
      - name: ifGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to noAcl.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: noAcl
      - name: softDeleted
        in: query
        required: false
        description: If true, retrieves the soft-deleted version of the object.
        schema:
          type: boolean
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Successful response with object metadata (alt=json) or object data (alt=media).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
            application/octet-stream:
              schema:
                type: string
                format: binary
        '304':
          description: Not Modified. The object has not been modified since the specified conditions.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateObject
      summary: Google Cloud Storage Update an Object
      description: Updates an object's metadata. This method replaces all mutable metadata fields of the object with the values in the request body.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - $ref: '#/components/parameters/objectName'
      - name: generation
        in: query
        required: false
        description: If present, selects a specific revision of this object.
        schema:
          type: integer
          format: int64
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: predefinedAcl
        in: query
        required: false
        description: Apply a predefined set of access controls to the object.
        schema:
          type: string
          enum:
          - authenticatedRead
          - bucketOwnerFullControl
          - bucketOwnerRead
          - private
          - projectPrivate
          - publicRead
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to full.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: full
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Object metadata updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: patchObject
      summary: Google Cloud Storage Patch an Object
      description: Patches an object's metadata. This method supports patch semantics where only the specified fields are updated.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - $ref: '#/components/parameters/objectName'
      - name: generation
        in: query
        required: false
        description: If present, selects a specific revision of this object.
        schema:
          type: integer
          format: int64
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: predefinedAcl
        in: query
        required: false
        description: Apply a predefined set of access controls to the object.
        schema:
          type: string
          enum:
          - authenticatedRead
          - bucketOwnerFullControl
          - bucketOwnerRead
          - private
          - projectPrivate
          - publicRead
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to full.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: full
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Object metadata patched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteObject
      summary: Google Cloud Storage Delete an Object
      description: Deletes an object and its metadata. Deletions are permanent if versioning is not enabled for the bucket, or if the object is not the latest version. When versioning is enabled, deleting the latest version creates a delete marker.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - $ref: '#/components/parameters/objectName'
      - name: generation
        in: query
        required: false
        description: If present, permanently deletes a specific revision of this object.
        schema:
          type: integer
          format: int64
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/userProject'
      responses:
        '204':
          description: Object deleted successfully. No content returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}/o/{object}/compose:
    post:
      operationId: composeObject
      summary: Google Cloud Storage Compose Objects
      description: Concatenates a list of existing objects into a new object in the same bucket. The composed object can contain no more than 32 source objects. The destination object's metadata is identical to that of the first source object unless overridden.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: object
        in: path
        required: true
        description: Name of the destination object.
        schema:
          type: string
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeRequest'
      responses:
        '200':
          description: Object composed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}/o/{object}/copyTo/b/{destinationBucket}/o/{destinationObject}:
    post:
      operationId: copyObject
      summary: Google Cloud Storage Copy an Object
      description: Copies a source object to a destination object. Optionally overrides metadata. This method creates a copy of an object as a new object in the destination bucket.
      tags:
      - Objects
      parameters:
      - name: bucket
        in: path
        required: true
        description: Name of the source bucket.
        schema:
          type: string
      - name: object
        in: path
        required: true
        description: Name of the source object. For information about how to URL-encode object names, see Encoding URI path parts.
        schema:
          type: string
      - name: destinationBucket
        in: path
        required: true
        description: Name of the destination bucket.
        schema:
          type: string
      - name: destinationObject
        in: path
        required: true
        description: Name of the destination object.
        schema:
          type: string
      - name: destinationPredefinedAcl
        in: query
        required: false
        description: Apply a predefined set of access controls to the destination object.
        schema:
          type: string
          enum:
          - authenticatedRead
          - bucketOwnerFullControl
          - bucketOwnerRead
          - private
          - projectPrivate
          - publicRead
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to noAcl.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: noAcl
      - name: sourceGeneration
        in: query
        required: false
        description: If present, selects a specific revision of the source object.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Object copied successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}/o/{object}/rewriteTo/b/{destinationBucket}/o/{destinationObject}:
    post:
      operationId: rewriteObject
      summary: Google Cloud Storage Rewrite an Object
      description: Rewrites a source object to a destination object. Optionally overrides metadata. This method can copy objects across locations and storage classes, and can also be used to change an object's encryption key. For large objects, this method may require multiple calls.
      tags:
      - Objects
      parameters:
      - name: bucket
        in: path
        required: true
        description: Name of the source bucket.
        schema:
          type: string
      - name: object
        in: path
        required: true
        description: Name of the source object.
        schema:
          type: string
      - name: destinationBucket
        in: path
        required: true
        description: Name of the destination bucket.
        schema:
          type: string
      - name: destinationObject
        in: path
        required: true
        description: Name of the destination object.
        schema:
          type: string
      - name: destinationKmsKeyName
        in: query
        required: false
        description: Resource name of the Cloud KMS key that will be used to encrypt the destination object.
        schema:
          type: string
      - name: destinationPredefinedAcl
        in: query
        required: false
        description: Apply a predefined set of access controls to the destination object.
        schema:
          type: string
          enum:
          - authenticatedRead
          - bucketOwnerFullControl
          - bucketOwnerRead
          - private
          - projectPrivate
          - publicRead
      - name: ifGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the destination object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceGenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current generation matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceGenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current generation does not match the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceMetagenerationMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifSourceMetagenerationNotMatch
        in: query
        required: false
        description: Makes the operation conditional on whether the source object's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - name: maxBytesRewrittenPerCall
        in: query
        required: false
        description: The maximum number of bytes that will be rewritten per rewrite request. Allows throttling of large copies.
        schema:
          type: integer
          format: int64
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to noAcl.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: noAcl
      - name: rewriteToken
        in: query
        required: false
        description: Include this field only if the previous rewrite response included a rewriteToken. Provides a token for resuming a previously started rewrite operation.
        schema:
          type: string
      - name: sourceGeneration
        in: query
        required: false
        description: If present, selects a specific revision of the source object.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Rewrite response. If done is false, the rewrite is not yet complete and another call must be made with the returned rewriteToken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewriteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}/o/watchAll:
    post:
      operationId: watchAllObjects
      summary: Google Cloud Storage Watch for Object Changes
      description: Watch for changes on all objects in a bucket. This method creates a notification channel that sends a notification whenever an object is created, updated, or deleted.
      tags:
      - Objects
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: prefix
        in: query
        required: false
        description: Limits notifications to objects with names beginning with this prefix.
        schema:
          type: string
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Channel'
      responses:
        '200':
          description: Watch channel created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /channels/stop:
    post:
      operationId: stopChannel
      summary: Google Cloud Storage Stop a Notification Channel
      description: Stop receiving object change notifications through a previously created watch channel.
      tags:
      - Objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Channel'
      responses:
        '204':
          description: Channel stopped successfully. No content returned.
        '400':
          $ref: '#/components/respon

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gcp-cloud-storage/refs/heads/main/openapi/gcp-cloud-storage-objects-api-openapi.yml