TypeDB Cloud API

The TypeDB Cloud administration API can be used to perform certain actions programmatically, rather than through the TypeDB Cloud website.

To use the API, you will need a TypeDB Cloud account.

Generate an API Token

  1. Visit your team settings page, scroll to the API tokens section, and click "Generate API Token".

  2. Give your API token a descriptive name, and appropriate access to your chosen space and hit "Create token". See the API reference for detailed access level info.

  3. Once created, the token details will be displayed - save the displayed client secret.

Make sure to save the client secret somewhere safe - you will only see it when you first generate the token, and will be unable to use the token without it.

Access the API

Once you have your client ID and client secret, you will need to exchange these for a short-lived access token used to query the API.

  1. Make a POST request to https://cloud.typedb.com/api/v1/auth, with the client ID and client secret in a Basic authorization header, separated by a :.

    • curl

    • Python

    • Rust

    curl --request POST \
    --url https://cloud.typedb.com/api/v1/auth \
    --header 'Authorization: Basic {CLIENT-ID}:{CLIENT-SECRET}'
    import requests

url = "https://cloud.typedb.com/api/v1/auth"

headers = {
    "Authorization": "Basic {CLIENT-ID}:{CLIENT-SECRET}"
}

response = requests.post(url, headers=headers)
    use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .post("https://cloud.typedb.com/api/v1/auth")
        .header(reqwest::header::AUTHORIZATION, "Basic {CLIENT_ID}:{CLIENT_SECRET}")
        .send().await;
    Ok(())
}

    The response body will be your access token.

    For security, your access token will expire after 1 hour.

  2. Make an API request to list clusters in the space you selected for your API token. The example below targets the default space in an team called my-team. You will use the access token you generated in the previous step to authenticate this request.

    • curl

    • Python

    • Rust

    curl --request GET \
    --url https://cloud.typedb.com/api/v1/team/TEAM_ID/spaces/SPACE_ID/clusters \
    --header 'Authorization: Bearer {ACCESS-TOKEN}'
    import requests

url = "https://cloud.typedb.com/api/v1/team/my-team/spaces/default/clusters"

headers = {
    "Authorization": "Bearer {ACCESS-TOKEN}"
}

response = requests.get(url, headers=headers)
    use reqwest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let resp = client
        .get("https://cloud.typedb.com/api/v1/team/my-team/spaces/default/clusters")
        .header(reqwest::header::AUTHORIZATION, "Bearer {ACCESS-TOKEN}")
        .send().await;
    Ok(())
}

    It will return information about the clusters in a JSON format, as below

    [
    {
        "id":"my-cluster",
        "serverCount":1,
        "storageSizeGB":10,
        "isFree":true,
        "status":"running",
        "createdAt":1738256490070,
        "teamID":"my-team",
        "spaceID":"default",
        "version":"3.1.0",
        "provider":"gcp",
        "region":"europe-west2",
        "machineType":"c2d-highcpu-2",
        "storageType":"standard-rwo",
        "servers": [
            {
              "address": "abc123-0.cluster.typedb.com:80",
              "status": "running"
            }
        ]
    }
]

Next steps

Now that you know how to list the clusters in your space from the API, you can explore TypeDB Cloud further, either through further API use or back on the website.

TypeDB Cloud

Head back to TypeDB Cloud to keep exploring there.

TypeDB Cloud API

View the API reference for more detail on what you can do with it.

Example scripts

Look at examples of using the Cloud API in simple command-line scripts