Overview of resources and methods for the JSON API

This guide contains technical reference information for the Cloud Storage JSON API. Like the XML API, it is RESTful, but it has slightly different URI endpoints and request syntax, and is specifically intended to be used with the Google Cloud Client Libraries.

This API reference is organized by resource type. Each resource type has one or more data representations and one or more methods.

URIs are relative to https://storage.googleapis.com/storage/v1, unless otherwise noted.

Resource types

BucketAccessControls

For BucketAccessControls Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET/acl/ENTITY Permanently deletes the ACL entry for the specified entity on the specified bucket.
get GET /b/BUCKET/acl/ENTITY Returns the ACL entry for the specified entity on the specified bucket.
insert POST /b/BUCKET/acl Creates a new ACL entry on the specified bucket.
list GET /b/BUCKET/acl Retrieves ACL entries on a specified bucket.
patch PATCH /b/BUCKET/acl/ENTITY Updates an ACL entry on the specified bucket. This method supports patch semantics.
update PUT /b/BUCKET/acl/ENTITY Updates an ACL entry on the specified bucket.

Buckets

For Buckets Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET Permanently deletes an empty bucket.
get GET /b/BUCKET Returns metadata for the specified bucket.
getIamPolicy GET /b/BUCKET/iam Returns an IAM policy for the specified bucket.
insert POST /b Creates a new bucket.
Required query parameters: project
list GET /b Retrieves a list of buckets for a given project.
Required query parameters: project
listChannels GET /b/BUCKET/channels Retrieves a list of active Object Change Notification channels for a bucket.
lockRetentionPolicy POST /b/BUCKET/lockRetentionPolicy Irreversibly sets the retention policy on a bucket.
Required query parameters: ifMetagenerationMatch
patch PATCH /b/BUCKET Updates 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.
setIamPolicy PUT /b/BUCKET/iam Updates an IAM policy for the specified bucket.
testIamPermissions GET /b/BUCKET/iam/testPermissions Tests a set of permissions on the given bucket to see which, if any, are held by the caller.
Required query parameters: permissions
update PUT /b/BUCKET Updates a bucket. Changes to the bucket will be readable immediately after writing, but configuration changes may take time to propagate. This method sets the complete metadata of a bucket. If you want to change some of a bucket's metadata while leaving other parts unaffected, use the PATCH method instead.

Channels

For Channels Resource details, see the resource representation page.

Method HTTP request Description
stop POST /channels/stop Stop receiving object change notifications through this channel.

DefaultObjectAccessControls

For DefaultObjectAccessControls Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET/defaultObjectAcl/ENTITY Permanently deletes the default object ACL entry for the specified entity on the specified bucket.
get GET /b/BUCKET/defaultObjectAcl/ENTITY Returns the default object ACL entry for the specified entity on the specified bucket.
insert POST /b/BUCKET/defaultObjectAcl Creates a new default object ACL entry on the specified bucket.
list GET /b/BUCKET/defaultObjectAcl Retrieves default object ACL entries on the specified bucket.
patch PATCH /b/BUCKET/defaultObjectAcl/ENTITY Updates a default object ACL entry on the specified bucket. This method supports patch semantics.
update PUT /b/BUCKET/defaultObjectAcl/ENTITY Updates a default object ACL entry on the specified bucket.

Folders

For Folders Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET/folders/FOLDER Permanently deletes an empty folder.
get GET /b/BUCKET/folders/FOLDER Returns metadata for the specified folder.
insert POST /b/BUCKET/folders Creates a new folder.
list GET /b/BUCKET/folders Retrieves a list of folders in a given bucket.
rename POST /b/BUCKET/folders/SOURCE_FOLDER/renameTo/folders/DESTINATION_FOLDER Renames a folder in a given bucket.

ManagedFolders

For ManagedFolders Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET/managedFolders/MANAGED_FOLDER Permanently deletes a managed folder.
get GET /b/BUCKET/managedFolders/MANAGED_FOLDER Returns metadata for the specified managed folder.
getIamPolicy GET /b/BUCKET/managedFolders/MANAGED_FOLDER/iam Returns an IAM policy for the specified managed folder.
insert POST /b/BUCKET/managedFolders Creates a new managed folder.
list GET /b/BUCKET/managedFolders Retrieves a list of managed folders in a given bucket.
setIamPolicy PUT /b/BUCKET/managedFolders/MANAGED_FOLDER/iam Updates an IAM policy for the specified managed folder.
testIamPermissions GET /b/BUCKET/managedFolders/MANAGED_FOLDER/iam/testPermissions Tests a set of permissions on the given managed folder. to see which, if any, are held by the caller.

