docs-v2/content/shared/influxdb3-write-guides/http-api/compatibility-apis.md

Use compatibility APIs when you need to migrate existing InfluxDB v1 or v2 write workloads to InfluxDB 3.x. The /api/v2/write (v2-compatible) and /write (v1-compatible) HTTP API endpoints work with InfluxDB client libraries, Telegraf, and third-party integrations to write points as line protocol data to {{% product-name %}}.

[!Note]

Compatibility APIs differ from native APIs

Keep in mind that the compatibility APIs differ from the v1 and v2 APIs in previous versions in the following ways:

• Tags in a table (measurement) are immutable
• A tag and a field can't have the same name within a table.

InfluxDB v2 compatibility

The /api/v2/write InfluxDB v2 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB OSS v2.x and Cloud 2 (TSM).

{{}}

Authenticate v2 API requests

{{< product-name >}} requires each API request to be authenticated with a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}.

Use the Authorization: Bearer or Authorization: Token scheme to authenticate v2 API write requests:

Syntax

Authorization: Bearer DATABASE_TOKEN

Authorization: Token DATABASE_TOKEN

Examples

Use Bearer to authenticate a v2 write request:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

curl -i "https://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME&precision=s" \
    --header "Authorization: Bearer DATABASE_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /code-placeholders %}}

Use Token to authenticate a v2 write request:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

curl -i "https://{{< influxdb/host >}}/api/v2/write?bucket=DATABASE_NAME&precision=s" \
    --header "Authorization: Token DATABASE_TOKEN" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /code-placeholders %}}

v2 API write parameters

For {{< product-name >}} v2 API /api/v2/write requests, set parameters as listed in the following table:

Parameter	Allowed in	Ignored	Value
bucket {{% req " *" %}}	Query string	Honored	Database name
precision	Query string	Honored	Timestamp precision
Content-Encoding	Header	Honored	gzip (compressed data) or identity (uncompressed)
Authorization	Header	Honored	Bearer DATABASE_TOKEN or Token DATABASE_TOKEN

{{% caption %}}{{% req " *" %}} = {{% req "Required" %}}{{% /caption %}}

Timestamp precision

[!Note] By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. To avoid any ambiguity, you can specify the precision of timestamps in your data.

Use one of the following precision values in v2 API /api/v2/write requests:

• ns: nanoseconds
• us: microseconds
• ms: milliseconds
• s: seconds
• m: minutes
• h: hours

InfluxDB v1 compatibility

The /write InfluxDB v1 compatibility endpoint provides backwards compatibility with clients that can write data to InfluxDB v1.x.

{{}}

Authenticate v1 API requests

{{< product-name >}} requires each API request to be authenticated with a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 Authorization: Token scheme, or in the OAuth Authorization: Bearer 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 database writes by passing a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} as the password credential. When authenticating requests to the v1 API /write endpoint, {{< product-name >}} checks that the password (p) value is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. {{< 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:

• Basic authentication
• Query string authentication

Basic authentication

Use the Authorization header with the Basic scheme to authenticate v1 API /write requests. When authenticating requests, {{< product-name >}} checks that the password part of the decoded credential is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}. {{< product-name >}} ignores the username part of the decoded credential.

Syntax

Authorization: Basic <base64-encoded [USERNAME]:DATABASE_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:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s" \
  --user "any:DATABASE_TOKEN" \
  --header "Content-type: text/plain; charset=utf-8" \
  --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /code-placeholders %}}

Query string authentication

In the URL, pass the p query parameter to authenticate /write requests. When authenticating requests, {{< product-name >}} checks that the p (password) value is an authorized {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} and ignores the u (username) parameter.

Syntax

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

Example

The following example shows how to use cURL with query string authentication:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

curl -i "https://{{< influxdb/host >}}/write?db=DATABASE_NAME&precision=s&p=DATABASE_TOKEN" \
  --header "Content-type: text/plain; charset=utf-8" \
  --data-binary 'home,room=kitchen temp=72 1641024000'

{{% /code-placeholders %}}

Authenticate with a token scheme

Use the Authorization: Bearer or the Authorization: Token scheme to pass a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}} for authenticating v1 API /write requests.

