Google Cloud Storage Managed Folders API

openapi: 3.2.0
info:
  title: Cloud Storage JSON Managed Folders API
  description: Stores and retrieves potentially large, immutable data objects.
  version: v1
  x-discovery-revision: '20261030'
  termsOfService: https://developers.google.com/terms/
  contact:
    name: Google Cloud Storage
    url: https://developers.google.com/storage/docs/json_api/
  x-generated-from: google-discovery
  x-source: https://storage.googleapis.com/$discovery/rest?version=v1
  x-conversion: mechanical Discovery-to-OpenAPI conversion by API Evangelist; every path, parameter and schema is copied from the provider Discovery document
servers:
- url: https://storage.googleapis.com
security:
- oauth2:
  - https://www.googleapis.com/auth/cloud-platform
  - https://www.googleapis.com/auth/cloud-platform.read-only
  - https://www.googleapis.com/auth/devstorage.full_control
  - https://www.googleapis.com/auth/devstorage.read_only
  - https://www.googleapis.com/auth/devstorage.read_write
tags:
- name: managedFolders
paths:
  /storage/v1/b/{bucket}/managedFolders/{managedFolder}:
    delete:
      operationId: storage.managedFolders.delete
      tags:
      - managedFolders
      summary: Permanently deletes a managed folder
      description: Permanently deletes a managed folder.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      - name: managedFolder
        in: path
        required: true
        schema:
          type: string
        description: The managed folder name/path.
      - name: ifMetagenerationMatch
        in: query
        required: false
        schema:
          type: string
          format: int64
        description: If set, only deletes the managed folder if its metageneration matches this value.
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        schema:
          type: string
          format: int64
        description: If set, only deletes the managed folder if its metageneration does not match this value.
      - name: allowNonEmpty
        in: query
        required: false
        schema:
          type: boolean
        description: Allows the deletion of a managed folder even if it is not empty. A managed folder is empty if there are no objects or managed folders that it applies to. Callers must have storage.managedFolders.setIamPolicy permission.
      responses:
        '200':
          description: Successful response
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_write
    get:
      operationId: storage.managedFolders.get
      tags:
      - managedFolders
      summary: Returns metadata of the specified managed folder
      description: Returns metadata of the specified managed folder.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      - name: managedFolder
        in: path
        required: true
        schema:
          type: string
        description: The managed folder name/path.
      - name: ifMetagenerationMatch
        in: query
        required: false
        schema:
          type: string
          format: int64
        description: Makes the return of the managed folder metadata conditional on whether the managed folder's current metageneration matches the given value.
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        schema:
          type: string
          format: int64
        description: Makes the return of the managed folder metadata conditional on whether the managed folder's current metageneration does not match the given value.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedFolder'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/cloud-platform.read-only
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_only
        - https://www.googleapis.com/auth/devstorage.read_write
    patch:
      operationId: storage.managedFolders.update
      tags:
      - managedFolders
      summary: Updates a managed folder using patch semantics
      description: Updates a managed folder using patch semantics.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: The name of the bucket containing the managed folder.
      - name: managedFolder
        in: path
        required: true
        schema:
          type: string
        description: The name of the managed folder.
      - name: ifMetagenerationMatch
        in: query
        required: false
        schema:
          type: string
          format: int64
        description: Makes the operation conditional on whether the metageneration of the managed folder matches the specified value.
      - name: ifMetagenerationNotMatch
        in: query
        required: false
        schema:
          type: string
          format: int64
        description: Makes the operation conditional on whether the metageneration of the managed folder doesn't match the specified value.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedFolder'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedFolder'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_write
  /storage/v1/b/{bucket}/managedFolders/{managedFolder}/iam:
    get:
      operationId: storage.managedFolders.getIamPolicy
      tags:
      - managedFolders
      summary: Returns an IAM policy for the specified managed folder
      description: Returns an IAM policy for the specified managed folder.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      - name: optionsRequestedPolicyVersion
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: The IAM policy format version to be returned. If the optionsRequestedPolicyVersion is for an older version that doesn't support part of the requested IAM policy, the request fails.
      - name: managedFolder
        in: path
        required: true
        schema:
          type: string
        description: The managed folder name/path.
      - name: userProject
        in: query
        required: false
        schema:
          type: string
        description: The project to be billed for this request. Required for Requester Pays buckets.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/cloud-platform.read-only
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_only
        - https://www.googleapis.com/auth/devstorage.read_write
    put:
      operationId: storage.managedFolders.setIamPolicy
      tags:
      - managedFolders
      summary: Updates an IAM policy for the specified managed folder
      description: Updates an IAM policy for the specified managed folder.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      - name: managedFolder
        in: path
        required: true
        schema:
          type: string
        description: The managed folder name/path.
      - name: userProject
        in: query
        required: false
        schema:
          type: string
        description: The project to be billed for this request. Required for Requester Pays buckets.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/devstorage.full_control
  /storage/v1/b/{bucket}/managedFolders:
    post:
      operationId: storage.managedFolders.insert
      tags:
      - managedFolders
      summary: Creates a new managed folder
      description: Creates a new managed folder.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedFolder'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedFolder'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_write
    get:
      operationId: storage.managedFolders.list
      tags:
      - managedFolders
      summary: Lists managed folders in the given bucket
      description: Lists managed folders in the given bucket.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: Maximum number of items to return in a single page of responses.
      - name: pageToken
        in: query
        required: false
        schema:
          type: string
        description: A previously-returned page token representing part of the larger set of results to view.
      - name: prefix
        in: query
        required: false
        schema:
          type: string
        description: The managed folder name/path prefix to filter the output list of results.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedFolders'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/cloud-platform.read-only
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_only
        - https://www.googleapis.com/auth/devstorage.read_write
  /storage/v1/b/{bucket}/managedFolders/{managedFolder}/iam/testPermissions:
    get:
      operationId: storage.managedFolders.testIamPermissions
      tags:
      - managedFolders
      summary: Tests a set of permissions on the given managed folder to see which, if any…
      description: Tests a set of permissions on the given managed folder to see which, if any, are held by the caller.
      parameters:
      - name: bucket
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the managed folder.
      - name: managedFolder
        in: path
        required: true
        schema:
          type: string
        description: The managed folder name/path.
      - name: permissions
        in: query
        required: true
        schema:
          type: string
        description: Permissions to test.
      - name: userProject
        in: query
        required: false
        schema:
          type: string
        description: The project to be billed for this request. Required for Requester Pays buckets.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestIamPermissionsResponse'
        default:
          description: Error response
      security:
      - oauth2:
        - https://www.googleapis.com/auth/cloud-platform
        - https://www.googleapis.com/auth/cloud-platform.read-only
        - https://www.googleapis.com/auth/devstorage.full_control
        - https://www.googleapis.com/auth/devstorage.read_only
        - https://www.googleapis.com/auth/devstorage.read_write
