Understanding TD API URLs and TD Console URLs

A Treasure Data server supports two different URLs:

• Console URLs
• API URLs

The console URL provides access to the Treasure Data user interface. After you have logged into the console with your browser, the console URL that is displayed in the browser bar changes depending on where you have navigated to in the user interface. This is a useful feature for API users because it can help determine the IDs of certain objects in the server. For example, in the screen shot below, you can see from the console URL that the database db_test has an id of 1761984.

The API URL is location where you can also make requests of the server. This URL also changes depending on the functionality and the resource you are trying to access. For example, using the same db_test database, the API URL to query db_test is shown here:

https://api.treasuredata.com/v3/database/show/db_test

$ curl --location 'https://api.treasuredata.com/v3/database/show/db_test' --header 'Authorization: TD1 123/abcdef•••••••••••••••••••••••0123456789' | jq

{
  "id": "1761984",
  "name": "db_test",
  "created_at": "2021-12-06 17:04:47 UTC",
  "updated_at": "2021-12-06 17:04:47 UTC",
  "count": 0,
  "organization": null,
  "permission": "owner",
  "delete_protected": false,
  "datatank": false
}

The challenge API users encounter when working with Treasure Data URLs is that the base portions of the console URL and the base portion of the API URL are different—even though they point to the same server. In order to use TD APIs you have know both URLs. You have to know the API URL to make the call, and you have to know the console URL to get the API authorization key. This can be a challenge because in general usage, as well as in TD-specific usage, different terms are used to describe the components of these URLs. This figure illustrates some of the variety you may encounter in the terminology used to describe the different parts of an API URL.

In the casual day-to-day engineering language of Treasure Data, the term "endpoint" is sometimes used to describe every component of a full URL. However, this article will use the "Formal TD" terminology described above.

About TD baseURLs

This article is primarily concerned with helping you determine which baseURL for your API call corresponds to which TD Console URL. Specifically this article attempts to address the following situations:

• I have the full URL of an API. What console do I login to get a key to authenticate this API call?
• I called the full URL of an API successfully. Which console do I login to so I can see the object that I created or modified in the console?
• I created an object in the TD Console, what is the API baseURL for the endpoint paths that will let me programmatically access my object?

After you have determined the baseURL of the server you want to use in your API calls, you can then consult the other API references hosted on the Treasure Data API portal to determine the endpoint paths for specific APIs.

About TD Console Regions and URLs

There are four principal instances of the Treasure Data console that run in following geographic regions:

• United States (us01)
• Europe (eu01)
• Korea (ap02)
• Japan (ap01 or ".co.jp")

Audience Studio (Legacy) URL Format

Here is the full URL for accessing the login screen of the Audience Studio (Legacy) console in the US region:

     https://console.treasuredata.com/

Table 1 lists the full URLs of the login screens for the current consoles by region. Note that the full URLs of the TD Consoles in Europe and Korea can be derived from the US console URL by adding a region identifier after the word "console" in the full URL. For example,

     https://console.eu01.treasuredata.com
     https://console.ap02.treasuredata.com

The full URL for the TD Console hosted in the Japan region, can be derived from the US console URL by replacing ".com" with ".co.jp" in the full URL.

     https://console.treasuredata.co.jp

Audience Studio URL Format

With the introduction of the new Audience Studio console, the word "-next" was added to the full URL. For example, to login to the any v5 console, you can simply append "-next" after the word "console" in the full URL for the Audience Studio (Legacy) console. Table 1 provides a summary of console URLs.

Table 1: Console URLS by Region

TD API v3 baseURLs

Table 2 provides a mapping between console URLs and API baseURLs for the same server. Note that the baseURL for the TD API v3 can be derived from the Audience Studio (Legacy) console URL by replacing the word "console" with "api". For example, to make a call to a TD API v3 endpoint path on the US console, the baseURL for the API would be:

     [ https://api.treasuredata.com ]

Table 2: Corresponding Audience Studio (Legacy) console URLs and TD API v3 baseURLs

About Endpoints Used by the TD Toolbelt CLI

The TD Toolbelt provides a CLI wrapper for v3 TD APIs. However, it is not always obvious which console the CLI is sending API requests to. In order to determine this, inspect the td.conf file which is located by default in ~/.td/td.conf. Here is an example of a td.conf file.

[account]
endpoint = https://api.treasuredata.com
apikey = 123/abcdef•••••••••••••••••••••••0123456789
user = my.name@mycompany.com

Using the Table 2, you can convert the baseURL (e.g. [ https://api.treasuredata.com ]) to a console URL (e.g https://console.treasuredata.com). You can then log in to that console to see the effects of your CLI calls.

For additional information on specifying the baseURL for the TD Toolbelt CLI see the following:

• Configuring Your TD Endpoint using TD Toolbelt
• TD Basic Commands

Audience API baseURLs

Table 3 provides a mapping between Audience Studio console URLs and the corresponding baseURLs for Audience APIs. Note that the baseURL for the Audience API can be derived by replacing "console-next" in the Audience Studio console URL with with "api-cdp". For example, to call an Audience API on the US console, the baseURL would be:

     [ https://api-cdp.treasuredata.com ]

Table 3: Corresponding v5 console URLs and Audience API baseURLs

Other API baseURLs

The various baseURLs for TD API services are structured in a variety of ways. For example, the TD ingest API uses a console prefix in the baseURL:

     [ https://us01.records.in.treasuredata.com ]

For a list of specific API baseURLs by region see Treasure Data Sites and baseURLs.

About Treasure Data API Keys

Your TD API key contains the credentials you will need to authenticate your API calls, and these credentials are only valid on the specific console instance where they were created. Moreover, as consoles are multi-tenant systems, the API key is only valid for your account on that console instance.

In the console, API keys are comprised of an account number and a key:

     123/abcdef•••••••••••••••••••••••0123456789

In this example, the "123" is the account number, and the 40-digit hexadecimal value that follows is the actual API key. To authenticate you need to provide the full key along with the value "TD1". For example, to authenticate an API call in cURL you would specify a header that looks something like this:

--header 'Authorization: TD1 123/abcdef••••••••••••••••••••••••012345678'