Google Cloud Storage Buckets API

openapi: 3.1.0
info:
  title: Google Cloud Storage JSON BucketAccessControls Buckets 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: Buckets
  description: Operations for managing Cloud Storage buckets
paths:
  /b:
    get:
      operationId: listBuckets
      summary: Google Cloud Storage List Buckets
      description: Retrieves a list of buckets for a given project. The authenticated user must have the storage.buckets.list permission for the specified project.
      tags:
      - Buckets
      parameters:
      - name: project
        in: query
        required: true
        description: The project ID or project number to list buckets for.
        schema:
          type: string
        example: my-project-id
      - name: maxResults
        in: query
        required: false
        description: Maximum number of buckets to return in a single response. The service uses this value or 1,000 items, whichever is smaller.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
      - name: pageToken
        in: query
        required: false
        description: A previously-returned page token representing part of the larger set of results to view. The pageToken is an encoded field that marks the name and generation of the last bucket in the previous list response.
        schema:
          type: string
      - name: prefix
        in: query
        required: false
        description: Filter results to buckets 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
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Successful response with a list of buckets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BucketList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: insertBucket
      summary: Google Cloud Storage Create a Bucket
      description: Creates a new bucket in the specified project. The authenticated user must have the storage.buckets.create permission for the project. Bucket names must be globally unique across all of Cloud Storage.
      tags:
      - Buckets
      parameters:
      - name: project
        in: query
        required: true
        description: The project ID or project number to create the bucket in.
        schema:
          type: string
        example: my-project-id
      - name: predefinedAcl
        in: query
        required: false
        description: Apply a predefined set of access controls to the bucket.
        schema:
          type: string
          enum:
          - authenticatedRead
          - private
          - projectPrivate
          - publicRead
          - publicReadWrite
      - name: predefinedDefaultObjectAcl
        in: query
        required: false
        description: Apply a predefined set of default object access controls to the bucket.
        schema:
          type: string
          enum:
          - authenticatedRead
          - bucketOwnerFullControl
          - bucketOwnerRead
          - private
          - projectPrivate
          - publicRead
      - name: projection
        in: query
        required: false
        description: Set of properties to return. Defaults to noAcl.
        schema:
          type: string
          enum:
          - full
          - noAcl
          default: noAcl
      - name: enableObjectRetention
        in: query
        required: false
        description: When set to true, object retention is enabled for this bucket.
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bucket'
      responses:
        '200':
          description: Bucket created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict. A bucket with the specified name already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}:
    get:
      operationId: getBucket
      summary: Google Cloud Storage Get a Bucket
      description: Returns metadata for the specified bucket. The authenticated user must have the storage.buckets.get permission for the bucket.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the return of the bucket metadata conditional on whether the bucket's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the return of the bucket metadata conditional on whether the bucket'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
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/prettyPrint'
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Successful response with bucket metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '304':
          description: Not Modified. The bucket has not been modified since the specified metageneration.
        '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
    put:
      operationId: updateBucket
      summary: Google Cloud Storage Update a Bucket
      description: Updates a bucket. Changes to the bucket will be readable immediately after writing, but configuration changes may take time to propagate. This method replaces all mutable properties of the bucket with the values in the request body.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the update conditional on whether the bucket's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the update conditional on whether the bucket'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 bucket.
        schema:
          type: string
          enum:
          - authenticatedRead
          - private
          - projectPrivate
          - publicRead
          - publicReadWrite
      - name: predefinedDefaultObjectAcl
        in: query
        required: false
        description: Apply a predefined set of default object access controls.
        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/Bucket'
      responses:
        '200':
          description: Bucket updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '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: patchBucket
      summary: Google Cloud Storage Patch a Bucket
      description: Patches a bucket. Changes to the bucket will be readable immediately after writing, but configuration changes may take time to propagate. This method supports patch semantics where only the specified fields are updated.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the patch conditional on whether the bucket's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the patch conditional on whether the bucket'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 bucket.
        schema:
          type: string
          enum:
          - authenticatedRead
          - private
          - projectPrivate
          - publicRead
          - publicReadWrite
      - name: predefinedDefaultObjectAcl
        in: query
        required: false
        description: Apply a predefined set of default object access controls.
        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/Bucket'
      responses:
        '200':
          description: Bucket patched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '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: deleteBucket
      summary: Google Cloud Storage Delete a Bucket
      description: Permanently deletes an empty bucket. The authenticated user must have the storage.buckets.delete permission for the bucket. The bucket must be empty before it can be deleted.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: ifMetagenerationMatch
        in: query
        required: false
        description: Makes the deletion conditional on whether the bucket's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        description: Makes the deletion conditional on whether the bucket's current metageneration does not match the given value.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/userProject'
      responses:
        '204':
          description: Bucket 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'
        '409':
          description: Conflict. The bucket is not empty and cannot be deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b/{bucket}/lockRetentionPolicy:
    post:
      operationId: lockBucketRetentionPolicy
      summary: Google Cloud Storage Lock Retention Policy
      description: Locks retention policy on a bucket. This action is irreversible. Once locked, the retention policy cannot be removed or the retention period shortened.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: ifMetagenerationMatch
        in: query
        required: true
        description: Makes the operation conditional on whether the bucket's current metageneration matches the given value.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Retention policy locked successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bucket'
        '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}/iam:
    get:
      operationId: getBucketIamPolicy
      summary: Google Cloud Storage Get Bucket Iam Policy
      description: Returns an IAM policy for the specified bucket. The authenticated user must have the storage.buckets.getIamPolicy permission.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: optionsRequestedPolicyVersion
        in: query
        required: false
        description: The IAM policy format version to be returned. Valid values are 1 and 3. Requests specifying an invalid value will be rejected. Defaults to 1.
        schema:
          type: integer
          enum:
          - 1
          - 3
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Successful response with the IAM policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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
    put:
      operationId: setBucketIamPolicy
      summary: Google Cloud Storage Set Bucket Iam Policy
      description: Updates an IAM policy for the specified bucket. The authenticated user must have the storage.buckets.setIamPolicy permission.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - $ref: '#/components/parameters/userProject'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
      responses:
        '200':
          description: IAM policy updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '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}/iam/testPermissions:
    get:
      operationId: testBucketIamPermissions
      summary: Google Cloud Storage Test Bucket Iam Permissions
      description: Tests a set of permissions on the given bucket to see which, if any, are held by the caller. The authenticated user must have the storage.buckets.testIamPermissions permission.
      tags:
      - Buckets
      parameters:
      - $ref: '#/components/parameters/bucketName'
      - name: permissions
        in: query
        required: true
        description: Permissions to test.
        schema:
          type: array
          items:
            type: string
        example:
        - storage.buckets.get
        - storage.objects.list
      - $ref: '#/components/parameters/userProject'
      responses:
        '200':
          description: Successful response with test results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  kind:
                    type: string
                    default: storage#testIamPermissionsResponse
                  permissions:
                    type: array
                    items:
                      type: string
                    description: The permissions held by the caller. This is a subset of the requested permissions.
        '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