Bearer and Token are equivalent in {{< product-name >}}. The Token scheme is used in the InfluxDB 2.x API. Bearer is defined by the OAuth 2.0 Framework. Support for one or the other may vary across InfluxDB API clients.

Syntax

Authorization: Bearer DATABASE_TOKEN

Authorization: Token DATABASE_TOKEN

Examples

Use Bearer to authenticate a v1 write request:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

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

{{% /code-placeholders %}}

Use Token to authenticate a v1 write request:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

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

{{% /code-placeholders %}}

v1 API write 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 name
precision	Query string	Honored	Timestamp precision
rp	Query string	Honored, but discouraged	Retention policy
u	Query string	Ignored	For query string authentication, any arbitrary string
p	Query string	Honored	For query string authentication, a {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}
Content-Encoding	Header	Honored	gzip (compressed data) or identity (uncompressed)
Authorization	Header	Honored	Bearer DATABASE_TOKEN, Token DATABASE_TOKEN, or Basic <base64 [USERNAME]:DATABASE_TOKEN>

{{% caption %}}{{% req " *" %}} = {{% req "Required" %}}{{% /caption %}}

Timestamp precision

[!Note] By default, {{% product-name %}} uses the timestamp magnitude to auto-detect the precision. To avoid any ambiguity, you can specify the precision of timestamps in your data.

Use one of the following precision values in v1 API /write requests:

• ns: nanoseconds
• us: microseconds
• ms: milliseconds
• s: seconds
• m: minutes
• h: hours

Client library examples

Use language-specific client libraries with your custom code to write data to {{< product-name >}}.

v1 client libraries

v1 client libraries send data in line protocol syntax to the v1 API /write endpoint.

{{< tabs-wrapper >}} {{% tabs %}} Node.js Python {{% /tabs %}} {{% tab-content %}}

Create a v1 API client using the node-influx JavaScript client library:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

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: 'DATABASE_NAME',
  username: 'ignored',
  password: 'DATABASE_TOKEN'
})

{{% /code-placeholders %}}

{{% /tab-content %}} {{% tab-content %}}

Create a v1 API client using the influxdb-python Python client library:

{{% code-placeholders "DATABASE_NAME|DATABASE_TOKEN" %}}

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='DATABASE_TOKEN',
  headers={'Content-Type': 'text/plain; charset=utf-8'}
)

{{% /code-placeholders %}}

{{% /tab-content %}} {{< /tabs-wrapper >}}

v2 client libraries

v2 client libraries send data in line protocol syntax to the v2 API /api/v2/write endpoint.

For more information about using v2 client libraries, see v2 client libraries.

Telegraf configuration

If you have existing v1 workloads that use Telegraf, you can use the InfluxDB v1.x influxdb Telegraf output plugin to write data.

The following table shows outputs.influxdb plugin parameters and values for writing to the {{< product-name >}} v1 API:

Parameter	Ignored	Value
database	Honored	Database name
retention_policy	Honored, but discouraged	Duration
username	Ignored	String or empty
password	Honored	{{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}
content_encoding	Honored	gzip (compressed data) or identity (uncompressed)
skip_database_creation	Ignored	N/A (see how to create a database)

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 "DATABASE_NAME|DATABASE_TOKEN" %}}

[[outputs.influxdb]]
  urls = ["https://{{< influxdb/host >}}"]
  database = "DATABASE_NAME"
  skip_database_creation = true
  retention_policy = ""
  username = "ignored"
  password = "DATABASE_TOKEN"
  content_encoding = "gzip"

{{% /code-placeholders %}}

Replace the following configuration values:

• {{% code-placeholder-key %}}DATABASE_NAME{{% /code-placeholder-key %}}: the name of the database to write to
• {{% code-placeholder-key %}}DATABASE_TOKEN{{% /code-placeholder-key %}}: your {{< product-name >}} {{% token-link %}}{{% show-in "enterprise" %}} with write access to the database{{% /show-in %}}