--- title: Use the InfluxDB v1 HTTP write API seotitle: Use the v1 write API list_title: Use the v1 write API description: > Use the InfluxDB v1 HTTP write API to write data stored in InfluxDB Cloud Serverless. weight: 301 menu: influxdb3_cloud_serverless: parent: Write data name: Use the v1 HTTP write API influxdb3/cloud-serverless/tags: [query, influxql, python] metadata: [InfluxQL] related: - /influxdb3/cloud-serverless/guides/api-compatibility/v1/ - /influxdb3/cloud-serverless/reference/client-libraries/v1/ list_code_example: | ```sh curl "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \ --header "Authorization: Token API_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` --- Use the InfluxDB v1 HTTP API `/write` endpoint and InfluxQL to write data stored in {{< product-name >}}. The `/write` endpoint provides compatibility for InfluxDB 1.x workloads that you bring to InfluxDB 3. _The v1 write and query APIs require [mapping databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets)._ - [Map databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets) - [Autogenerate a bucket and DBRP mapping](#autogenerate-a-bucket-and-dbrp-mapping) - [Create a bucket and DBRP mapping](#create-a-bucket-and-dbrp-mapping) - [Write to the v1 HTTP `/write` endpoint](#write-to-the-v1-http-write-endpoint) - [Parameters](#parameters) - [Data](#data) - [Authorization](#authorization) - [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api) ## Map databases and retention policies to buckets The v1 write and query APIs require mapping databases and retention policies to buckets. InfluxDB can [autogenerate a bucket and DBRP mapping](#autogenerate-a-bucket-and-dbrp-mapping) for a write request or you can [create a bucket and DBRP](#create-a-bucket-and-dbrp-mapping) before writing. ### Autogenerate a bucket and DBRP mapping To let InfluxDB autogenerate a bucket and an associated DBRP mapping, pass the following parameters when writing data to the v1 `/write` endpoint: - a [`db=DATABASE_NAME` parameter](#v1-api-write-parameters). - Optional: an [`rp=RETENTION_POLICY_NAME`](#v1-api-write-parameters) parameter. Default retention policy name is `autogen`. - a token (such as an [All-access token](/influxdb3/cloud-serverless/admin/tokens/#all-access-api-token)) that has permission to write DBRPs and buckets. If no bucket exists with the name `DATABASE_NAME/RETENTION_POLICY_NAME`, InfluxDB creates a bucket and a DBRP before writing the data to the bucket. To learn more about DBRP mapping, see the [v1 API compatibility guide](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#map-v1-databases-and-retention-policies-to-buckets). ### Create a bucket and DBRP mapping To create a DBRP for a bucket: 1. If it doesn't already exist, [create the bucket](/influxdb3/cloud-serverless/admin/buckets/create-bucket/) that you want to write to. 2. [Find the bucket ID](/influxdb3/cloud-serverless/admin/buckets/view-buckets/) for the bucket that you want to write to. 3. [Create a DBRP](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#create-dbrp-mappings), which maps a database name and retention policy name to the bucket ID from the preceding step. If the `db=DATABASE_NAME` and `rp=RETENTION_POLICY` parameters in your `/write` request map to an existing DBRP, InfluxDB writes to the mapped bucket. ## Write to the v1 HTTP `/write` endpoint {{% api-endpoint endpoint="https://{{< influxdb/host >}}/write" method="post" %}} - [`/api/v2/write` parameters](#v1-api-write-parameters) - [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api) ### Parameters For {{% product-name %}} v1 API `/write` requests, set parameters as listed in the following table: Parameter | Allowed in | Ignored | Value -----------------------|--------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `consistency` | Query string | Ignored | N/A `db` {{% req " \*" %}} | Query string | Honored | Database (see how to [map databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets)) `precision` | Query string | Honored | [Timestamp precision](#timestamp-precision) `rp` | Query string | Honored | Retention policy (see how to [map databases and retention policies to buckets](#map-databases-and-retention-policies-to-buckets)) [`Authorization` header or `u` and `p`](#authorization) | | | [Token](#authorization) {{% caption %}}{{% req " \*" %}} = {{% req "Required" %}}{{% /caption %}} #### Timestamp precision Use one of the following `precision` values in v1 API `/write` requests: - `ns`: nanoseconds - `us`: microseconds - `ms`: milliseconds - `s`: seconds - `m`: minutes - `h`: hours ### Data In the request body, include the [line protocol](/influxdb3/cloud-serverless/write-data/line-protocol/) data that you want to write to the bucket. ### Authorization To authorize writes to an existing bucket, include a [token](/influxdb3/cloud-serverless/admin/tokens/) that has write permission to the bucket. Use [`Token` authentication](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#authenticate-with-a-token-scheme) or v1-compatible [username and password authentication](/influxdb3/cloud-serverless/guides/api-compatibility/v1/#authenticate-with-a-username-and-password-scheme) to include a token in the request. For InfluxDB to autogenerate the bucket and DBRP, you must use a [token](/influxdb3/cloud-serverless/admin/tokens/), such as an **All-access token**, that has write permissions to buckets and DBRPs. ### Tools for writing to the v1 API When using the v1 API and associated tooling, pass the DBRP mapping's database name and retention policy name in the request parameters. The following tools work with the {{% product-name %}} `/write` endpoint: - [Telegraf](#telegraf) - [Interactive clients](#interactive-clients) - [Client libraries](#client-libraries) #### Telegraf If you have existing v1 workloads that use Telegraf, you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) to write data. {{% note %}} See how to [use Telegraf and the v2 API](/influxdb3/cloud-serverless/write-data/use-telegraf/) for new workloads that don't already use the v1 API. {{% /note %}} The following table shows `outputs.influxdb` plugin parameters and values for writing to the {{% product-name %}} v1 API: Parameter | Ignored | Value -------------------------|--------------------------|--------------------------------------------------------------------------------------------------- `database` | Honored | Bucket name `retention_policy` | Honored | [Duration](/influxdb3/cloud-serverless/reference/glossary/#duration) `username` | Ignored | String or empty `password` | Honored | [API token](/influxdb3/cloud-serverless/admin/tokens/) with permission to write to the bucket `content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed) `skip_database_creation` | Ignored | N/A (see how to [create a bucket](/influxdb3/cloud-serverless/admin/buckets/create-bucket/)) To configure the v1.x output plugin for writing to {{% product-name %}}, add the following `outputs.influxdb` configuration in your `telegraf.conf` file: {{% code-placeholders "API_TOKEN|RETENTION_POLICY" %}} ```toml [[outputs.influxdb]] urls = ["https://{{< influxdb/host >}}"] database = "DATABASE_NAME" skip_database_creation = true retention_policy = "RETENTION_POLICY" username = "ignored" password = "API_TOKEN" content_encoding = "gzip” ``` {{% /code-placeholders %}} Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets) - {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets) - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb3/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket ##### Other Telegraf configuration options `influx_uint_support`: supported in InfluxDB 3. For more plugin options, see [`influxdb`](https://github.com/influxdata/telegraf/blob/master/plugins/outputs/influxdb/README.md) on GitHub. #### Interactive clients To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman. {{% note %}} For production use cases, use tools such as [client libraries](#client-libraries) that construct line protocol for you and provide batch writing options. {{% /note %}} {{< code-tabs-wrapper >}} {{% code-tabs %}} [Token Auth](#) [Basic Auth](#) [Query String Auth](#) {{% /code-tabs %}} {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}} ```sh curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \ --header "Authorization: Token API_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` {{% /code-placeholders %}} {{% /code-tab-content %}} {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}} ```sh curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \ -user "ignored":"API_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` {{% /code-placeholders %}} {{% /code-tab-content %}} {{% code-tab-content %}} {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}} ```sh curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&rp=RETENTION_POLICY&precision=s" \ --header "Content-type: text/plain; charset=utf-8" \ --data-urlencode "u=ignored" \ --data-urlencode "p=DATABASE_TOKEN" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` {{% /code-placeholders %}} {{% /code-tab-content %}} {{< /code-tabs-wrapper >}} Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets) - {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets) - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb3/cloud-serverless/admin/tokens/) with sufficient permissions to the mapped bucket #### v1 influx CLI (not supported) Don't use the v1 `influx` CLI with {{% product-name %}}. While it may coincidentally work, it isn't officially supported. #### Client libraries Use language-specific [v1 client libraries](/influxdb/v1/tools/api_client_libraries/) and your custom code to write data to InfluxDB. v1 client libraries send data in [line protocol](/influxdb3/cloud-serverless/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint. The following samples show how to configure **v1** client libraries for writing to {{% product-name %}}: {{< tabs-wrapper >}} {{% tabs %}} [Node.js](#nodejs) [Python](#python) {{% /tabs %}} {{% tab-content %}} Create a v1 API client using the [node-influx](/influxdb/v1/tools/api_client_libraries/#javascriptnodejs) JavaScript client library: {{% code-placeholders "BUCKET_NAME|API_TOKEN|RETENTION_POLICY" %}} ```js const Influx = require('influx') // Instantiate a client for writing to {{% product-name %}} v1 API const client = new Influx.InfluxDB({ host: '{{< influxdb/host >}}', port: 443, protocol: 'https' database: 'BUCKET_NAME', username: 'ignored', password: 'API_TOKEN' }) // When calling write or query functions, specify the retention policy name in options. ``` {{% /code-placeholders %}} {{% /tab-content %}} {{% tab-content %}} Create a v1 API client using the [influxdb-python](/influxdb/v1/tools/api_client_libraries/#python) Python client library: {{% code-placeholders "DATABASE_NAME|API_TOKEN|RETENTION_POLICY" %}} ```py from influxdb import InfluxDBClient # Instantiate a client for writing to {{% product-name %}} v1 API client = InfluxDBClient( host='{{< influxdb/host >}}', ssl=True, database='DATABASE_NAME', username='', password='API_TOKEN' headers={'Content-Type': 'text/plain; charset=utf-8'} ) # When calling write or query functions, specify the retention policy name in options. ``` {{% /code-placeholders %}} {{% /tab-content %}} {{< /tabs-wrapper >}} Replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the [database](#map-databases-and-retention-policies-to-buckets) - {{% code-placeholder-key %}}`RETENTION_POLICY`{{% /code-placeholder-key %}}: the [retention policy](#map-databases-and-retention-policies-to-buckets) - {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: a [token](/influxdb3/cloud-serverless/admin/tokens/) with sufficient permissions to the specified bucket