Notifications

For Notifications Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET/notificationConfigs/NOTIFICATION Permanently deletes a notification subscription.
get GET /b/BUCKET/notificationConfigs/NOTIFICATION View a notification configuration.
insert POST /b/BUCKET/notificationConfigs Creates a notification subscription for a given bucket.
list GET /b/BUCKET/notificationConfigs Retrieves a list of notification subscriptions for a given bucket.

ObjectAccessControls

For ObjectAccessControls Resource details, see the resource representation page.

Method HTTP request Description
delete DELETE /b/BUCKET/o/OBJECT/acl/ENTITY Permanently deletes the ACL entry for the specified entity on the specified object.
get GET /b/BUCKET/o/OBJECT/acl/ENTITY Returns the ACL entry for the specified entity on the specified object.
insert POST /b/BUCKET/o/OBJECT/acl Creates a new ACL entry on the specified object.
list GET /b/BUCKET/o/OBJECT/acl Retrieves ACL entries on the specified object.
patch PATCH /b/BUCKET/o/OBJECT/acl/ENTITY Updates an ACL entry on the specified object. This method supports patch semantics.
update PUT /b/BUCKET/o/OBJECT/acl/ENTITY Updates an ACL entry on the specified object.

Objects

For Objects Resource details, see the resource representation page.

Method HTTP request Description
compose POST /b/BUCKET/o/DESTINATION_OBJECT/compose Concatenates a list of existing objects into a new object in the same bucket.
copy POST /b/SOURCE_BUCKET/o/SOURCE_OBJECT/copyTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT Copies a source object to a destination object. Optionally overrides metadata.
delete DELETE /b/BUCKET/o/OBJECT Deletes an object and its metadata. Deletions are permanent if versioning is not enabled for the bucket, or if the generation parameter is used.
get GET /b/BUCKET/o/OBJECT Retrieves an object or its metadata.
insert POST https://storage.googleapis.com/upload/storage/v1/b/BUCKET/o and POST /b/BUCKET/o Stores a new object and metadata. This method supports simple, multipart, and resumable upload types. For more information, see Uploads and downloads.
list GET /b/BUCKET/o Retrieves a list of objects matching the criteria.
patch PATCH /b/BUCKET/o/OBJECT Updates a data blob's associated metadata. This method supports patch semantics.
rewrite POST /b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT Rewrites a source object to a destination object. Optionally overrides metadata.
update PUT /b/BUCKET/o/OBJECT Updates an object's metadata.
watchAll POST /b/BUCKET/o/watch Watches for changes on all objects in a bucket.

Operations

For Operations Resource details, see the resource representation page.

Method HTTP request Description
cancel POST /b/BUCKET/operations/OPERATION_ID/cancel Cancels a long-running operation.
get GET /b/BUCKET/operations/OPERATION_ID Gets a long-running operation.
list GET /b/BUCKET/operations Lists long-running operations.

Projects.hmacKeys

For Projects.hmacKeys Resource details, see the resource representation page.

Method HTTP request Description
create POST /projects/PROJECT_IDENTIFIER/hmacKeys Creates a new HMAC key for the specified service account.
Required query parameters: serviceAccountEmail
delete DELETE /projects/PROJECT_IDENTIFIER/hmacKeys/ACCESS_ID Deletes an HMAC key.
get GET /projects/PROJECT_IDENTIFIER/hmacKeys/ACCESS_ID Retrieves an HMAC key's metadata.
list GET /projects/PROJECT_IDENTIFIER/hmacKeys Retrieves a list of HMAC keys matching the criteria.
update PUT /projects/PROJECT_IDENTIFIER/hmacKeys/ACCESS_ID Updates the state of an HMAC key.

Projects.serviceAccount

For Projects.serviceAccount Resource details, see the resource representation page.

Method HTTP request Description
get GET /projects/PROJECT_IDENTIFIER/serviceAccount Get the email address of this project's Cloud Storage service agent.