components:
  schemas:
    ObjectAccessControl:
      type: object
      description: An access-control entry for an object.
      properties:
        kind:
          type: string
          description: The kind of item this is.
          default: storage#objectAccessControl
          readOnly: true
          example: example_value
        id:
          type: string
          description: The ID of the access-control entry.
          readOnly: true
          example: abc123
        selfLink:
          type: string
          format: uri
          description: The link to this access-control entry.
          readOnly: true
          example: https://www.example.com
        bucket:
          type: string
          description: The name of the bucket.
          example: example_value
        object:
          type: string
          description: The name of the object.
          example: example_value
        generation:
          type: string
          description: The content generation of the object.
          example: example_value
        entity:
          type: string
          description: 'The entity holding the permission, in one of the following forms: user-userId, user-email, group-groupId, group-email, domain-domain, project-team-projectId, allUsers, or allAuthenticatedUsers.'
          example: example_value
        role:
          type: string
          description: The access permission for the entity.
          enum:
          - OWNER
          - READER
          example: OWNER
        email:
          type: string
          format: email
          description: The email address associated with the entity, if any.
          readOnly: true
          example: user@example.com
        domain:
          type: string
          description: The domain associated with the entity, if any.
          readOnly: true
          example: example_value
        entityId:
          type: string
          description: The ID for the entity, if any.
          readOnly: true
          example: '500123'
        etag:
          type: string
          description: HTTP 1.1 Entity tag for the access-control entry.
          readOnly: true
          example: example_value
        projectTeam:
          type: object
          description: The project team associated with the entity, if any.
          readOnly: true
          properties:
            projectNumber:
              type: string
              description: The project number.
            team:
              type: string
              description: The team.
              enum:
              - editors
              - owners
              - viewers
          example: example_value
      required:
      - entity
      - role
    Bucket:
      type: object
      description: A bucket is a container for objects stored in Cloud Storage. Buckets are associated with a project and have globally unique names.
      properties:
        kind:
          type: string
          description: The kind of item this is. For buckets, this is always storage#bucket.
          default: storage#bucket
          readOnly: true
          example: example_value
        id:
          type: string
          description: The ID of the bucket. For buckets, this is the same as the name.
          readOnly: true
          examples:
          - my-bucket
        selfLink:
          type: string
          format: uri
          description: The URI of this bucket.
          readOnly: true
          example: https://www.example.com
        projectNumber:
          type: string
          description: The project number of the project the bucket belongs to.
          readOnly: true
          example: example_value
        name:
          type: string
          description: The name of the bucket. Bucket names must be globally unique and conform to naming requirements (3-63 characters, lowercase letters, numbers, hyphens, and dots).
          minLength: 3
          maxLength: 63
          examples:
          - my-bucket
          - example-project-data
        timeCreated:
          type: string
          format: date-time
          description: The creation time of the bucket in RFC 3339 format.
          readOnly: true
          examples:
          - '2024-01-15T09:00:00.000Z'
        updated:
          type: string
          format: date-time
          description: The modification time of the bucket in RFC 3339 format.
          readOnly: true
          example: '2026-01-15T10:30:00Z'
        metageneration:
          type: string
          description: The metadata generation of this bucket. Used for preconditions and for detecting changes in metadata.
          readOnly: true
          example: example_value
        location:
          type: string
          description: The location of the bucket. Object data for objects in the bucket resides in physical storage within this region.
          examples:
          - US
          - US-EAST1
          - EUROPE-WEST1
        locationType:
          type: string
          description: The type of location the bucket resides in.
          enum:
          - multi-region
          - region
          - dual-region
          readOnly: true
          example: multi-region
        storageClass:
          type: string
          description: The default storage class of the bucket, used for newly created objects.
          enum:
          - STANDARD
          - NEARLINE
          - COLDLINE
          - ARCHIVE
          examples:
          - STANDARD
        etag:
          type: string
          description: HTTP 1.1 Entity tag for the bucket.
          readOnly: true
          example: example_value
        defaultEventBasedHold:
          type: boolean
          description: Whether or not to automatically apply an event-based hold to new objects added to the bucket.
          example: true
        rpo:
          type: string
          description: The Recovery Point Objective (RPO) of this bucket. Set to ASYNC_TURBO to turn on Turbo Replication for dual-region buckets.
          enum:
          - DEFAULT
          - ASYNC_TURBO
          example: DEFAULT
        acl:
          type: array
          description: Access controls on the bucket.
          items:
            $ref: '#/components/schemas/BucketAccessControl'
          example: []
        defaultObjectAcl:
          type: array
          description: Default access controls to apply to new objects when no ACL is provided.
          items:
            $ref: '#/components/schemas/ObjectAccessControl'
          example: []
        iamConfiguration:
          type: object
          description: The bucket's IAM configuration.
          properties:
            uniformBucketLevelAccess:
              type: object
              description: The bucket's uniform bucket-level access configuration. When enabled, access is controlled through IAM policies only and ACLs are disabled.
              properties:
                enabled:
                  type: boolean
                  description: Whether uniform bucket-level access is enabled.
                lockedTime:
                  type: string
                  format: date-time
                  description: The deadline for changing the uniform bucket-level access setting. After this time, the setting becomes permanent.
            publicAccessPrevention:
              type: string
              description: The bucket's public access prevention configuration.
              enum:
              - inherited
              - enforced
          example: example_value
        encryption:
          type: object
          description: Encryption configuration for a bucket.
          properties:
            defaultKmsKeyName:
              type: string
              description: A Cloud KMS key that will be used to encrypt objects inserted into this bucket, if no encryption method is specified.
          example: example_value
        lifecycle:
          type: object
          description: The bucket's lifecycle configuration. Lifecycle rules automatically manage objects based on conditions.
          properties:
            rule:
              type: array
              items:
                type: object
                properties:
                  action:
                    type: object
                    description: The action to take when lifecycle conditions are met.
                    properties:
                      type:
                        type: string
                        description: Type of the action.
                        enum:
                        - Delete
                        - SetStorageClass
                        - AbortIncompleteMultipartUpload
                      storageClass:
                        type: string
                        description: Target storage class. Required when action type is SetStorageClass.
                  condition:
                    type: object
                    description: The condition(s) under which the action will be taken.
                    properties:
                      age:
                        type: integer
                        description: Age of an object in days.
                      createdBefore:
                        type: string
                        format: date
                        description: A date in RFC 3339 format. Applies to objects created before this date.
                      customTimeBefore:
                        type: string
                        format: date
                        description: A date in RFC 3339 format. Applies to objects with a custom time before this date.
                      daysSinceCustomTime:
                        type: integer
                        description: Number of days elapsed since the custom time.
                      daysSinceNoncurrentTime:
                        type: integer
                        description: Number of days elapsed since the noncurrent timestamp.
                      isLive:
                        type: boolean
                        description: Relevant only for versioned objects. true for live objects, false for noncurrent objects.
                      matchesPattern:
                        type: string
                        description: A regular expression that satisfies RE2 syntax.
                      matchesPrefix:
                        type: array
                        items:
                          type: string
                        description: Objects having names with the listed prefixes satisfy this condition.
                      matchesSuffix:
                        type: array
                        items:
                          type: string
                        description: Objects having names with the listed suffixes satisfy this condition.
                      matchesStorageClass:
                        type: array
                        items:
                          type: string
                        description: Objects having any of the listed storage classes satisfy this condition.
                      noncurrentTimeBefore:
                        type: string
                        format: date
                        description: A date in RFC 3339 format. Applies to the noncurrent time of an object.
                      numNewerVersions:
                        type: integer
                        description: Relevant only for versioned objects. The number of newer versions of an object.
          example: example_value
        logging:
          type: object
          description: The bucket's logging configuration.
          properties:
            logBucket:
              type: string
              description: The destination bucket for access logs.

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