InfluxDB v3 Cloud Dedicated Docs Submit API issue
Documentation Powered by ReDoc

InfluxDB Cloud Dedicated Management API

License: MIT

The Management API for InfluxDB Cloud Dedicated provides a programmatic interface for managing an InfluxDB Cloud Dedicated instance.

The InfluxDB v3 Management API lets you manage an InfluxDB Cloud Dedicated instance and integrate functions such as creating and managing databases, permissions, and tokens into your workflow or application.

This documentation is generated from the InfluxDB OpenAPI specification.

Authentication

The InfluxDB Management API endpoints require the following credentials:

  • ACCOUNT_ID: The ID of the account that the cluster belongs to. To view account ID and cluster ID, list cluster details.

  • CLUSTER_ID: The ID of the cluster that you want to manage. To view account ID and cluster ID, list cluster details.

  • Authorization MANAGEMENT_TOKEN: the Authorization HTTP header with a management token.

    See how to create a management token.

    By default, management tokens in InfluxDB v3 are short-lived tokens issued by an OAuth2 identity provider that grant a specific user administrative access to your InfluxDB cluster. However, for automation purposes, you can manually create management tokens that authenticate directly with your InfluxDB cluster and do not require human interaction with your identity provider.

Database tokens

Manage database read/write tokens for a cluster

Get all database tokens for a cluster

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account to get the database tokens for

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster to get the database tokens for

Responses

Request samples

HOST="https://console.influxdata.com"

