--- title: Use the InfluxDB v1 HTTP API description: Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Serverless. url: https://docs.influxdata.com/influxdb3/cloud-serverless/guides/api-compatibility/v1/ estimated_tokens: 14302 product: InfluxDB Cloud Serverless version: cloud-serverless --- # 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-api-requests) - [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) - [Authenticate with a token scheme](#authenticate-with-a-token-scheme) - [Responses](#responses) - [Error examples](#error-examples) - [Map v1 databases and retention policies to buckets](#map-v1-databases-and-retention-policies-to-buckets) - [Required permissions](#required-permissions) - [Default DBRP](#default-dbrp) - [Automatic DBRP mapping](#automatic-dbrp-mapping) - [Manage DBRPs](#manage-dbrps) - [Write data](#write-data) - [Query data](#query-data) - [Bucket management with InfluxQL (not supported)](#bucket-management-with-influxql-not-supported) ## Authenticate API requests InfluxDB Cloud Serverless requires each API request to be authenticated with an [API token](/influxdb3/cloud-serverless/admin/tokens/). 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-username-and-password-scheme) - [Authenticate with a token 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](/influxdb3/cloud-serverless/admin/tokens/) 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](/influxdb3/cloud-serverless/admin/tokens/). 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](#authenticate-with-a-token-scheme)): - [Basic authentication](#basic-authentication) - [Query string 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](/influxdb3/cloud-serverless/admin/tokens/). InfluxDB Cloud Serverless ignores the `username` part of the decoded credential. ##### Syntax ```http Authorization: Basic ``` 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 `:` 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](/influxdb3/cloud-serverless/admin/tokens/): ```sh ####################################### # 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](/influxdb3/cloud-serverless/admin/buckets/) - `RETENTION_POLICY`: your InfluxDB Cloud Serverless retention policy - `API_TOKEN`: a [token](/influxdb3/cloud-serverless/admin/tokens/) 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 ```http 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](/influxdb3/cloud-serverless/admin/tokens/). ```sh ####################################### # 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](#map-v1-databases-and-retention-policies-to-buckets) - `RETENTION_POLICY`: the [retention policy](#map-v1-databases-and-retention-policies-to-buckets) - `API_TOKEN`: a [token](/influxdb3/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket ### Authenticate with a token scheme Use the `Authorization: Token` scheme to pass a [token](/influxdb3/cloud-serverless/admin/tokens/) 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: ```sh ######################################################## # 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](#map-v1-databases-and-retention-policies-to-buckets) - `RETENTION_POLICY`: the [retention policy](#map-v1-databases-and-retention-policies-to-buckets) - `API_TOKEN`: a [token](/influxdb3/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket ## Responses InfluxDB HTTP API responses use standard [HTTP status codes](/influxdb3/cloud-serverless/api/response-codes/). The response body for [partial writes](/influxdb3/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points) 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**: ```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](#map-v1-databases-and-retention-policies-to-buckets). - **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)](/influxdb3/cloud-serverless/admin/dbrps/) 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](/influxdb3/cloud-serverless/reference/glossary/#database) and [retention policies](/influxdb3/cloud-serverless/reference/glossary/#retention-period). In InfluxDB Cloud Serverless, the concepts of database and retention policy have been merged into *buckets*, where buckets have a [retention period](/influxdb3/cloud-serverless/reference/glossary/#retention-period), but retention policies are no longer part of the data model. InfluxDB can [automatically map buckets to DBRPs](#automatic-dbrp-mapping) for you or you can [manage DBRP mappings](#manage-dbrps) yourself using the `influx v1 dbrp` CLI commands or the InfluxDB v2 API `/api/v2/dbrps` endpoints. - [Authenticate API requests](#authenticate-api-requests) - [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) - [Authenticate with a token scheme](#authenticate-with-a-token-scheme) - [Responses](#responses) - [Error examples](#error-examples) - [Map v1 databases and retention policies to buckets](#map-v1-databases-and-retention-policies-to-buckets) - [Required permissions](#required-permissions) - [Default DBRP](#default-dbrp) - [Automatic DBRP mapping](#automatic-dbrp-mapping) - [Manage DBRPs](#manage-dbrps) - [Write data](#write-data) - [Query data](#query-data) - [Bucket management with InfluxQL (not supported)](#bucket-management-with-influxql-not-supported) ### Required permissions Managing DBRP mappings requires a [token](/influxdb3/cloud-serverless/admin/tokens/) 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: - [Writing to the v1 `/write` endpoint](/influxdb3/cloud-serverless/write-data/api/v1-http/) - [Migrating from InfluxDB 1.x to InfluxDB Cloud Serverless](/influxdb3/cloud-serverless/guides/migrate-data/migrate-1x-to-v3/) For InfluxDB to automatically create DBRP mappings and buckets, you must use a [token](/influxdb3/cloud-serverless/admin/tokens/) that has write permissions for DBRPs and buckets. Auto-generated buckets use the [name syntax for mapped buckets](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#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](/influxdb3/cloud-serverless/admin/buckets/update-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 | To avoid having to add configuration parameters to each CLI command, [set up an active InfluxDB configuration](/influxdb3/cloud-serverless/reference/cli/influx/config/set/). ### 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:** Use the [`influx v1 dbrp create` command](/influxdb3/cloud-serverless/reference/cli/influx/v1/dbrp/create/) to map a database and retention policy to a bucket. Include the following: \* Required - \* a [token](/influxdb3/cloud-serverless/admin/tokens/) that has the necessary permissions to the mapped bucket. - \* the **database name** to map - \* the **retention policy** name to map - \* the [bucket ID](/influxdb3/cloud-serverless/admin/buckets/view-buckets/#view-buckets-in-the-influxdb-ui) to map to - **Default flag** to set the provided retention policy as the [default DBRP mapping](#default-dbrp) for the database. ```sh 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](/influxdb3/cloud-serverless/admin/tokens/) 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](/influxdb3/cloud-serverless/admin/buckets/view-buckets/) to map to The output is the DBRP. **InfluxDB API:** Use the [`/api/v2/dbrps` API endpoint](/influxdb3/cloud-serverless/api/) to create a new DBRP mapping. [POST https://cloud2.influxdata.com/api/v2/dbrps](/influxdb3/cloud-serverless/api/) Include the following: - **Request method:** `POST` - **Headers:** - **Authorization:** `Token` scheme with a [token](/influxdb3/cloud-serverless/admin/tokens/) 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](/influxdb3/cloud-serverless/admin/buckets/view-buckets/) to map to - **database:** the database name to map to the bucket - **org** or **orgID:** your organization name or [organization ID](/influxdb3/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id) - **retention\_policy:** the retention policy name to map to the bucket - Optional: **default:** `true` sets the database name’s [default DBRP mapping](#default-dbrp). ```sh 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](/influxdb3/cloud-serverless/reference/cli/influx/) or the [InfluxDB HTTP API](/influxdb3/cloud-serverless/reference/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:** Use the [`influx v1 dbrp list` command](/influxdb3/cloud-serverless/reference/cli/influx/v1/dbrp/list/) to list DBRP mappings. ##### View all DBRP mappings ```sh influx v1 dbrp list --token API_TOKEN --org ORG_ID \ ``` ##### Filter DBRP mappings by database ```sh influx v1 dbrp list \ --token API_TOKEN \ --org ORG_ID \ --db DATABASE_NAME ``` ##### Filter DBRP mappings by bucket ID ```sh influx v1 dbrp list \ --token API_TOKEN \ --org ORG_ID \ --bucket-id BUCKET_ID ``` **InfluxDB HTTP API:** Use the [`/api/v2/dbrps` API endpoint](/influxdb3/cloud-serverless/api/) to list DBRP mappings. [GET https://cloud2.influxdata.com/api/v2/dbrps](/influxdb3/cloud-serverless/api/) Include the following: - **Request method:** `GET` - **Headers:** - **Authorization:** `Token` scheme with your [token](/influxdb3/cloud-serverless/admin/tokens/) that has the necessary permissions to the mapped bucket - **Query parameters:** \* Required - \* **orgID:** your [organization ID](/influxdb3/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id) - **bucketID:** a [bucket ID](/influxdb3/cloud-serverless/admin/buckets/view-buckets/) *(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 ```sh 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 ```sh 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 ```sh 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](/influxdb3/cloud-serverless/reference/cli/influx/) or the [InfluxDB HTTP API](/influxdb3/cloud-serverless/reference/api/) to update a DBRP mapping–for example, to change the retention policy name or set the mapping as the [default](#default-dbrp) for the database name. **influx CLI:** Use the [`influx v1 dbrp update` command](/influxdb3/cloud-serverless/reference/cli/influx/v1/dbrp/update/) to update a DBRP mapping. Include the following: - a [token](/influxdb3/cloud-serverless/admin/tokens/) 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](#default-dbrp) for the database name. ##### Update the default retention policy ```sh 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](/influxdb3/cloud-serverless/admin/tokens/) 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. **InfluxDB HTTP API:** Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb3/cloud-serverless/api/) to update DBRP mappings. [PATCH https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}](/influxdb3/cloud-serverless/api/) Include the following: \* Required - **Request method:** `PATCH` - **Headers:** - \* the **Authorization:** `Token` scheme with a [token](/influxdb3/cloud-serverless/admin/tokens/) that has the necessary permissions to the mapped bucket - **Path parameters:** - \* **id:** the DBRP mapping ID to update - **Query parameters:** - \* **orgID:** your [organization ID](/influxdb3/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id) - **Request body (JSON):** - **rp:** retention policy name to update to - **default:** set the retention policy as the [default DBRP mapping](#default-dbrp) for the database name ##### Update the default retention policy ```sh 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](/influxdb3/cloud-serverless/admin/tokens/) 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](/influxdb3/cloud-serverless/reference/cli/influx/) or the [InfluxDB API](/influxdb3/cloud-serverless/reference/api/) to delete a DBRP mapping. **influx CLI:** Use the [`influx v1 dbrp delete` command](/influxdb3/cloud-serverless/reference/cli/influx/v1/dbrp/delete/) to delete a DBRP mapping. Include the following: \* Required - \* a [token](/influxdb3/cloud-serverless/admin/tokens/) that has the necessary permissions to the mapped bucket - \* **DBRP mapping ID** to delete ```sh influx v1 dbrp delete \ --token API_TOKEN \ --org ORG_ID \ --id DBRP_ID ``` The output is the DBRP. **InfluxDB API:** Use the [`/api/v2/dbrps/{dbrpID}` API endpoint](/influxdb3/cloud-serverless/api/) to delete a DBRP mapping. [DELETE https://cloud2.influxdata.com/api/v2/dbrps/{dbrpID}](/influxdb3/cloud-serverless/api/) Include the following: \* Required - **Request method:** `DELETE` - **Headers:** - \* the **Authorization:** `Token` scheme with a [token](/influxdb3/cloud-serverless/admin/tokens/) that has the necessary permissions to the mapped bucket - **Path parameters:** - \* **id:** DBRP mapping ID to update - **Query parameters:** - \* **orgID:** [organization ID](/influxdb3/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id) ```sh 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](/influxdb3/cloud-serverless/admin/tokens/) that has the necessary permissions to the mapped bucket - `DBRP_ID`: the DBRP ID to update - `ORG_ID`: the [organization ID](/influxdb3/cloud-serverless/admin/organizations/view-orgs/#view-your-organization-id) ## Write data See how to [use the InfluxDB Cloud Serverless HTTP write API](/influxdb3/cloud-serverless/write-data/api/v1-http/) for InfluxDB v1 or v1.x-compatibility workloads. ## Query data See how to [use the InfluxDB Cloud Serverless HTTP query API](/influxdb3/cloud-serverless/query-data/execute-queries/v1-http/) 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: ```sql SELECT INTO CREATE DELETE DROP GRANT EXPLAIN REVOKE ALTER SET KILL ``` #### Related - [Use the InfluxDB v1 HTTP query API and InfluxQL](/influxdb3/cloud-serverless/query-data/execute-queries/v1-http/) - [Use the InfluxDB v1 HTTP write API](/influxdb3/cloud-serverless/write-data/api/v1-http/)