Use the InfluxDB v1 HTTP API

Use the InfluxDB v1 API /write and /query endpoints with v1 workloads that you bring to InfluxDB Cloud Serverless. 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 InfluxDB Cloud Serverless 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

InfluxDB Cloud Serverless 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, InfluxDB Cloud Serverless checks that the password (p) value is an authorized API token. InfluxDB Cloud Serverless 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, InfluxDB Cloud Serverless checks that the password part of the decoded credential is an authorized API token. InfluxDB Cloud Serverless ignores the username part of the decoded credential.

Syntax

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.

Most HTTP clients provide a Basic authentication option that accepts the <username>:<password> syntax and encodes the credentials before sending the request.

Example

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

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

curl "https://cloud2.influxdata.com/query" \
  --user "any:API_TOKEN
" \
  --data-urlencode "db=DATABASE_NAME
" \
  --data-urlencode "rp=RETENTION_POLICY
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

Replace the following:

DATABASE_NAME: your InfluxDB Cloud Serverless bucket
RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
API_TOKEN: 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, InfluxDB Cloud Serverless checks that the p (password) value is an authorized API token and ignores the u (username) parameter.

Syntax

https://cloud2.influxdata.com/query/?u=any&p=API_TOKEN
https://cloud2.influxdata.com/write/?u=any&p=API_TOKEN

Example

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

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

curl --get "https://cloud2.influxdata.com/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:

DATABASE_NAME: the database
RETENTION_POLICY: the retention policy
API_TOKEN: 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

Authorization: Token API_TOKEN

Examples

Use Token to authenticate a write request:

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

curl -i "https://cloud2.influxdata.com/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:

DATABASE_NAME: the database
RETENTION_POLICY: the retention policy
API_TOKEN: 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 InfluxDB Cloud Serverless v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS.

Error examples

Invalid namespace name:

400 Bad Request

{ "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
```
400 Bad Request
```
```
{ "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.

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 InfluxDB Cloud Serverless, 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

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

InfluxDB Cloud Serverless 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:

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

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.

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.

influx CLI InfluxDB API

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

* Required

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

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:

API_TOKEN: a token that has the necessary permissions to the mapped bucket
DATABASE_NAME: the database name to map to the bucket
RETENTION_POLICY_NAME: the retention policy name to map to the bucket
BUCKET_ID: the bucket ID to map to

The output is the DBRP.

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

POST https://cloud2.influxdata.com/api/v2/dbrps

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.

curl --request POST https://cloud2.influxdata.com/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.

influx CLI InfluxDB HTTP API

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

View all DBRP mappings

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.

GET https://cloud2.influxdata.com/api/v2/dbrps

Include the following:

Request method: GET
Headers:
- Authorization: Token scheme with your token that has the necessary permissions to the mapped bucket
Query parameters: * Required
- * 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)

View all DBRP mappings

curl --request GET \
  https://cloud2.influxdata.com/api/v2/dbrps \
  --header "Authorization: Token API_TOKEN
" \
  --data-urlencode "orgID=ORG_ID
"

Filter DBRP mappings by database

curl --request GET \
  https://cloud2.influxdata.com/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://cloud2.influxdata.com/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.

influx CLI InfluxDB HTTP API

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

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

Replace the following:

API_TOKEN: a token that has the necessary permissions to the mapped bucket
DBRP_ID: the DBRP ID to update
RETENTION_POLICY_NAME: 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.

PATCH https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}

Include the following:

* Required

Request method: PATCH
Headers:
- * the Authorization: Token scheme with a token that has the necessary permissions to the mapped bucket
Path parameters:
- * id: the DBRP mapping ID to update
Query parameters:
- * 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

curl --request PATCH \
  https://cloud2.influxdata.com/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:

API_TOKEN: a token that has the necessary permissions to the mapped bucket
DBRP_ID: the DBRP ID to update
RETENTION_POLICY_NAME: a retention policy name to map to the bucket

The output is the DBRP.

Delete a DBRP mapping

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

influx CLI InfluxDB API

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

* Required

* a token that has the necessary permissions to the mapped bucket
* 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.

DELETE https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}

Include the following:

* Required

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

curl --request DELETE \
  https://cloud2.influxdata.com/api/v2/dbrps/DBRP_ID
 \
  --header "Authorization: Token API_TOKEN
" \
  --data-urlencode "orgID=ORG_ID
"

Replace the following:

API_TOKEN: a token that has the necessary permissions to the mapped bucket
DBRP_ID: the DBRP ID to update
ORG_ID: the organization ID

Write data

See how to use the InfluxDB Cloud Serverless HTTP write API for InfluxDB v1 or v1.x-compatibility workloads.

Query data

See how to use the InfluxDB Cloud Serverless HTTP query API for InfluxDB v1 or v1.x-compatibility workloads.

Bucket management with InfluxQL (not supported)

InfluxDB Cloud Serverless doesn’t allow InfluxQL commands for managing or modifying buckets. You can’t use the following InfluxQL commands:

SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL

Was this page helpful?

Thank you for your feedback!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB Cloud Serverless and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support.

Edit this page Submit docs issue Submit InfluxDB Cloud Serverless issue

Use the InfluxDB v1 HTTP API

Authenticate API requests

Authenticate with a username and password scheme

Basic authentication

Syntax

Example

Query string authentication

Syntax

Example

Authenticate with a token scheme

Syntax

Examples

Responses

Error examples

Map v1 databases and retention policies to buckets

Required permissions

Permission required to create mapped buckets

Default DBRP

Automatic DBRP mapping

Name syntax for mapped buckets

Bucket naming examples

Manage DBRPs

Create DBRP mappings

A DBRP combination can only be mapped to a single bucket

List DBRP mappings

View all DBRP mappings

Filter DBRP mappings by database

Filter DBRP mappings by bucket ID

View all DBRP mappings

Filter DBRP mappings by database

Filter DBRP mappings by bucket ID

Update a DBRP mapping

Update the default retention policy

Update the default retention policy

Delete a DBRP mapping

Write data

Query data

Bucket management with InfluxQL (not supported)

Related

Support and feedback

Select your InfluxDB Cloud Serverless region

AWS

Thank you for your feedback!

New in InfluxDB 3.5

InfluxDB Docker latest tag changing to InfluxDB 3 Core

InfluxDB Cloud Serverless