Documentation

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

InfluxDB Cloud Serverless requires each API request to be authenticated with an API token. With the InfluxDB v1 API, 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

With the InfluxDB v1 API, 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

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 "":"
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:

Authenticate with a token scheme

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

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:

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.

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.

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 namev1 Retention Policy nameBucket name
dbrpdb/rp
telegrafautogentelegraf/autogen
webmetrics1w-downsampledwebmetrics/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.

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

* Required

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
  • 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:

  • 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.

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:
  • 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.

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

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
  • 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:
  • Path parameters:
    • * id: the DBRP mapping ID to update
  • Query parameters:
  • 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
  • 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.

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

* Required

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

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:

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!


Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

InfluxDB Cloud Serverless