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
- DefaultObjectAccessControls
- Folders
- ManagedFolders
- Notifications
- ObjectAccessControls
- Objects
- Operations
- Projects.hmacKeys
- Projects.serviceAccount
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. |
| restore | POST /b/BUCKET/restore |
Restores a soft-deleted bucket. |
| 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 |
Concatenates a list of existing objects into a new object in the same bucket. |
| copy | POST /b/SOURCE_BUCKET/o/SOURCE_OBJECT/copyTo |
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 |
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. |