docs-v2/content/shared/influxdb-v2/api-guide/api_intro.md

InfluxDB offers a rich API and client libraries ready to integrate with your application. Use popular tools like Curl and Postman for rapidly testing API requests.

This section guides you through the most commonly used API methods.

For detailed documentation on the entire API, see the InfluxDB v2 API Reference.

[!Note] If you need to use InfluxDB {{< current-version >}} with InfluxDB 1.x API clients and integrations, see the 1.x compatibility API guide.

Bootstrap your application

With most API requests, you'll need to provide a minimum of your InfluxDB URL and Authorization Token (API Token).

Install InfluxDB OSS v2.x or upgrade to an InfluxDB Cloud account.

Authentication

InfluxDB uses API tokens to authorize API requests. InfluxDB filters API requests and response data based on the permissions associated with the token.

1. Before exploring the API, use the influx CLI or the InfluxDB UI to create an initial API token for your application.

2. Include your API token in an Authorization: Token API_TOKEN HTTP header with each request--for example:

{{% code-placeholders "API_TOKEN" %}}

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

# Use a token to authorize a GET request to the InfluxDB API.
# List buckets in your organization that the token can read.
curl -X GET "http://{{< influxdb/host >}}/api/v2/buckets" \
  --header 'Accept: application/json' \
  --header 'Authorization: Token API_TOKEN'

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

/**
  * Use a token to authorize a GET request to the InfluxDB API.
  * List buckets in your organization that the token can read.
  */

const https = require('https');

function listBuckets() {

  const options = {
    host: '{{< influxdb/host >}}',
    path: "/api/v2/buckets",
    headers: {
      'Authorization': 'Token API_TOKEN',
      'Content-type': 'application/json'
    },
  };

  const request = https.get(options, (response) => {
    let rawData = '';
    response.on('data', () => {
      response.on('data', (chunk) => { rawData += chunk; });
    })
    response.on('end', () => {
      console.log(rawData);
    })
  });

  request.end();
}

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

{{% /code-placeholders %}}

[!Note] Postman is another popular tool for exploring APIs. See how to send authenticated requests with Postman.

Buckets API

Before writing data you'll need to create a bucket in your InfluxDB instance. To use the API to create a bucket, send a request to the following endpoint:

{{% api-endpoint method="POST" endpoint="/api/v2/buckets" api-ref="/influxdb/version/api/v2/#operation/PostBuckets" %}}

{{% code-placeholders "API_TOKEN|ORG_ID|BUCKET_NAME|RETENTION_PERIOD_SECONDS" %}}

curl --request POST \
  "http://localhost:8086/api/v2/buckets" \
  --header "Authorization: Token API_TOKEN" \
  --json '{
    "orgID": "'"ORG_ID"'",
    "name": "BUCKET_NAME",
    "retentionRules": [
      {
        "type": "expire",
        "everySeconds": RETENTION_PERIOD_SECONDS,
        "shardGroupDurationSeconds": 0
      }
    ]
  }'

{{% /code-placeholders %}}

Replace the following placeholders with your values:

• {{% code-placeholder-key %}}API_TOKEN{{% /code-placeholder-key %}} - your token.
• {{% code-placeholder-key %}}ORG_ID{{% /code-placeholder-key %}} - the ID of the organization that owns the bucket.
• {{% code-placeholder-key %}}BUCKET_NAME{{% /code-placeholder-key %}} - the name of the bucket to create.
• Optional: {{% code-placeholder-key %}}RETENTION_PERIOD_SECONDS{{% /code-placeholder-key %}} - the retention period (in number of seconds) to retain data in the bucket. Default is 0 (infinite retention).
  • For example, 31536000 (1 year) or 604800 (7 days).

For more information, see Create a bucket.

Write API

Write data to InfluxDB using an HTTP request to the InfluxDB API /api/v2/write endpoint.

Query API

Query from InfluxDB using an HTTP request to the /api/v2/query endpoint.