Use compatibility APIs and client libraries to write data

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 InfluxDB 3 Core.

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

POST /api/v2/write?bucket=mydb&precision=ns

Authenticate v2 API requests

InfluxDB 3 Core requires each API request to be authenticated with a token.

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:

curl -i "https://localhost:8181/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'

Use Token to authenticate a v2 write request:

curl -i "https://localhost:8181/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'

v2 API write parameters

For InfluxDB 3 Core v2 API /api/v2/write requests, set parameters as listed in the following table:

Timestamp precision

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.

POST /write?db=mydb&precision=ns

Authenticate v1 API requests

InfluxDB 3 Core requires each API request to be authenticated with a token. 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 as the password credential. When authenticating requests to the v1 API /write endpoint, InfluxDB 3 Core checks that the password (p) value is an authorized token. InfluxDB 3 Core 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, InfluxDB 3 Core checks that the password part of the decoded credential is an authorized token. InfluxDB 3 Core 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:

curl -i "https://localhost:8181/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'

Query string authentication

In the URL, pass the p query parameter to authenticate /write requests. When authenticating requests, InfluxDB 3 Core checks that the p (password) value is an authorized token and ignores the u (username) parameter.

Syntax

https://localhost:8181/write/?u=any&p=DATABASE_TOKEN

Example

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

curl -i "https://localhost:8181/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'

Authenticate with a token scheme

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

Bearer and Token are equivalent in InfluxDB 3 Core. 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:

curl -i "https://localhost:8181/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'

Use Token to authenticate a v1 write request:

curl -i "https://localhost:8181/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'

v1 API write parameters

For InfluxDB 3 Core v1 API /write requests, set parameters as listed in the following table:

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

Client library examples

Use language-specific client libraries with your custom code to write data to InfluxDB 3 Core.

v1 client libraries

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

const Influx = require('influx')

// Instantiate a client for writing to InfluxDB 3 Core v1 API
const client = new Influx.InfluxDB({
  host: 'localhost:8181',
  port: 443,
  protocol: 'https',
  database: '
DATABASE_NAME
',
  username: 'ignored',
  password: '
DATABASE_TOKEN
'
})

from influxdb import InfluxDBClient

# Instantiate a client for writing to InfluxDB 3 Core v1 API
client = InfluxDBClient(
  host='localhost:8181',
  ssl=True,
  database='
DATABASE_NAME
',
  username='',
  password='
DATABASE_TOKEN
',
  headers={'Content-Type': 'text/plain; charset=utf-8'}
)

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 InfluxDB 3 Core v1 API:

To configure the v1.x output plugin for writing to InfluxDB 3 Core, add the following outputs.influxdb configuration in your telegraf.conf file:

[[outputs.influxdb]]
  urls = ["https://localhost:8181"]
  database = "
DATABASE_NAME
"
  skip_database_creation = true
  retention_policy = ""
  username = "ignored"
  password = "
DATABASE_TOKEN
"
  content_encoding = "gzip"

Replace the following configuration values:

• DATABASE_NAME: the name of the database to write to
• DATABASE_TOKEN: your InfluxDB 3 Core token