components:
  schemas:
    Expr:
      type: object
      description: 'Represents an expression text. Example: title: "User account presence" description: "Determines whether the request has a user account" expression: "size(request.user) > 0"'
      properties:
        description:
          type: string
          description: An optional description of the expression. This is a longer text which describes the expression, e.g. when hovered over it in a UI.
        expression:
          type: string
          description: Textual representation of an expression in Common Expression Language syntax. The application context of the containing message determines which well-known feature set of CEL is supported.
        location:
          type: string
          description: An optional string indicating the location of the expression for error reporting, e.g. a file name and a position in the file.
        title:
          type: string
          description: An optional title for the expression, i.e. a short string describing its purpose. This can be used e.g. in UIs which allow to enter the expression.
    RapidCacheConfig:
      type: object
      description: Configuration options for the rapid cache of a managed folder.
      properties:
        policies:
          type: object
          description: A map of rapid cache IDs to the corresponding `RapidCachePolicy` configurations for a managed folder.
          additionalProperties:
            $ref: '#/components/schemas/RapidCachePolicy'
    ManagedFolder:
      type: object
      description: A managed folder.
      properties:
        bucket:
          type: string
          description: The name of the bucket containing this managed folder.
        id:
          type: string
          description: The ID of the managed folder, including the bucket name and managed folder name.
        kind:
          type: string
          description: The kind of item this is. For managed folders, this is always storage#managedFolder.
          default: storage#managedFolder
        metageneration:
          type: string
          description: The version of the metadata for this managed folder. Used for preconditions and for detecting changes in metadata.
          format: int64
        name:
          type: string
          description: The name of the managed folder. Required if not specified by URL parameter.
        selfLink:
          type: string
          description: The link to this managed folder.
        createTime:
          type: string
          description: The creation time of the managed folder in RFC 3339 format.
          format: date-time
        updateTime:
          type: string
          description: The last update time of the managed folder metadata in RFC 3339 format.
          format: date-time
        rapidCacheConfig:
          $ref: '#/components/schemas/RapidCacheConfig'
    RapidCachePolicy:
      type: object
      description: The rapid cache policy configuration for a managed folder.
      properties:
        rapidCacheId:
          type: string
          description: The unique identifier of the rapid cache.
        ingestOnWrite:
          type: string
          description: The ingest-on-write policy for objects in the managed folder. When set to `enabled`, objects are automatically ingested into the cache when they are written to the managed folder.
          enum:
          - enabled
          - unspecified
          x-enumDescriptions:
          - Ingestion on write is explicitly enabled for the managed folder.
          - Ingestion on write isn't specified at the managed folder level and is inherited from the parent resource's configuration. This is the default value.
    TestIamPermissionsResponse:
      type: object
      description: A storage.(buckets|objects|managedFolders).testIamPermissions response.
      properties:
        kind:
          type: string
          description: The kind of item this is.
          default: storage#testIamPermissionsResponse
        permissions:
          type: array
          description: "The permissions held by the caller. Permissions are always of the format storage.resource.capability, where resource is one of buckets, objects, or managedFolders. The supported permissions are as follows:  \n- storage.buckets.delete - Delete bucket.  \n- storage.buckets.get - Read bucket metadata.  \n- storage.buckets.getIamPolicy - Read bucket IAM policy.  \n- storage.buckets.create - Create bucket.  \n- storage.buckets.list - List buckets.  \n- storage.buckets.setIamPolicy - Update bucket IAM policy.  \n- storage.buckets.update - Update bucket metadata.  \n- storage.objects.delete - Delete object.  \n- storage.objects.get - Read object data and metadata.  \n- storage.objects.getIamPolicy - Read object IAM policy.  \n- storage.objects.create - Create object.  \n- storage.objects.list - List objects.  \n- storage.objects.setIamPolicy - Update object IAM policy.  \n- storage.objects.update - Update object metadata. \n- storage.managedFolders.delete - Delete managed folder.  \n- storage.managedFolders.get - Read managed folder metadata.  \n- storage.managedFolders.getIamPolicy - Read managed folder IAM policy.  \n- storage.managedFolders.create - Create managed folder.  \n- storage.managedFolders.list - List managed folders.  \n- storage.managedFolders.setIamPolicy - Update managed folder IAM policy."
          items:
            type: string
    ManagedFolders:
      type: object
      description: A list of managed folders.
      properties:
        items:
          type: array
          description: The list of items.
          items:
            $ref: '#/components/schemas/ManagedFolder'
        kind:
          type: string
          description: The kind of item this is. For lists of managed folders, this is always storage#managedFolders.
          default: storage#managedFolders
        nextPageToken:
          type: string
          description: The continuation token, used to page through large result sets. Provide this value in a subsequent request to return the next page of results.
    Policy:
      type: object
      description: A bucket/object/managedFolder IAM policy.
      properties:
        bindings:
          type: array
          description: An association between a role, which comes with a set of permissions, and members who may assume that role.
          items:
            type: object
            properties:
              condition:
                $ref: '#/components/schemas/Expr'
              members:
                type: array
                description: "A collection of identifiers for members who may assume the provided role. Recognized identifiers are as follows:  \n- allUsers - A special identifier that represents anyone on the internet; with or without a Google account.  \n- allAuthenticatedUsers - A special identifier that represents anyone who is authenticated with a Google account or a service account.  \n- user:emailid - An email address that represents a specific account. For example, user:alice@gmail.com or user:joe@example.com.  \n- serviceAccount:emailid - An email address that represents a service account. For example,  serviceAccount:my-other-app@appspot.gserviceaccount.com .  \n- group:emailid - An email address that represents a Google group. For example, group:admins@example.com.  \n- domain:domain - A Google Apps domain name that represents all the users of that domain. For example, domain:google.com or domain:example.com.  \n- projectOwner:projectid - Owners of the given project. For example, projectOwner:my-example-project  \n- projectEditor:projectid - Editors of the given project. For example, projectEditor:my-example-project  \n- projectViewer:projectid - Viewers of the given project. For example, projectViewer:my-example-project"
                items:
                  type: string
              role:
                type: string
                description: "The role to which members belong. Two types of roles are supported: new IAM roles, which grant permissions that do not map directly to those provided by ACLs, and legacy IAM roles, which do map directly to ACL permissions. All roles are of the format roles/storage.specificRole.\nThe new IAM roles are:  \n- roles/storage.admin - Full control of Google Cloud Storage resources.  \n- roles/storage.objectViewer - Read-Only access to Google Cloud Storage objects.  \n- roles/storage.objectCreator - Access to create objects in Google Cloud Storage.  \n- roles/storage.objectAdmin - Full control of Google Cloud Storage objects.   The legacy IAM roles are:  \n- roles/storage.legacyObjectReader - Read-only access to objects without listing. Equivalent to an ACL entry on an object with the READER role.  \n- roles/storage.legacyObjectOwner - Read/write access to existing objects without listing. Equivalent to an ACL entry on an object with the OWNER role.  \n- roles/storage.legacyBucketReader - Read access to buckets with object listing. Equivalent to an ACL entry on a bucket with the READER role.  \n- roles/storage.legacyBucketWriter - Read access to buckets with object listing/creation/deletion. Equivalent to an ACL entry on a bucket with the WRITER role.  \n- roles/storage.legacyBucketOwner - Read and write access to existing buckets with object listing/creation/deletion. Equivalent to an ACL entry on a bucket with the OWNER role."
        etag:
          type: string
          description: HTTP 1.1  Entity tag for the policy.
          format: byte
        kind:
          type: string
          description: The kind of item this is. For policies, this is always storage#policy. This field is ignored on input.
          default: storage#policy
        resourceId:
          type: string
          description: 'The ID of the resource to which this policy belongs. Will be of the form projects/_/buckets/bucket for buckets, projects/_/buckets/bucket/objects/object for objects, and projects/_/buckets/bucket/managedFolders/managedFolder. A specific generation may be specified by appending #generationNumber to the end of the object name, e.g. projects/_/buckets/my-bucket/objects/data.txt#17. The current generation can be denoted with #0. This field is ignored on input.'
        version:
          type: integer
          description: The IAM policy format version.
          format: int32
  securitySchemes:
    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/cloud-platform: View and manage your data across Google Cloud Platform services
            https://www.googleapis.com/auth/cloud-platform.read-only: View your data across Google Cloud Platform services
            https://www.googleapis.com/auth/devstorage.full_control: Manage your data and permissions in Google Cloud Storage
            https://www.googleapis.com/auth/devstorage.read_only: View your data in Google Cloud Storage
            https://www.googleapis.com/auth/devstorage.read_write: Manage your data in Google Cloud Storage