list_tokens () {
  local response=$( \
    curl \
      --location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens" \
      --header "Accept: application/json" \
      --header "Authorization: Bearer $MANAGEMENT_TOKEN" \
  )
  echo "$response"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Create a database token

Create a database token for a cluster.

The token returned on the accessToken property in the response can be used to authenticate query and write requests to the cluster.

Notable behaviors

  • InfluxDB might take some time--from a few seconds to a few minutes--to activate and synchronize new tokens. If a new database token doesn't immediately work (you receive a 401 Unauthorized error) for querying or writing, wait and then try your request again.

  • Token strings are viewable only on token creation and aren't stored by InfluxDB; you can't recover a lost token.

Store secure tokens in a secret store

We recommend storing database tokens in a secure secret store. For example, see how to authenticate Telegraf using tokens in your OS secret store.

If you lose a token, delete the token from InfluxDB and create a new one.

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account to create the database token for

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster to create the database token for

Request Body schema: application/json
description
required
string (schemas)

The description of the database token

Array of objects (schemas)

The list of permissions the database token allows

Responses

Request samples

Content type
application/json
Example
Limited Access Token
Limited Access Token
Full Access Token
No Access Token
{
  • "description": "Limited Access Token",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
Example
Limited Access Token
Limited Access Token
Full Access Token
No Access Token
{
  • "accountId": "11111111-1111-4111-8111-111111111111",
  • "clusterId": "33333333-3333-4333-8333-333333333333",
  • "id": "55555555-5555-4555-8555-555555555555",
  • "description": "Limited Access Token",
  • "permissions": [
    ],
  • "createdAt": "2023-12-21T17:32:28.000Z",
  • "accessToken": "apiv1_5555555555555555555555555555555555555555555555555555555555555555"
}

Get a database token

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account that the database token belongs to

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster that the database token belongs to

tokenId
required
string <uuid> (UuidV4)

The ID of the database token to get

Responses

Request samples

HOST="https://console.influxdata.com"

get_token () {
  local tokenId=$1
  local response=$( \
    curl \
      --location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens/$tokenId" \
      --header "Accept: application/json" \
      --header "Authorization: Bearer $MANAGEMENT_TOKEN" \
  )
  echo "$response"
}

Response samples

Content type
application/json
Example
Limited Access Token
Limited Access Token
Full Access Token
No Access Token
{
  • "accountId": "11111111-1111-4111-8111-111111111111",
  • "clusterId": "33333333-3333-4333-8333-333333333333",
  • "id": "55555555-5555-4555-8555-555555555555",
  • "description": "Limited Access Token",
  • "permissions": [
    ],
  • "createdAt": "2023-12-21T17:32:28.000Z"
}

Update a database token

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account that the database token belongs to

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster that the database token belongs to

tokenId
required
string <uuid> (UuidV4)

The ID of the database token to update

Request Body schema: application/json
description
string (schemas)

The description of the database token

Array of objects (schemas)

The list of permissions the database token allows

Responses

Request samples

Content type
application/json
Example
Update All Fields
Update All Fields
Update Description Only
Update Permissions Only
Remove All Permissions
{
  • "description": "Updated Limited Access Token",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
Example
Update All Fields
Update All Fields
Update Description Only
Update Permissions Only
Remove All Permissions
{
  • "accountId": "11111111-1111-4111-8111-111111111111",
  • "clusterId": "33333333-3333-4333-8333-333333333333",
  • "id": "55555555-5555-4555-8555-555555555555",
  • "description": "Updated Limited Access Token",
  • "permissions": [
    ],
  • "createdAt": "2023-12-21T17:32:28.000Z"
}

Delete a database token

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account that the database token belongs to

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster that the database token belongs to

tokenId
required
string <uuid> (UuidV4)

The ID of the database token to delete

Responses

Request samples

HOST="https://console.influxdata.com"

delete_token () {
  local tokenId=$1
  local response=$( \
    curl \
      --location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/tokens/$tokenId" \
      --request DELETE \
      --header "Accept: application/json" \
      --header "Authorization: Bearer $MANAGEMENT_TOKEN" \
  )
  echo "$response"
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "bad request"
}

Databases

Manage databases for a cluster

Get all databases for a cluster

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account to get the databases for

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster to get the databases for

Responses

Request samples

HOST="https://console.influxdata.com"

list_databases () {
  local response=$( \
    curl \
      --location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/databases" \
      --header "Accept: application/json" \
      --header "Authorization: Bearer $MANAGEMENT_TOKEN" \
  )
  echo "$response"
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a database

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account to create the database for

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster to create the database for

Request Body schema: application/json
maxColumnsPerTable
integer <int32> (schemas) >= 1
Default: 200

The maximum number of columns per table for the cluster database

maxTables
integer <int32> (schemas) >= 1
Default: 500

The maximum number of tables for the cluster database

name
required
string (schemas) [ 1 .. 64 ] characters

The name of the cluster database

Array of ClusterDatabasePartitionTemplatePartTagValue (object) or ClusterDatabasePartitionTemplatePartTimeFormat (object) or ClusterDatabasePartitionTemplatePartBucket (object) (schemas) [ 1 .. 8 ] items unique

A template for partitioning a cluster database.

Each template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter |.

For example, using the partition template below:

[
  {
    "type": "time",
    "value": "%Y"
  },
  {
    "type": "tag",
    "value": "bananas"
  },
  {
    "type": "tag",
    "value": "plátanos"
  },
  {
    "type": "bucket",
    "value": {
      "tagName": "c",
      "numberOfBuckets": 10
    }
  }
]

The following partition keys are derived:

  • time=2023-01-01, a=bananas, b=plátanos, c=ananas -> 2023|bananas|plátanos|5
  • time=2023-01-01, b=plátanos -> 2023|!|plátanos|!
  • time=2023-01-01, another=cat, b=plátanos -> 2023|!|plátanos|!
  • time=2023-01-01 -> 2023|!|!|!
  • time=2023-01-01, a=cat|dog, b=!, c=! -> 2023|cat%7Cdog|%21|8
  • time=2023-01-01, a=%50, c=%50 -> 2023|%2550|!|9
  • time=2023-01-01, a=, c= -> 2023|^|!|0
  • time=2023-01-01, a=<long string> -> 2023|<long string>#|!|!
  • time=2023-01-01, c=<long string> -> 2023|!|!|<bucket ID for untruncated long string>

When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [TemplatePart::Bucket] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated.

retentionPeriod
integer <int64> (schemas) >= 0
Default: 0

The retention period of the cluster database in nanoseconds, if applicable

If the retention period is not set or is set to 0, the database will have infinite retention

Responses

Request samples

Content type
application/json
Example
Required Fields Only
Required Fields Only
All Fields
{
  • "name": "DatabaseOne"
}

Response samples

Content type
application/json
Example
Required Fields Only
Required Fields Only
All Fields
{
  • "accountId": "11111111-1111-4111-8111-111111111111",
  • "clusterId": "33333333-3333-4333-8333-333333333333",
  • "name": "DatabaseOne",
  • "maxTables": 500,
  • "maxColumnsPerTable": 200,
  • "retentionPeriod": 0
}

Update a database

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account that the database belongs to

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster that the database belongs to

databaseName
required
string (ClusterDatabaseName) [ 1 .. 64 ] characters

The name of the database to update

Request Body schema: application/json
maxColumnsPerTable
integer <int32> (schemas) >= 1
Default: 200

The maximum number of columns per table for the cluster database

maxTables
integer <int32> (schemas) >= 1
Default: 500

The maximum number of tables for the cluster database

retentionPeriod
integer <int64> (schemas) >= 0
Default: 0

The retention period of the cluster database in nanoseconds, if applicable

If the retention period is not set or is set to 0, the database will have infinite retention

Responses

Request samples

Content type
application/json
Example
Update All Fields
Update All Fields
Update Max Tables Only
Update Max Columns Per Table Only
Update Retention Period Only
{
  • "maxTables": 300,
  • "maxColumnsPerTable": 150,
  • "retentionPeriod": 600000000000
}

Response samples

Content type
application/json
Example
Update All Fields
Update All Fields
Update Max Tables Only
Update Max Columns Per Table Only
Update Retention Period Only
{
  • "accountId": "11111111-1111-4111-8111-111111111111",
  • "clusterId": "33333333-3333-4333-8333-333333333333",
  • "name": "DatabaseOne",
  • "maxTables": 300,
  • "maxColumnsPerTable": 150,
  • "retentionPeriod": 600000000000
}

Delete a database

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account that the database belongs to

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster that the database belongs to

databaseName
required
string (ClusterDatabaseName) [ 1 .. 64 ] characters

The name of the database to delete

Responses

Request samples

HOST="https://console.influxdata.com"

delete_database () {
  local databaseName=$1
  local response=$( \
    curl \
      --location "$HOST/api/v0/accounts/$ACCOUNT_ID/clusters/$CLUSTER_ID/databases/$databaseName" \
      --request DELETE \
      --header "Accept: application/json" \
      --header "Authorization: Bearer $MANAGEMENT_TOKEN" \
  )
  echo "$response"
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "bad request"
}

Tables

Manage tables in a database

Create a database table

Authorizations:
bearerAuthManagementTokenbearerAuthJwt
path Parameters
accountId
required
string <uuid> (UuidV4)

The ID of the account to create the database table for

clusterId
required
string <uuid> (UuidV4)

The ID of the cluster to create the database table for

databaseName
required
string (ClusterDatabaseName) [ 1 .. 64 ] characters

The name of the database to create the database table for

Request Body schema: application/json
name
required
string (schemas) non-empty

The name of the cluster database table

Array of ClusterDatabasePartitionTemplatePartTagValue (object) or ClusterDatabasePartitionTemplatePartTimeFormat (object) or ClusterDatabasePartitionTemplatePartBucket (object) (schemas) [ 1 .. 8 ] items unique

A template for partitioning a cluster database.

Each template part is evaluated in sequence, concatinating the final partition key from the output of each part, delimited by the partition key delimiter |.

For example, using the partition template below:

[
  {
    "type": "time",
    "value": "%Y"
  },
  {
    "type": "tag",
    "value": "bananas"
  },
  {
    "type": "tag",
    "value": "plátanos"
  },
  {
    "type": "bucket",
    "value": {
      "tagName": "c",
      "numberOfBuckets": 10
    }
  }
]

The following partition keys are derived:

  • time=2023-01-01, a=bananas, b=plátanos, c=ananas -> 2023|bananas|plátanos|5
  • time=2023-01-01, b=plátanos -> 2023|!|plátanos|!
  • time=2023-01-01, another=cat, b=plátanos -> 2023|!|plátanos|!
  • time=2023-01-01 -> 2023|!|!|!
  • time=2023-01-01, a=cat|dog, b=!, c=! -> 2023|cat%7Cdog|%21|8
  • time=2023-01-01, a=%50, c=%50 -> 2023|%2550|!|9
  • time=2023-01-01, a=, c= -> 2023|^|!|0
  • time=2023-01-01, a=<long string> -> 2023|<long string>#|!|!
  • time=2023-01-01, c=<long string> -> 2023|!|!|<bucket ID for untruncated long string>

When using the default partitioning template (YYYY-MM-DD) there is no encoding necessary, as the derived partition key contains a single part, and no reserved characters. [TemplatePart::Bucket] parts by definition will always be within the part length limit and contain no restricted characters so are also not percent-encoded and/or truncated.

Responses

Request samples

Content type
application/json
Example
Required Fields Only
Required Fields Only
All Fields
{
  • "name": "TableOne"
}

Response samples

Content type
application/json
Example
Required Fields Only
Required Fields Only
All Fields
{
  • "accountId": "11111111-1111-4111-8111-111111111111",
  • "clusterId": "33333333-3333-4333-8333-333333333333",
  • "databaseName": "DatabaseOne",
  • "name": "TableOne"
}