Request endpoints

This page explains the different request endpoints (URIs) you can use to access Cloud Storage. Cloud Storage supports HTTP/1.1, HTTP/2, and HTTP/3 protocols.

Note: The Cloud Storage URIs described on this page are subject to change.

Typical API requests

When making requests directly to one of the Cloud Storage APIs, use the following URIs:

JSON API

• For general JSON API requests, excluding object uploads, use the following endpoint, replacing PLACEHOLDER with the appropriate values:

  https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

• For JSON API object uploads, use the following endpoint, replacing PLACEHOLDER with the appropriate values:

  https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

• For batched requests, use the following endpoint, replacing PLACEHOLDER with the appropriate values:

  https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

• Optionally, for JSON API object downloads, you can use the following endpoint, replacing PLACEHOLDER with the appropriate values:

  https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

JSON API endpoints only accept HTTPS requests.

Note: The www.googleapis.com endpoint is also supported for the JSON API, but storage.googleapis.com is the preferred endpoint for better performance and availability.

XML API

Important: If you intend to serve content through a browser, note that the XML API serves content from the same origin as the request endpoint. If you need to serve content from a unique origin, consider using the JSON API or Authenticated browser downloads.

• For XML API requests, you can use either the virtual hosted-style or path-style endpoint, replacing PLACEHOLDER with the appropriate values:

  Virtual hosted-style:

  https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME

  Path-style:

  https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

  Note: Virtual hosted-style endpoints cannot be used to access domain-named buckets. Use either path-style endpoints or a redirect instead.

XML API endpoints support secure sockets layer (SSL) encryption, which means you can use either HTTP or HTTPS. Using HTTPS is recommended, especially if you authenticate to Cloud Storage using OAuth 2.0.

For connections through a proxy, see the Troubleshooting topic for recommended practices.

Encoding URI path parts

In addition to general considerations for bucket naming and object naming, to ensure compatibility across Cloud Storage tools, you should encode the following characters when they appear in either the object name or query string of a request URI:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ], and space characters.

For example, if you send a JSON API GET request for the object named foo??bar in the bucket example-bucket, then your request URI should be:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

Note that not all of the listed characters must be encoded in every scenario. Additionally, encoding is typically handled for you by client libraries, such as the Cloud Storage Client Libraries, so you can pass the raw object name when using such tools.

For more information about using percent-encoded for URIs, see Section 3.3 Path in RFC 3986.

Cloud Console endpoints

When using the Cloud Console, you access different resources using the following URLs:

Resource	URL
Bucket list for a project	https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Object list for a bucket	https://console.cloud.google.com/storage/browser/BUCKET_NAME
Details for an object	https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME

Custom domains

If you own your own domain, you can map its URIs to one or more Google Cloud services, including Cloud Storage buckets. The term bucket-bound hostname is sometimes used to describe this Cloud Storage request endpoint. To connect a custom domain to a Cloud Storage bucket, you create either an A or CNAME redirect in your DNS record.

A records

When connecting a custom domain to a Cloud Storage bucket, you generally should use an A record.

• A records support HTTPS requests.
• A records can be used to send traffic coming from a single hostname to multiple buckets as well as to other Google Cloud services.
• A records do not place any restrictions on your bucket name.

The drawback to using A records is that they require additional setup and use of additional Google Cloud resources. See Setting up your load balancer and SSL certificate for a guide to using custom domains with A records.

CNAME records

When connecting a custom domain to a Cloud Storage bucket, you can use a CNAME record, but note that doing so has certain limitations:

• CNAME records only support HTTP requests.
• CNAME records can only direct traffic from a given hostname to a single bucket.
• CNAME records require the hostname and the associated bucket name to match, and you must validate your bucket name.
• CNAME records can only be used for subdomains, such as www.mydomain.com, not top-level domains such as mydomain.com.

When using CNAME records, the following URI must be added to the host name portion of your CNAME record:

c.storage.googleapis.com.

For example, say your domain is example.com, and you want to make travel maps available to your customers. You can create a bucket in Cloud Storage called travel-maps.example.com, and then create a CNAME record in DNS that redirects requests from travel-maps.example.com to the Cloud Storage URI. To do this, you publish the following CNAME record in DNS:

NAME                      TYPE     DATA
travel-maps.example.com   CNAME    c.storage.googleapis.com.

By doing this, your customers can use the following URL to access a map of Paris:

http://travel-maps.example.com/paris.jpg

Your domain registration service should have a way for you to administer your domain, including adding a CNAME resource record. For example, if you use Google Domains, instructions for adding a resource record can be found on the Google Domains Help page, in the Resource records drop-down section.

Authenticated browser downloads

Authenticated browser downloads use cookie-based authentication. Cookie-based authentication asks users to sign in to their Google account to establish their identity. The specified Google account must have appropriate permission to download the object. For example, if you are using Identity and Access Management to control access to your objects, the user's Google account should have storage.objects.viewer permission, which is granted in the Storage Object Viewer role.

To download an object using cookie-based authentication, use the following URL, replacing PLACEHOLDER with the appropriate values:

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

For example, if you shared an image london.jpg from your bucket example-maps, the URL would be:

https://storage.cloud.google.com/example-maps/london.jpg

Using HTTPS is required when performing authenticated browser downloads; attempts to use HTTP redirect to HTTPS.

Important: If you have enabled Data Access logs to track access to your objects, users cannot use authenticated browser downloads to access the objects. For more information, see the Troubleshooting topic.

Access to public objects

All requests to the storage.cloud.google.com URI require authentication. This applies even when allUsers have permission to access an object. If you want users to download anonymously accessible objects without authenticating, use the storage.googleapis.com URI documented in Direct API requests. For details and examples, see Accessing Public Data.

What's next

• Upload a file to Cloud Storage.
• Download a file from Cloud Storage.
• Host a static website.
• Learn about options to control access to your data.