Request endpoints

Stay organized with collections Save and categorize content based on your preferences.

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.

Typical API requests

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


  • For general JSON API requests, excluding object uploads, use the following endpoint, replacing PLACEHOLDER with the appropriate values:
  • For JSON API object uploads, use the following endpoint, replacing PLACEHOLDER with the appropriate values:
  • For batched requests, use the following endpoint, replacing PLACEHOLDER with the appropriate values:
  • Optionally, for JSON API object downloads, you can use the following endpoint, replacing PLACEHOLDER with the appropriate values:

JSON API endpoints only accept HTTPS requests.


  • 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:

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:


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.

Google Cloud console endpoints

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

Resource URL
Bucket list for a project
Object list for a bucket
Details for an object

gcloud endpoints

gcloud storage commands use JSON API endpoints. Endpoint usage is managed on your behalf by the gcloud CLI.

gsutil endpoints

gsutil manages request endpoints on your behalf, but you can control which API gsutil prefers to use. By default, gsutil accesses Cloud Storage through the JSON API and its associated endpoints. You can control this default by setting the prefer_api variable in the "GSUtil" section of the .boto config file to xml or json like so:

prefer_api = xml

While gsutil uses the preferred API where possible, if it is not possible, gsutil silently falls back to using the other API. For example, the ubla command is not supported in the XML API, so gsutil always uses the JSON API for that command. Similarly, gsutil always uses the XML API when interacting with cloud storage providers that do not support the JSON API.

gsutil considerations when using the XML API

  • You can control whether gsutil uses path-style XML API endpoints or virtual hosted-style XML API endpoints by editing the calling_format entry in the "s3" section of your .boto config file. By default, gsutil uses path-style XML API endpoints for Cloud Storage.

    • Use calling_format = boto.s3.connection.OrdinaryCallingFormat for path-style endpoints.

    • Use calling_format = boto.s3.connection.SubdomainCallingFormat for virtual hosted-style endpoints.

  • The XML API uses the boto framework. This framework re-reads downloaded files to compute an MD5 hash if one is not present. For objects that do not include MD5 hashes in their metadata, such as composite objects, this doubles the bandwidth consumed and elapsed time needed by the download. If you are working with composite objects, you should avoid setting prefer_api to xml.

  • The XML API requires separate calls to get each available object and bucket metadata field, such as each configuration set on a bucket. Using the JSON API when possible uses fewer operations and has a consequently lower cost.

Client library endpoints

Cloud Storage client libraries manage request endpoints automatically. Optionally, you can set the request endpoint manually. This can be useful when you want to use a specific endpoint, or for testing, such as when you want to use a local emulator:


For more information, see the Cloud Storage C++ API reference documentation.

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
  PerformSomeOperations(client, bucket_name, object_name);


For more information, see the Cloud Storage C# API reference documentation.

using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
        BaseUri = endpoint


For more information, see the Cloud Storage Go API reference documentation.

import (


// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := ""
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	return nil


For more information, see the Cloud Storage Java API reference documentation.


public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = ""

    Storage storage =

        "Storage Client initialized with endpoint " + storage.getOptions().getHost());


For more information, see the Cloud Storage Node.js API reference documentation.

 * TODO(developer): Uncomment the following lines before running the sample.
// The custom endpoint to which requests should be made
// const apiEndpoint = '';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);


For more information, see the Cloud Storage PHP API reference documentation.

use Google\Cloud\Storage\StorageClient;

 * Sets a custom endpoint for storage client.
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. '')
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);


For more information, see the Cloud Storage Python API reference documentation.

from import storage

def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = ''

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client


For more information, see the Cloud Storage Ruby API reference documentation.

# api_endpoint = ""

require "google/cloud/storage"

storage =
  endpoint: api_endpoint

puts "Client initiated with endpoint #{storage.service.service.root_url}"

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, not top-level domains such as

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

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

NAME                      TYPE     DATA
travel-maps               CNAME

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

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:

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

After successfully signing in, you are redirected to the desired content. The URL for this content has the following structure:

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

Access to public objects

All requests to the 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 URI documented in Direct API requests. For details and examples, see Accessing Public Data.

What's next