Use the InfluxDB v1 HTTP API - Influxdb

Use the InfluxDB v1 API /write and /query endpoints with v1 workloads that you bring to {{% product-name %}}. The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code.

Learn how to authenticate requests, map databases and retention policies to buckets, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an {{% product-name %}} database.

Authenticate API requests
- Authenticate with a username and password scheme
- Authenticate with a token scheme
Responses
- Error examples
Map v1 databases and retention policies to buckets
Write data
Query data
Bucket management with InfluxQL (not supported)

Authenticate API requests

{{% product-name %}} requires each API request to be authenticated with an API token. With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use API tokens in InfluxDB 1.x username and password schemes or in the InfluxDB v2 Authorization: Token scheme.

Authenticate with a username and password scheme
Authenticate with a token scheme

Authenticate with a username and password scheme

With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate bucket reads and writes by passing an API token as the password credential. When authenticating requests to the v1 API /write and /query endpoints, {{% product-name %}} checks that the password (p) value is an authorized API token. {{% product-name %}} ignores the username (u) parameter in the request.

Use one of the following authentication schemes with clients that support Basic authentication or query parameters (that don't support token authentication):

Basic authentication
Query string authentication

Basic authentication

Use the Authorization header with the Basic scheme to authenticate v1 API /write and /query requests. When authenticating requests, {{% product-name %}} checks that the password part of the decoded credential is an authorized API token. {{% product-name %}} ignores the username part of the decoded credential.

Syntax

http

Authorization: Basic <base64-encoded [USERNAME]:API_TOKEN>

Encode the [USERNAME]:DATABASE_TOKEN credential using base64 encoding, and then append the encoded string to the Authorization: Basic header.

Example

The following example shows how to use cURL with the Basic authentication scheme and a token:

{{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}}

#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################

curl "https://{{< influxdb/host >}}/query" \
  --user "any:API_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "rp=RETENTION_POLICY" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

Replace the following:

{{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: your {{% product-name %}} bucket
{{% code-placeholder-key %}}RETENTION_POLICY{{% /code-placeholder-key %}}: your {{% product-name %}} retention policy
{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token with sufficient permissions to the mapped bucket

Query string authentication

In the URL, pass the p query parameter to authenticate /write and /query requests. When authenticating requests, {{% product-name %}} checks that the p (password) value is an authorized API token and ignores the u (username) parameter.

Syntax

http

https://{{< influxdb/host >}}/query/?u=any&p=API_TOKEN
https://{{< influxdb/host >}}/write/?u=any&p=API_TOKEN

Example

The following example shows how to use cURL with query string authentication and a token.

{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}

#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 API
#######################################

curl --get "https://{{< influxdb/host >}}/query" \
  --data-urlencode "p=API_TOKEN" \
  --data-urlencode "db=DATABASE_NAME" \
  --data-urlencode "rp=RETENTION_POLICY" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

Replace the following:

{{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the database
{{% code-placeholder-key %}}RETENTION_POLICY{{% /code-placeholder-key %}}: the retention policy
{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token with sufficient permissions to the mapped bucket

Authenticate with a token scheme

Use the Authorization: Token scheme to pass a token for authenticating v1 API /write and /query requests.

Include the word Token, a space, and your token value (all case-sensitive).

Syntax

http

Authorization: Token API_TOKEN

Examples

Use Token to authenticate a write request:

{{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}}

########################################################
# Use the Token authorization scheme with v1 /write
# to write data.
########################################################

curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=ms" \
    --header "Authorization: Token API_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1682358973500'

Replace the following:

{{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the database
{{% code-placeholder-key %}}RETENTION_POLICY{{% /code-placeholder-key %}}: the retention policy
{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token with sufficient permissions to the mapped bucket

Responses

InfluxDB HTTP API responses use standard HTTP status codes. The response body for partial writes and errors contains a JSON object with code and message properties that describe the error. Response body messages may differ across {{% product-name %}} v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.

Error examples

Invalid namespace name:
http
```
400 Bad Request
```
json
```
{ "code":"invalid",
  "message":"namespace name length must be between 1 and 64 characters"
}
```
The ?db= parameter value is missing in the request. Provide the DBRP database name.
Failed to deserialize db/rp/precision
http
```
400 Bad Request
```
json
```
{ "code": "invalid",
  "message": "failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`"
}
```
The ?precision= parameter contains an unknown value. Provide a [timestamp precision]/influxdb3/cloud-serverless/reference/glossary/#timestamp-precision).

Map v1 databases and retention policies to buckets

Before you can write data using the InfluxDB v1 /write endpoint or query data using the v1 /query endpoint, the bucket must be mapped to a database retention policy (DBRP) combination.

[!Note] To query using Flight with InfluxQL or SQL, you don't need to map DBRPs to buckets.

In InfluxDB 1.x, data is stored in databases and retention policies. In {{% product-name %}}, the concepts of database and retention policy have been merged into buckets, where buckets have a retention period, but retention policies are no longer part of the data model.

InfluxDB can automatically map buckets to DBRPs for you or you can manage DBRP mappings yourself using the influx v1 dbrp CLI commands or the InfluxDB v2 API /api/v2/dbrps endpoints.

Authenticate API requests
- Authenticate with a username and password scheme
- Authenticate with a token scheme
Responses
- Error examples
Map v1 databases and retention policies to buckets
Write data
Query data
Bucket management with InfluxQL (not supported)

Required permissions

Managing DBRP mappings requires a token with the necessary permissions.

write dbrp: to create (automatically or manually), update, or delete DBRP mappings.
read dbrp: to list DBRP mappings
write bucket: to automatically create a bucket for a DBRP mapping when using the v1 write API

[!Note]

Permission required to create mapped buckets

If you use the v1 write API to write to a database (db) and retention policy (rp) combination that doesn't exist, InfluxDB tries to create a new bucket using the specified parameter values. If the token doesn't have permission to create a bucket, then the write request fails with an authorization error.

Default DBRP

Each unique database name in DBRP mappings has a default mapping (the default property is equal to true). If you send a request to the v1 /write or v1 /query endpoint and don't specify a retention policy name (rp=), then InfluxDB uses the database's default DBRP mapping to determine the bucket.

Automatic DBRP mapping

{{< product-name >}} automatically creates DBRP mappings for you during the following operations:

For InfluxDB to automatically create DBRP mappings and buckets, you must use a token that has write permissions for DBRPs and buckets.

Auto-generated buckets use the name syntax for mapped buckets and a default retention period equal to the bucket's created date minus 3 days. To set a bucket's retention period, see how to update a bucket.

Name syntax for mapped buckets

InfluxDB uses the following naming convention to map database and retention policy names to bucket names:

text

DATABASE_NAME/RETENTION_POLICY_NAME

Bucket naming examples

v1 Database name	v1 Retention Policy name	Bucket name
db	rp	db/rp
telegraf	autogen	telegraf/autogen
webmetrics	1w-downsampled	webmetrics/1w-downsampled

[!Note] To avoid having to add configuration parameters to each CLI command, set up an active InfluxDB configuration.

Manage DBRPs

Create DBRP mappings

To create DBRP mappings, use the influx CLI or the InfluxDB HTTP API.

[!Note]

A DBRP combination can only be mapped to a single bucket

Each unique DBRP combination can only be mapped to a single bucket. If you map a DBRP combination that is already mapped to another bucket, it overwrites the existing DBRP mapping.

{{< tabs-wrapper >}} {{% tabs %}} influx CLI InfluxDB API {{% /tabs %}} {{% tab-content %}}

Use the influx v1 dbrp create command to map a database and retention policy to a bucket. Include the following:

{{< req "*" >}} a token that has the necessary permissions to the mapped bucket.
{{< req "*" >}} the database name to map
{{< req "*" >}} the retention policy name to map
{{< req "*" >}} the bucket ID to map to
Default flag to set the provided retention policy as the default DBRP mapping for the database.

{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API)_(NAME|TOKEN|ID)" %}}

influx v1 dbrp create \
  --token API_TOKEN \
  --org ORG_ID \
  --db DATABASE_NAME \
  --rp RETENTION_POLICY_NAME \
  --bucket-id BUCKET_ID \
  --default

Replace the following:

{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token that has the necessary permissions to the mapped bucket
{{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the database name to map to the bucket
{{% code-placeholder-key %}}RETENTION_POLICY_NAME{{% /code-placeholder-key %}}: the retention policy name to map to the bucket
{{% code-placeholder-key %}}BUCKET_ID{{% /code-placeholder-key %}}: the bucket ID to map to

The output is the DBRP.

Use the /api/v2/dbrps API endpoint to create a new DBRP mapping.

{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps" method="POST" api-ref="/influxdb3/cloud-serverless/api/#operation/PostDBRP" >}}

Include the following:

Request method: POST
Headers:
- Authorization: Token scheme with a token that has the necessary permissions to the mapped bucket
- Content-type: application/json
Request body: JSON object with the following fields:
- bucketID: the bucket ID to map to
- database: the database name to map to the bucket
- org or orgID: your organization name or organization ID
- retention_policy: the retention policy name to map to the bucket
- Optional: default: true sets the database name's default DBRP mapping.

{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}

curl --request POST https://{{< influxdb/host >}}/api/v2/dbrps \
  --header "Authorization: Token API_TOKEN" \
  --header 'Content-type: application/json' \
  --data '{
        "bucketID": "BUCKET_ID",
        "database": "DATABASE_NAME",
        "default": true,
        "orgID": "ORG_ID",
        "retention_policy": "RETENTION_POLICY_NAME"
      }'

If successful, the response status code is 201: Created and the response body contains the DBRP.

List DBRP mappings

Use the influx CLI or the InfluxDB HTTP API to list all DBRP mappings and verify that the buckets you want to query are mapped to a database and retention policy.

{{< tabs-wrapper >}} {{% tabs %}} influx CLI InfluxDB HTTP API {{% /tabs %}} {{% tab-content %}}

Use the influx v1 dbrp list command to list DBRP mappings.

View all DBRP mappings

{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}

influx v1 dbrp list --token API_TOKEN --org ORG_ID \

Filter DBRP mappings by database

influx v1 dbrp list \
  --token API_TOKEN \
  --org ORG_ID \
  --db DATABASE_NAME

Filter DBRP mappings by bucket ID

influx v1 dbrp list \
  --token API_TOKEN \
  --org ORG_ID \
  --bucket-id BUCKET_ID

Use the /api/v2/dbrps API endpoint to list DBRP mappings.

{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps" method="GET" api-ref="/influxdb3/cloud-serverless/api/#operation/GetDBRPs" >}}

Include the following:

Request method: GET
Headers:
- Authorization: Token scheme with your token that has the necessary permissions to the mapped bucket
Query parameters: {{< req type="key" >}}
- {{< req "*" >}} orgID: your organization ID
- bucketID: a bucket ID (to list DBRP mappings for a specific bucket)
- database: a database name (to list DBRP mappings with a specific database name)
- rp: a retention policy name (to list DBRP mappings with a specific retention policy name)
- id: a DBRP mapping ID (to list a specific DBRP mapping)

{{% code-placeholders "(DATABASE|RETENTION_POLICY|BUCKET|API|ORG)_(NAME|TOKEN|ID)" %}}

View all DBRP mappings

curl --request GET \
  https://{{< influxdb/host >}}/api/v2/dbrps \
  --header "Authorization: Token API_TOKEN" \
  --data-urlencode "orgID=ORG_ID"

Filter DBRP mappings by database

curl --request GET \
  https://{{< influxdb/host >}}/api/v2/dbrps \
  --header "Authorization: Token API_TOKEN" \
  --data-urlencode "orgID=ORG_ID" \
  --data-urlencode  "db=DATABASE_NAME"

Filter DBRP mappings by bucket ID

curl --request GET \
  https://{{< influxdb/host >}}/api/v2/dbrps \
  --header "Authorization: Token API_TOKEN" \
  --data-urlencode "orgID=ORG_ID" \
  --data-urlencode  "bucketID=BUCKET_ID"

Update a DBRP mapping

Use the influx CLI or the InfluxDB HTTP API to update a DBRP mapping--for example, to change the retention policy name or set the mapping as the default for the database name.

{{< tabs-wrapper >}} {{% tabs %}} influx CLI InfluxDB HTTP API {{% /tabs %}} {{% tab-content %}}

Use the influx v1 dbrp update command to update a DBRP mapping. Include the following:

a token that has the necessary permissions to the mapped bucket
DBRP mapping ID to update
Optional: Retention policy name to update to
Optional: Default flag to set the retention policy as the default DBRP mapping for the database name.

Update the default retention policy

{{% code-placeholders "(DBRP|RETENTION_POLICY|API|ORG)_(NAME|TOKEN|ID)" %}}

influx v1 dbrp update \
  --token API_TOKEN \
  --org ORG_ID \
  --id DBRP_ID \
  --rp RETENTION_POLICY_NAME \
  --default

Replace the following:

{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token that has the necessary permissions to the mapped bucket
{{% code-placeholder-key %}}DBRP_ID{{% /code-placeholder-key %}}: the DBRP ID to update
{{% code-placeholder-key %}}RETENTION_POLICY_NAME{{% /code-placeholder-key %}}: a retention policy name to map to the bucket

The output is the DBRP.

Use the /api/v2/dbrps/{dbrpID} API endpoint to update DBRP mappings.

{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps/{dbrpID}" method="PATCH" api-ref="/influxdb3/cloud-serverless/api/#operation/PatchDBRPID" >}}

Include the following:

Request method: PATCH
Headers:
- {{< req "*" >}} the Authorization: Token scheme with a token that has the necessary permissions to the mapped bucket
Path parameters:
- {{< req "*" >}} id: the DBRP mapping ID to update
Query parameters:
- {{< req "*" >}} orgID: your organization ID
Request body (JSON):
- rp: retention policy name to update to
- default: set the retention policy as the default DBRP mapping for the database name

Update the default retention policy

{{% code-placeholders "(DBRP|RETENTION_POLICY|API|ORG)_(NAME|TOKEN|ID)" %}}

curl --request PATCH \
  https://{{< influxdb/host >}}/api/v2/dbrps/DBRP_ID \
  --header "Authorization: Token API_TOKEN" \
  --data-urlencode "orgID=ORG_ID" \
  --data '{
      "rp": "RETENTION_POLICY_NAME",
      "default": true
    }'

Replace the following:

{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token that has the necessary permissions to the mapped bucket
{{% code-placeholder-key %}}DBRP_ID{{% /code-placeholder-key %}}: the DBRP ID to update
{{% code-placeholder-key %}}RETENTION_POLICY_NAME{{% /code-placeholder-key %}}: a retention policy name to map to the bucket

The output is the DBRP. {{% /tab-content %}} {{% /tabs-wrapper %}}

Delete a DBRP mapping

Use the influx CLI or the InfluxDB API to delete a DBRP mapping.

{{< tabs-wrapper >}} {{% tabs %}} influx CLI InfluxDB API {{% /tabs %}} {{% tab-content %}}

Use the influx v1 dbrp delete command to delete a DBRP mapping. Include the following:

{{< req "*" >}} a token that has the necessary permissions to the mapped bucket
{{< req "*" >}} DBRP mapping ID to delete

influx v1 dbrp delete \
  --token API_TOKEN \
  --org ORG_ID \
  --id DBRP_ID

The output is the DBRP.

Use the /api/v2/dbrps/{dbrpID} API endpoint to delete a DBRP mapping.

{{< api-endpoint endpoint="https://{{< influxdb/host >}}/api/v2/dbrps/{dbrpID}" method="DELETE" api-ref="/influxdb3/cloud-serverless/api/#operation/DeleteDBRPID" >}}

Include the following:

Request method: DELETE
Headers:
- {{< req "*" >}} the Authorization: Token scheme with a token that has the necessary permissions to the mapped bucket
Path parameters:
- {{< req "*" >}} id: DBRP mapping ID to update
Query parameters:
- {{< req "*" >}} orgID: organization ID

curl --request DELETE \
  https://{{< influxdb/host >}}/api/v2/dbrps/DBRP_ID \
  --header "Authorization: Token API_TOKEN" \
  --data-urlencode "orgID=ORG_ID"

Replace the following:

{{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}}: a token that has the necessary permissions to the mapped bucket
{{% code-placeholder-key %}}DBRP_ID{{% /code-placeholder-key %}}: the DBRP ID to update
{{% code-placeholder-key %}}ORG_ID{{% /code-placeholder-key %}}: the organization ID

Write data

See how to use the {{% product-name %}} HTTP write API for InfluxDB v1 or v1.x-compatibility workloads.

Query data

See how to use the {{% product-name %}} HTTP query API for InfluxDB v1 or v1.x-compatibility workloads.

Bucket management with InfluxQL (not supported)

{{% product-name %}} doesn't allow InfluxQL commands for managing or modifying buckets. You can't use the following InfluxQL commands:

sql

SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL