openapi: 3.0.3
info:
title: InfluxDB 3 Core API Service
description: >
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface
for
interacting with InfluxDB 3 Core databases and resources.
Use this API to:
- Write data to InfluxDB 3 Core databases
- Query data using SQL or InfluxQL
- Process data using Processing engine plugins
- Manage databases, tables, and Processing engine triggers
- Perform administrative tasks and access system information
The API includes endpoints under the following paths:
- `/api/v3`: InfluxDB 3 Core native endpoints
- `/`: Compatibility endpoints for InfluxDB v1 workloads and clients
- `/api/v2/write`: Compatibility endpoint for InfluxDB v2 workloads and
clients
[Download the OpenAPI
specification](https://docs.influxdata.com/openapi/influxdb3-core-openapi.yaml)
version: v3.12.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: InfluxData
url: https://www.influxdata.com
email: support@influxdata.com
x-source-hash: sha256:24c3cc46699dc72e1bbfe45f0a3d91b32ed9f7635526e0a44136a3982870f228
x-influxdata-download-url: /openapi/influxdb3-core-openapi.yaml
x-influxdata-short-title: InfluxDB 3 API
x-influxdata-version-matrix:
v1: Compatibility layer for InfluxDB 1.x clients (supported)
v2: Compatibility layer for InfluxDB 2.x clients (supported)
v3: Native API for InfluxDB 3.x (current)
x-influxdata-short-description: >-
The InfluxDB 3 HTTP API provides a programmatic interface for interactions
with InfluxDB, including writing, querying, and processing data, and
managing an InfluxDB 3 instance.
servers:
- url: https://{baseurl}
description: InfluxDB 3 Core API URL
variables:
baseurl:
enum:
- localhost:8181
default: localhost:8181
description: InfluxDB 3 Core URL
security:
- BearerAuthentication: []
- TokenAuthentication: []
- BasicAuthentication: []
- QuerystringAuthentication: []
tags:
- name: Authentication
description: >-
Use one of the following schemes to authenticate to the InfluxDB 3 Core
API:
- [Token authentication](#section/Authentication/TokenAuthentication)
- [Bearer authentication](#section/Authentication/BearerAuthentication)
- [Basic authentication](#section/Authentication/BasicAuthentication)
- [Querystring
authentication](#section/Authentication/QuerystringAuthentication)
x-traitTag: true
x-related:
- title: Authenticate v1 API requests
href: >-
https://docs.influxdata.com/influxdb3/core/guides/api-compatibility/v1/
- title: Manage tokens
href: https://docs.influxdata.com/influxdb3/core/admin/tokens/
- name: Database
description: Create, list, and delete databases in InfluxDB 3 Core.
x-related:
- title: Manage databases
href: https://docs.influxdata.com/influxdb3/core/admin/databases/
- description: >-
Most InfluxDB API endpoints require parameters in the request--for
example, specifying the database to use.
### Common parameters
The following table shows common parameters used by many InfluxDB API
endpoints.
Many endpoints may require other parameters in the query string or in the
request body that perform functions specific to those endpoints.
| Query parameter | Value type |
Description |
|:------------------------ |:---------------------
|:-------------------------------------------|
| `db` | string | The database name |
InfluxDB HTTP API endpoints use standard HTTP request and response
headers.
The following table shows common headers used by many InfluxDB API
endpoints.
Some endpoints may use other headers that perform functions more specific
to those endpoints--for example,
the write endpoints accept the `Content-Encoding` header to indicate that
line protocol is compressed in the request body.
| Header | Value type |
Description |
|:------------------------ |:---------------------
|:-------------------------------------------|
| `Accept` | string | The content type that
the client can understand. |
| `Authorization` | string | The authorization
scheme and credential. |
| `Content-Length` | integer | The size of the
entity-body, in bytes. |
| `Content-Type` | string | The format of the
data in the request body. |
name: Headers and parameters
x-traitTag: true
- name: Processing engine
description: >-
Manage Processing engine triggers, test plugins, and send requests to
trigger On Request plugins.
InfluxDB 3 Core provides the InfluxDB 3 processing engine, an embedded
Python VM that can dynamically load and trigger Python plugins in response
to events in your database.
Use Processing engine plugins and triggers to run code and perform tasks
for different database events.
x-related:
- title: Processing engine and Python plugins
href: https://docs.influxdata.com/influxdb3/core/processing-engine/
- name: Query data
description: Query data stored in InfluxDB 3 Core using SQL or InfluxQL.
x-related:
- title: Query data
href: https://docs.influxdata.com/influxdb3/core/query-data/
- name: Quick start
description: >-
Authenticate, write, and query with the API:
1. Create an admin token to authorize API requests.
```bash
curl -X POST "http://localhost:8181/api/v3/configure/token/admin"
```
2. Check the status of the InfluxDB server.
```bash
curl "http://localhost:8181/health" \
--header "Authorization: Bearer ADMIN_TOKEN"
```
3. Write data to InfluxDB.
```bash
curl "http://localhost:8181/api/v3/write_lp?db=sensors&precision=auto"
--header "Authorization: Bearer ADMIN_TOKEN" \
--data-raw "home,room=Kitchen temp=72.0
home,room=Living\ room temp=71.5"
```
If all data is written, the response is `204 No Content`.
4. Query data from InfluxDB.
```bash
curl -G "http://localhost:8181/api/v3/query_sql" \
--header "Authorization: Bearer ADMIN_TOKEN" \
--data-urlencode "db=sensors" \
--data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
--data-urlencode "format=jsonl"
```
Output:
```jsonl
{"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"}
```
For more information about using InfluxDB 3 Core, see the [Get
started](https://docs.influxdata.com/influxdb3/core/get-started/) guide.
x-traitTag: true
- name: Server information
description: >-
Retrieve server metrics, health status, and version information for
InfluxDB 3 Core.
- name: Table
description: Manage table schemas in an InfluxDB 3 Core database.
x-related:
- title: Manage tables
href: https://docs.influxdata.com/influxdb3/core/admin/tables/
- name: Auth token
description: >-
Create and manage tokens used for authenticating and authorizing access to
InfluxDB 3 Core resources.
x-related:
- title: Manage tokens
href: https://docs.influxdata.com/influxdb3/core/admin/tokens/
- name: Write data
description: >-
Write data to InfluxDB 3 Core using line protocol format.
#### Timestamp precision across write APIs
InfluxDB 3 provides multiple write endpoints for compatibility with
different InfluxDB versions.
The following table compares timestamp precision support across v1, v2,
and v3 write APIs:
| Precision | v1 (`/write`) | v2 (`/api/v2/write`) | v3
(`/api/v3/write_lp`) |
|-----------|---------------|----------------------|-------------------------|
| **Auto detection** | ❌ No | ❌ No | ✅ `auto` (default) |
| **Seconds** | ✅ `s` | ✅ `s` | ✅ `second` |
| **Milliseconds** | ✅ `ms` | ✅ `ms` | ✅ `millisecond` |
| **Microseconds** | ✅ `u` or `µ` | ✅ `us` | ✅ `microsecond` |
| **Nanoseconds** | ✅ `ns` | ✅ `ns` | ✅ `nanosecond` |
| **Minutes** | ✅ `m` | ❌ No | ❌ No |
| **Hours** | ✅ `h` | ❌ No | ❌ No |
| **Default** | Nanosecond | Nanosecond | **Auto** (guessed) |
All timestamps are stored internally as nanoseconds.
x-related:
- title: Write data using HTTP APIs
href: https://docs.influxdata.com/influxdb3/core/write-data/http-api/
- title: Line protocol reference
href: >-
https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/
- name: Cache distinct values
description: >-
The Distinct Value Cache (DVC) lets you cache distinct
values of one or more columns in a table, improving the performance of
queries that return distinct tag and field values.
The DVC is an in-memory cache that stores distinct values for specific
columns
in a table. When you create a DVC, you can specify what columns' distinct
values to cache, the maximum number of distinct value combinations to
cache, and
the maximum age of cached values. A DVC is associated with a table, which
can
have multiple DVCs.
x-related:
- title: Manage the Distinct Value Cache
href: https://docs.influxdata.com/influxdb3/core/admin/distinct-value-cache/
- name: Cache last value
description: >-
The Last Value Cache (LVC) lets you cache the most recent
values for specific fields in a table, improving the performance of
queries that
return the most recent value of a field for specific series or the last N
values
of a field.
The LVC is an in-memory cache that stores the last N number of values for
specific fields of series in a table. When you create an LVC, you can
specify
what fields to cache, what tags to use to identify each series, and the
number of values to cache for each unique series.
An LVC is associated with a table, which can have multiple LVCs.
x-related:
- title: Manage the Last Value Cache
href: https://docs.influxdata.com/influxdb3/core/admin/last-value-cache/
- name: Cache data
- name: Migrate from InfluxDB v1 or v2
description: >-
Migrate your existing InfluxDB v1 or v2 workloads to InfluxDB 3 Core.
InfluxDB 3 provides compatibility endpoints that work with InfluxDB 1.x
and 2.x client libraries and tools.
Operations marked with v1 or v2 badges are compatible with the respective
InfluxDB version.
### Migration guides
- [Migrate from InfluxDB v1 or
v2](https://docs.influxdata.com/influxdb3/core/get-started/migrate-from-influxdb-v1-v2/)
- For users migrating from InfluxDB 1.x, 2.x, or Cloud
- [Use compatibility APIs to write
data](https://docs.influxdata.com/influxdb3/core/write-data/http-api/compatibility-apis/)
- v1 and v2 write endpoints
- [Use the v1 HTTP query
API](https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/influxdb-v1-api/)
- InfluxQL queries via HTTP
x-traitTag: true
paths:
/api/v1/health:
get:
operationId: GetHealthV1
summary: Health check (v1)
description: >
Checks the status of the service.
Returns `OK` if the service is running. This endpoint does not return
version information.
Use the [`/ping`](#operation/GetPing) endpoint to retrieve version
details.
> **Note**: This endpoint requires authentication by default in InfluxDB
3 Core.
responses:
'200':
description: Service is running. Returns `OK`.
content:
text/plain:
schema:
type: string
example: OK
'401':
description: Unauthorized. Authentication is required.
'500':
description: Service is unavailable.
tags:
- Server information
/api/v2/write:
post:
operationId: PostV2Write
responses:
'204':
description: >-
Success ("No Content"). All data in the batch is written and
queryable.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'400':
description: >
Bad request. InfluxDB rejected the whole batch and wrote nothing.
This endpoint doesn't support partial writes: if any line is
invalid, no
lines are written, and an `accept_partial` parameter is ignored.
To write the valid lines of a batch, use `/api/v3/write_lp`.
content:
application/json:
examples:
rejectedBatch:
summary: One invalid line rejects the batch
value: |
{
"code": "invalid",
"message": "write buffer error: line protocol parse failed: No fields were provided"
}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
summary: Write line protocol (v2-compatible)
description: >
Writes line protocol to the specified database.
This endpoint provides backward compatibility for InfluxDB 2.x write
workloads using tools such as InfluxDB 2.x client libraries, the
Telegraf `outputs.influxdb_v2` output plugin, or third-party tools.
Use this endpoint to send data in [line
protocol](https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/)
format to InfluxDB.
Use query parameters to specify options for writing data.
#### Related
- [Use compatibility APIs to write
data](https://docs.influxdata.com/influxdb3/core/write-data/http-api/compatibility-apis/)
parameters:
- name: Content-Type
in: header
description: |
The content type of the request payload.
schema:
$ref: '#/components/schemas/LineProtocol'
required: false
- description: |
The compression applied to the line protocol in the request payload.
To send a gzip payload, pass `Content-Encoding: gzip` header.
in: header
name: Content-Encoding
schema:
default: identity
description: >
Content coding.
Use `gzip` for compressed data or `identity` for unmodified,
uncompressed data.
enum:
- gzip
- identity
type: string
- description: |
The size of the entity-body, in bytes, sent to InfluxDB.
in: header
name: Content-Length
schema:
description: The length in decimal number of octets.
type: integer
- description: >
The content type that the client can understand.
Writes only return a response body if they fail (partially or
completely)--for example,
due to a syntax problem or type mismatch.
in: header
name: Accept
schema:
default: application/json
description: Error content type.
enum:
- application/json
type: string
- name: bucket
in: query
required: true
schema:
type: string
description: >-
A database name.
InfluxDB creates the database if it doesn't already exist, and then
writes all points in the batch to the database.
This parameter is named `bucket` for compatibility with InfluxDB v2
client libraries.
- $ref: '#/components/parameters/compatibilityPrecisionParam'
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
tags:
- Write data
/api/v3/configure/database:
delete:
operationId: DeleteConfigureDatabase
parameters:
- $ref: '#/components/parameters/db'
- name: data_only
in: query
required: false
schema:
type: boolean
default: false
description: >
Delete only data while preserving the database schema and all
associated resources
(tokens, triggers, last value caches, distinct value caches,
processing engine configurations).
When `false` (default), the entire database is deleted.
- name: remove_tables
in: query
required: false
schema:
type: boolean
default: false
description: >
Used with `data_only=true` to remove table resources (caches) while
preserving
database-level resources (tokens, triggers, processing engine
configurations).
Has no effect when `data_only=false`.
- name: hard_delete_at
in: query
required: false
schema:
type: string
format: date-time
description: >-
Schedule the database for hard deletion at the specified time.
If not provided, the database will be soft deleted.
Use ISO 8601 date-time format (for example, "2025-12-31T23:59:59Z").
#### Deleting a database cannot be undone
Deleting a database is a destructive action.
Once a database is deleted, data stored in that database cannot be
recovered.
Also accepts special string values:
- `now` — hard delete immediately
- `never` — soft delete only (default behavior)
- `default` — use the system default hard deletion time
responses:
'200':
description: Success. Database deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: Delete a database
description: >
Soft deletes a database.
The database is scheduled for deletion and unavailable for querying.
Use the `hard_delete_at` parameter to schedule a hard deletion.
Use the `data_only` parameter to delete data while preserving the
database schema and resources.
tags:
- Database
get:
operationId: GetConfigureDatabase
responses:
'200':
description: Success. The response body contains the list of databases.
content:
application/json:
schema:
$ref: '#/components/schemas/ShowDatabasesResponse'
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: List databases
description: Retrieves a list of databases.
parameters:
- $ref: '#/components/parameters/formatRequired'
- name: show_deleted
in: query
required: false
schema:
type: boolean
default: false
description: |
Include soft-deleted databases in the response.
By default, only active databases are returned.
tags:
- Database
post:
operationId: PostConfigureDatabase
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatabaseRequest'
responses:
'200':
description: Success. Database created.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: Database already exists.
summary: Create a database
description: Creates a new database in the system.
tags:
- Database
put:
operationId: PutConfigureDatabase
responses:
'200':
description: Success. The database has been updated.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: Update a database
description: |
Updates database configuration, such as retention period.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDatabaseRequest'
tags:
- Database
/api/v3/configure/database/retention_period:
delete:
operationId: DeleteDatabaseRetentionPeriod
summary: Remove database retention period
description: >
Removes the retention period from a database, setting it to infinite
retention.
parameters:
- $ref: '#/components/parameters/db'
responses:
'204':
description: Success. The database retention period has been removed.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
tags:
- Database
/api/v3/configure/distinct_cache:
delete:
operationId: DeleteConfigureDistinctCache
requestBody:
required: true
content:
application/json:
schema:
type: object
description: DistinctCacheDeleteRequest
responses:
'200':
description: Success. The distinct cache has been deleted.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Cache not found.
summary: Delete distinct cache
description: Deletes a distinct cache.
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
description: The name of the table containing the distinct cache.
- name: name
in: query
required: true
schema:
type: string
description: The name of the distinct cache to delete.
tags:
- Cache distinct values
- Table
post:
operationId: PostConfigureDistinctCache
responses:
'201':
description: Success. The distinct cache has been created.
'400':
description: >
Bad request.
The server responds with status `400` if the request would overwrite
an existing cache with a different configuration.
'409':
description: Conflict. A distinct cache with this configuration already exists.
summary: Create distinct cache
description: Creates a distinct cache for a table.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DistinctCacheCreateRequest'
tags:
- Cache distinct values
- Table
/api/v3/configure/last_cache:
delete:
operationId: DeleteConfigureLastCache
requestBody:
required: true
content:
application/json:
schema:
type: object
description: LastCacheDeleteRequest
responses:
'200':
description: Success. The last cache has been deleted.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Cache not found.
summary: Delete last cache
description: Deletes a last cache.
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
description: The name of the table containing the last cache.
- name: name
in: query
required: true
schema:
type: string
description: The name of the last cache to delete.
tags:
- Cache last value
- Table
post:
operationId: PostConfigureLastCache
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LastCacheCreateRequest'
responses:
'201':
description: Success. Last cache created.
'400':
description: >-
Bad request. A cache with this name already exists or the request is
malformed.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Cache not found.
summary: Create last cache
description: Creates a last cache for a table.
tags:
- Cache last value
- Table
/api/v3/configure/plugin_environment/install_packages:
post:
operationId: PostInstallPluginPackages
summary: Install plugin packages
description: >-
Installs the specified Python packages into the processing engine plugin
environment.
This endpoint is synchronous and blocks until the packages are
installed.
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
packages:
type: array
items:
type: string
description: >
A list of Python package names to install.
Can include version specifiers (for example,
"scipy==1.9.0").
example:
- influxdb3-python
- scipy
- pandas==1.5.0
- requests
required:
- packages
example:
packages:
- influxdb3-python
- scipy
- pandas==1.5.0
- requests
responses:
'200':
description: >-
Success. The packages are installed. In InfluxDB 3 Core 3.12, a
failed install can also return `200`; confirm that the package
imports before relying on it.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'500':
description: >-
The package install failed, for example because pip couldn't find
the package. The body includes the package manager's error.
tags:
- Processing engine
/api/v3/configure/plugin_environment/install_requirements:
post:
operationId: PostInstallPluginRequirements
summary: Install plugin requirements
description: >
Installs requirements from a requirements file (also known as a "pip
requirements file") into the processing engine plugin environment.
This endpoint is synchronous and blocks until the requirements are
installed.
### Related
- [Processing engine and Python
plugins](https://docs.influxdata.com/influxdb3/core/plugins/)
- [Python requirements file
format](https://pip.pypa.io/en/stable/reference/requirements-file-format/)
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
requirements_location:
type: string
description: >
The path to the requirements file containing Python packages
to install.
Can be a relative path (relative to the plugin directory) or
an absolute path.
example: requirements.txt
required:
- requirements_location
example:
requirements_location: requirements.txt
responses:
'200':
description: Success. The requirements have been installed.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Processing engine
/api/v3/configure/processing_engine_trigger:
post:
operationId: PostConfigureProcessingEngineTrigger
summary: Create processing engine trigger
description: >-
Creates a processing engine trigger with the specified plugin file and
trigger specification.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessingEngineTriggerRequest'
examples:
schedule_cron:
summary: Schedule trigger using cron
description: >
In `"cron:CRON_EXPRESSION"`, `CRON_EXPRESSION` uses extended
6-field cron format.
The cron expression `0 0 6 * * 1-5` means the trigger will run
at 6:00 AM every weekday (Monday to Friday).
value:
db: DATABASE_NAME
plugin_filename: schedule.py
trigger_name: schedule_cron_trigger
trigger_specification: cron:0 0 6 * * 1-5
disabled: false
trigger_settings:
run_async: false
error_behavior: log
schedule_every:
summary: Schedule trigger using interval
description: >
In `"every:DURATION"`, `DURATION` specifies the interval
between trigger executions.
The duration `1h` means the trigger will run every hour.
value:
db: mydb
plugin_filename: schedule.py
trigger_name: schedule_every_trigger
trigger_specification: every:1h
disabled: false
trigger_settings:
run_async: false
error_behavior: log
schedule_every_seconds:
summary: Schedule trigger using seconds interval
description: |
Example of scheduling a trigger to run every 30 seconds.
value:
db: mydb
plugin_filename: schedule.py
trigger_name: schedule_every_30s_trigger
trigger_specification: every:30s
disabled: false
trigger_settings:
run_async: false
error_behavior: log
schedule_every_minutes:
summary: Schedule trigger using minutes interval
description: |
Example of scheduling a trigger to run every 5 minutes.
value:
db: mydb
plugin_filename: schedule.py
trigger_name: schedule_every_5m_trigger
trigger_specification: every:5m
disabled: false
trigger_settings:
run_async: false
error_behavior: log
all_tables:
summary: All tables trigger example
description: >
Trigger that fires on write events to any table in the
database.
value:
db: mydb
plugin_filename: all_tables.py
trigger_name: all_tables_trigger
trigger_specification: all_tables
disabled: false
trigger_settings:
run_async: false
error_behavior: log
github_plugin:
summary: Trigger using a remotely fetched plugin
description: >
Trigger that uses a plugin referenced with the `gh:` prefix.
InfluxDB fetches the plugin from the default
`influxdata/influxdb3_plugins`
repository (or the repository configured with `--plugin-repo`)
instead of the local `--plugin-dir`.
value:
db: mydb
plugin_filename: gh:examples/wal_plugin/wal_plugin.py
trigger_name: my_trigger
trigger_specification: all_tables
disabled: false
trigger_settings:
run_async: false
error_behavior: log
table_specific:
summary: Table-specific trigger example
description: |
Trigger that fires on write events to a specific table.
value:
db: mydb
plugin_filename: table.py
trigger_name: table_trigger
trigger_specification: table:sensors
disabled: false
trigger_settings:
run_async: false
error_behavior: log
api_request:
summary: On-demand request trigger example
description: >
Creates an HTTP endpoint `/api/v3/engine/hello-world` for
manual invocation.
value:
db: mydb
plugin_filename: request.py
trigger_name: hello_world_trigger
trigger_specification: request:hello-world
disabled: false
trigger_settings:
run_async: false
error_behavior: log
cron_friday_afternoon:
summary: Cron trigger for Friday afternoons
description: |
Example of a cron trigger that runs every Friday at 2:30 PM.
value:
db: reports
plugin_filename: weekly_report.py
trigger_name: friday_report_trigger
trigger_specification: cron:0 30 14 * * 5
disabled: false
trigger_settings:
run_async: false
error_behavior: log
cron_monthly:
summary: Cron trigger for monthly execution
description: >
Example of a cron trigger that runs on the first day of every
month at midnight.
value:
db: monthly_data
plugin_filename: monthly_cleanup.py
trigger_name: monthly_cleanup_trigger
trigger_specification: cron:0 0 0 1 * *
disabled: false
trigger_settings:
run_async: false
error_behavior: log
responses:
'200':
description: Success. Processing engine trigger created.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Trigger not found.
tags:
- Processing engine
delete:
operationId: DeleteConfigureProcessingEngineTrigger
summary: Delete processing engine trigger
description: Deletes a processing engine trigger.
parameters:
- $ref: '#/components/parameters/db'
- name: trigger_name
in: query
required: true
schema:
type: string
- name: force
in: query
required: false
schema:
type: boolean
default: false
description: |
Force deletion of the trigger even if it has active executions.
By default, deletion fails if the trigger is currently executing.
responses:
'200':
description: Success. The processing engine trigger has been deleted.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Trigger not found.
tags:
- Processing engine
/api/v3/configure/processing_engine_trigger/disable:
post:
operationId: PostDisableProcessingEngineTrigger
summary: Disable processing engine trigger
description: Disables a processing engine trigger.
parameters:
- name: db
in: query
required: true
schema:
type: string
description: The database name.
- name: trigger_name
in: query
required: true
schema:
type: string
description: The name of the trigger.
responses:
'200':
description: Success. The processing engine trigger has been disabled.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Trigger not found.
tags:
- Processing engine
/api/v3/configure/processing_engine_trigger/enable:
post:
operationId: PostEnableProcessingEngineTrigger
summary: Enable processing engine trigger
description: Enables a processing engine trigger.
parameters:
- name: db
in: query
required: true
schema:
type: string
description: The database name.
- name: trigger_name
in: query
required: true
schema:
type: string
description: The name of the trigger.
responses:
'200':
description: Success. The processing engine trigger is enabled.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Trigger not found.
tags:
- Processing engine
/api/v3/configure/table:
delete:
operationId: DeleteConfigureTable
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
- name: data_only
in: query
required: false
schema:
type: boolean
default: false
description: >
Delete only data while preserving the table schema and all
associated resources
(last value caches, distinct value caches).
When `false` (default), the entire table is deleted.
- name: hard_delete_at
in: query
required: false
schema:
type: string
format: date-time
description: |-
Schedule the table for hard deletion at the specified time.
If not provided, the table will be soft deleted.
Use ISO 8601 format (for example, "2025-12-31T23:59:59Z").
Also accepts special string values:
- `now` — hard delete immediately
- `never` — soft delete only (default behavior)
- `default` — use the system default hard deletion time
responses:
'200':
description: Success (no content). The table has been deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Table not found.
'409':
description: Conflict. The table is already deleted.
summary: Delete a table
description: >
Soft deletes a table.
The table is scheduled for deletion and unavailable for querying.
Use the `hard_delete_at` parameter to schedule a hard deletion.
Use the `data_only` parameter to delete data while preserving the table
schema and resources.
#### Deleting a table cannot be undone
Deleting a table is a destructive action.
Once a table is deleted, data stored in that table cannot be recovered.
#### Soft-deleted tables keep a renamed, visible entry until hard
deletion
A soft delete renames the table to `-`
instead of removing it.
Until the table is hard deleted, this renamed entry still appears in
`SHOW TABLES` output and in
`information_schema.tables` queries. Filter out names that end in a
deleted-at timestamp to account for
these renamed entries when listing or counting tables.
Deleting an already-deleted table returns `409 Conflict`. There's no API
to remove the renamed entry
directly; only a scheduled or immediate (`hard_delete_at=now`) hard
deletion removes it.
tags:
- Table
post:
operationId: PostConfigureTable
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableRequest'
responses:
'200':
description: Success. The table has been created.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: Create a table
description: Creates a new table within a database.
tags:
- Table
patch:
operationId: PatchConfigureTable
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchTableRequest'
responses:
'200':
description: >-
Success. The columns have been added to the table. The response body
is empty.
'400':
description: >-
Bad request. The request names no tags or fields, or is otherwise
invalid.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database or table not found.
summary: Add columns to a table
description: >
Adds tag and field columns to an existing table.
The change is additive: a column that already exists with the requested
type is left unchanged.
No other table settings are modified.
The request must name at least one tag or field.
tags:
- Table
/api/v3/configure/token:
delete:
operationId: DeleteToken
parameters:
- name: token_name
in: query
required: true
schema:
type: string
description: The name of the token to delete.
responses:
'200':
description: Success. The token has been deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Token not found.
summary: Delete token
description: |
Deletes a token.
tags:
- Authentication
- Auth token
/api/v3/configure/token/admin:
post:
operationId: PostCreateAdminToken
responses:
'201':
description: |
Success. The admin token has been created.
The response body contains the token string and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
summary: Create admin token
description: >
Creates an admin token.
An admin token is a special type of token that has full access to all
resources in the system.
tags:
- Authentication
- Auth token
/api/v3/configure/token/admin/regenerate:
post:
operationId: PostRegenerateAdminToken
summary: Regenerate admin token
description: >
Regenerates an admin token and revokes the previous token with the same
name.
parameters: []
responses:
'201':
description: Success. The admin token has been regenerated.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Auth token
/api/v3/configure/token/named_admin:
post:
operationId: PostCreateNamedAdminToken
responses:
'201':
description: |
Success. The named admin token has been created.
The response body contains the token string and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: A token with this name already exists.
summary: Create named admin token
description: >
Creates a named admin token.
A named admin token is a special type of admin token with a custom name
for identification and management.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
token_name:
type: string
description: The name for the admin token.
expiry_secs:
type: integer
description: >-
Optional expiration time in seconds. If not provided, the
token does not expire.
nullable: true
required:
- token_name
tags:
- Authentication
- Auth token
/api/v3/engine/{request_path}:
get:
operationId: GetProcessingEnginePluginRequest
responses:
'200':
description: Success. The plugin request has been executed.
'400':
description: Malformed request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Plugin not found.
'500':
description: Processing failure.
summary: On Request processing engine plugin request
description: >
Executes the On Request processing engine plugin specified in the
trigger's `plugin_filename`.
The request can include request headers, query string parameters, and a
request body, which InfluxDB passes to the plugin.
An On Request plugin implements the following signature:
```python
def process_request(influxdb3_local, query_parameters, request_headers,
request_body, args=None)
```
The response depends on the plugin implementation.
tags:
- Processing engine
post:
operationId: PostProcessingEnginePluginRequest
responses:
'200':
description: Success. The plugin request has been executed.
'400':
description: Malformed request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Plugin not found.
'500':
description: Processing failure.
summary: On Request processing engine plugin request
description: >
Executes the On Request processing engine plugin specified in the
trigger's `plugin_filename`.
The request can include request headers, query string parameters, and a
request body, which InfluxDB passes to the plugin.
An On Request plugin implements the following signature:
```python
def process_request(influxdb3_local, query_parameters, request_headers,
request_body, args=None)
```
The response depends on the plugin implementation.
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
required: false
content:
application/json:
schema:
type: object
additionalProperties: true
tags:
- Processing engine
parameters:
- name: request_path
description: >
The path configured in the request trigger specification for the
plugin.
For example, if you define a trigger with the following:
```json
trigger_specification: "request:hello-world"
```
then, the HTTP API exposes the following plugin endpoint:
```
/api/v3/engine/hello-world
```
in: path
required: true
schema:
type: string
/api/v3/plugin_test/schedule:
post:
operationId: PostTestSchedulingPlugin
responses:
'200':
description: Success. The plugin test has been executed.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Plugin not enabled.
summary: Test scheduling plugin
description: Executes a test of a scheduling plugin.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulePluginTestRequest'
tags:
- Processing engine
/api/v3/plugin_test/wal:
post:
operationId: PostTestWALPlugin
responses:
'200':
description: Success. The plugin test has been executed.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Plugin not enabled.
summary: Test WAL plugin
description: Executes a test of a write-ahead logging (WAL) plugin.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WALPluginTestRequest'
tags:
- Processing engine
/api/v3/plugins/directory:
put:
operationId: PutPluginDirectory
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginDirectoryRequest'
responses:
'200':
description: Success. The plugin directory has been updated.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. Admin token required.
'500':
description: >-
Plugin not found. The `plugin_name` does not match any registered
trigger.
summary: Update a multi-file plugin directory
description: |
Replaces all files in a multi-file plugin directory. The
`plugin_name` must match a registered trigger name. Each entry in
the `files` array specifies a `relative_path` and `content`—the
server writes them into the trigger's plugin directory.
Use this endpoint to update multi-file plugins (directories with
`__init__.py` and supporting modules). For single-file plugins,
use `PUT /api/v3/plugins/files` instead.
tags:
- Processing engine
x-security-note: Requires an admin token
/api/v3/plugins/files:
post:
operationId: PostPluginsFiles
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginFileRequest'
responses:
'200':
description: Success. The plugin file has been created.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. Admin token required.
summary: Create a plugin file
description: |
Creates a single plugin file in the plugin directory. Writes the
`content` to a file named after `plugin_name`. Does not require an
existing trigger—use this to upload plugin files before creating
triggers that reference them.
tags:
- Processing engine
x-security-note: Requires an admin token
put:
operationId: PutPluginFile
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginFileRequest'
responses:
'200':
description: Success. The plugin file has been updated.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. Admin token required.
'500':
description: >-
Plugin not found. The `plugin_name` does not match any registered
trigger.
summary: Update a plugin file
description: |
Updates a single plugin file for an existing trigger. The
`plugin_name` must match a registered trigger name—the server
resolves the trigger's `plugin_filename` and overwrites that file
with the provided `content`.
To upload a new plugin file before creating a trigger, use
`POST /api/v3/plugins/files` instead. To update a multi-file
plugin directory, use `PUT /api/v3/plugins/directory`.
tags:
- Processing engine
x-security-note: Requires an admin token
/api/v3/query_influxql:
get:
operationId: GetExecuteInfluxQLQuery
parameters:
- $ref: '#/components/parameters/dbQueryParam'
- name: q
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/AcceptQueryHeader'
- name: params
in: query
required: false
schema:
type: string
description: >-
JSON-encoded query parameters. Use this to pass bind parameters to
parameterized queries.
description: JSON-encoded query parameters for parameterized queries.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: QueryRequest
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query
description: |
Executes an InfluxQL query to retrieve data from the specified database.
tags:
- Query data
post:
operationId: PostExecuteQueryInfluxQL
parameters:
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
requestBody:
$ref: '#/components/requestBodies/queryRequestBody'
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query
description: |
Executes an InfluxQL query to retrieve data from the specified database.
tags:
- Query data
/api/v3/query_sql:
get:
operationId: GetExecuteQuerySQL
parameters:
- $ref: '#/components/parameters/db'
- $ref: '#/components/parameters/querySqlParam'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
- name: params
in: query
required: false
schema:
type: string
description: >-
JSON-encoded query parameters. Use this to pass bind parameters to
parameterized queries.
description: JSON-encoded query parameters for parameterized queries.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: QueryRequest
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
example:
results:
- series:
- name: mytable
columns:
- time
- value
values:
- - '2024-02-02T12:00:00Z'
- 42
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute SQL query
description: |
Executes an SQL query to retrieve data from the specified database.
tags:
- Query data
post:
operationId: PostExecuteQuerySQL
parameters:
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
requestBody:
$ref: '#/components/requestBodies/queryRequestBody'
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute SQL query
description: |
Executes an SQL query to retrieve data from the specified database.
tags:
- Query data
/api/v3/write_lp:
post:
operationId: PostWriteLP
parameters:
- name: db
in: query
required: true
schema:
type: string
- name: precision
in: query
required: false
schema:
type: string
- name: accept_partial
in: query
required: false
description: >
Whether to write the valid lines when some lines in the batch are
rejected.
Default is `true`: InfluxDB writes the valid lines and returns `400`
with
`"partial write of line protocol occurred"` and the rejected lines.
With `false`, InfluxDB rejects the whole batch and writes nothing.
schema:
type: boolean
default: true
- name: no_sync
in: query
required: false
schema:
type: boolean
responses:
'204':
description: >-
Success ("No Content"). All data in the batch is written and
queryable.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'400':
description: >
Bad request. Some or all lines were rejected; the body lists each
rejected line.
With `accept_partial=true` (the default), the valid lines are
written and
the error is `"partial write of line protocol occurred"`.
With `accept_partial=false`, nothing is written.
In a database that uses explicit schemas (`schema_mode: explicit`,
Enterprise only), a line that writes an
undeclared table or column is rejected with a message that names it
and points to `/api/v3/configure/table`.
content:
application/json:
examples:
partialWrite:
summary: Partial write (default); line 1 was written
value: |
{
"error": "partial write of line protocol occurred",
"data": [
{
"error_message": "No fields were provided",
"line_number": 2,
"original_line": "home,room=Kitchen te"
}
]
}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
'422':
description: >
Unprocessable entity. The write would exceed a schema limit: the
number of
databases, tables, columns, tag columns, or fields. A partial write
whose
rejected lines hit a limit also returns `422` instead of `400`.
summary: Write line protocol
description: >
Writes line protocol data to the specified database.
Use this endpoint to send data in
[line
protocol](https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/)
format
to InfluxDB. Use query parameters to specify options for writing data.
#### Features
- **Partial writes**: By default (`accept_partial=true`), InfluxDB
writes the
valid lines when some lines in a batch fail. Set `accept_partial=false` to
reject the whole batch instead.
- **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL
synchronization, allowing faster response times but sacrificing durability
guarantees
- **Flexible precision**: Automatic timestamp precision detection with
`precision=auto` (default)
#### Auto precision detection
When you use `precision=auto` or omit the precision parameter, InfluxDB
3
automatically detects the timestamp precision based on the magnitude of
the
timestamp value:
- Timestamps < 5e9 → Second precision (multiplied by 1,000,000,000)
- Timestamps < 5e12 → Millisecond precision (multiplied by 1,000,000)
- Timestamps < 5e15 → Microsecond precision (multiplied by 1,000)
- Larger timestamps → Nanosecond precision (no conversion needed)
#### Related
- [Use the InfluxDB v3 write_lp API to write
data](https://docs.influxdata.com/influxdb3/core/write-data/http-api/v3-write-lp/)
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
tags:
- Write data
x-codeSamples:
- label: cURL - Basic write
lang: Shell
source: >
curl --request POST
"http://localhost:8181/api/v3/write_lp?db=sensors" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain" \
--data-raw "cpu,host=server01 usage=85.2 1638360000000000000"
- label: cURL - Write with millisecond precision
lang: Shell
source: >
curl --request POST
"http://localhost:8181/api/v3/write_lp?db=sensors&precision=ms" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain" \
--data-raw "cpu,host=server01 usage=85.2 1638360000000"
- label: cURL - Asynchronous write with partial acceptance
lang: Shell
source: >
curl --request POST
"http://localhost:8181/api/v3/write_lp?db=sensors&accept_partial=true&no_sync=true&precision=auto"
\
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain" \
--data-raw "cpu,host=server01 usage=85.2
memory,host=server01 used=4096"
- label: cURL - Multiple measurements with tags
lang: Shell
source: >
curl --request POST
"http://localhost:8181/api/v3/write_lp?db=sensors&precision=ns" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-Type: text/plain" \
--data-raw "cpu,host=server01,region=us-west usage=85.2,load=0.75 1638360000000000000
memory,host=server01,region=us-west used=4096,free=12288
1638360000000000000
disk,host=server01,region=us-west,device=/dev/sda1
used=50.5,free=49.5 1638360000000000000"
/health:
get:
operationId: GetHealth
responses:
'200':
description: Service is running. Returns `OK`.
content:
text/plain:
schema:
type: string
example: OK
'401':
description: Unauthorized. Authentication is required.
'403':
description: Forbidden. The token doesn't have permission to call this endpoint.
'500':
description: Service is unavailable.
summary: Health check
description: >
Checks the status of the service.
Returns `OK` if the service is running. This endpoint does not return
version information.
Use the [`/ping`](#operation/GetPing) endpoint to retrieve version
details.
> **Note**: This endpoint requires authentication by default in InfluxDB
3 Core.
tags:
- Server information
/metrics:
get:
operationId: GetMetrics
responses:
'200':
description: Success
summary: Metrics
description: Retrieves Prometheus-compatible server metrics.
tags:
- Server information
/ping:
get:
operationId: GetPing
responses:
'200':
description: Success. The response body contains server information.
headers:
x-influxdb-version:
description: The InfluxDB version number (for example, `3.8.0`).
schema:
type: string
example: 3.8.0
x-influxdb-build:
description: The InfluxDB build type (`Core` or `Enterprise`).
schema:
type: string
example: Core
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The InfluxDB version number.
example: 3.8.0
revision:
type: string
description: The git revision hash for the build.
example: 83b589b883
process_id:
type: string
description: A unique identifier for the server process.
example: b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7
'401':
description: Unauthorized. Authentication is required.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'403':
description: Forbidden. The token doesn't have permission to call this endpoint.
'404':
description: |
Not Found. Returned for HEAD requests.
Use a GET request to retrieve version information.
summary: Ping the server
description: >
Returns version information for the server.
**Important**: Use a GET request. HEAD requests return `404 Not Found`.
The response includes version information in both headers and the JSON
body:
- **Headers**: `x-influxdb-version`, `x-influxdb-build`, and
`cluster-uuid`
(`cluster-uuid` is also returned on a `401`)
- **Body**: JSON object with `version`, `revision`, and `process_id`
> **Note**: This endpoint requires authentication by default in InfluxDB
3 Core.
tags:
- Server information
post:
operationId: ping
responses:
'200':
description: Success. The response body contains server information.
headers:
x-influxdb-version:
description: The InfluxDB version number (for example, `3.8.0`).
schema:
type: string
example: 3.8.0
x-influxdb-build:
description: The InfluxDB build type (`Core` or `Enterprise`).
schema:
type: string
example: Core
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The InfluxDB version number.
example: 3.8.0
revision:
type: string
description: The git revision hash for the build.
example: 83b589b883
process_id:
type: string
description: A unique identifier for the server process.
example: b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7
'401':
description: Unauthorized. Authentication is required.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'403':
description: Forbidden. The token doesn't have permission to call this endpoint.
'404':
description: |
Not Found. Returned for HEAD requests.
Use a GET request to retrieve version information.
summary: Ping the server
description: >-
Returns version information for the server. Accepts POST in addition to
GET.
tags:
- Server information
/query:
get:
operationId: GetV1ExecuteQuery
responses:
'200':
description: |
Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
application/csv:
schema:
type: string
headers:
Content-Type:
description: >
The content type of the response.
Default is `application/json`.
If the `Accept` request header is `application/csv` or
`text/csv`, the `Content-type` response header is
`application/csv`
and the response is formatted as CSV.
schema:
type: string
default: application/json
enum:
- application/json
- application/csv
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query (v1-compatible)
description: >
Executes an InfluxQL query to retrieve data from the specified database.
This endpoint is compatible with InfluxDB 1.x client libraries and
third-party integrations such as Grafana.
Use query parameters to specify the database and the InfluxQL query.
#### Related
- [Use the InfluxDB v1 HTTP query API and InfluxQL to query
data](https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/influxdb-v1-api/)
parameters:
- name: Accept
in: header
schema:
type: string
default: application/json
enum:
- application/json
- application/csv
- text/csv
required: false
description: >
The content type that the client can understand.
If `text/csv` is specified, the `Content-type` response header is
`application/csv` and the response is formatted as CSV.
Returns an error if the format is invalid or non-UTF8.
- in: query
name: chunked
description: |
If true, the response is divided into chunks of size `chunk_size`.
schema:
type: boolean
default: false
- in: query
name: chunk_size
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
schema:
type: integer
default: 10000
- in: query
name: db
description: >-
The database to query. If not provided, the InfluxQL query string
must specify the database.
schema:
type: string
format: InfluxQL
- in: query
name: pretty
description: |
If true, the JSON response is formatted in a human-readable format.
schema:
type: boolean
default: false
- in: query
name: q
description: The InfluxQL query string.
required: true
schema:
type: string
- name: epoch
description: >
Formats timestamps as [unix (epoch)
timestamps](https://docs.influxdata.com/influxdb3/core/reference/glossary/#unix-timestamp)
with the specified precision
instead of [RFC3339
timestamps](https://docs.influxdata.com/influxdb3/core/reference/glossary/#rfc3339-timestamp)
with nanosecond precision.
in: query
schema:
$ref: '#/components/schemas/EpochCompatibility'
- $ref: '#/components/parameters/v1UsernameParam'
- $ref: '#/components/parameters/v1PasswordParam'
- name: rp
in: query
required: false
schema:
type: string
description: >
Retention policy name. Honored but discouraged. InfluxDB 3 doesn't
use retention policies.
- name: Authorization
in: header
required: false
schema:
type: string
description: >
Authorization header for token-based authentication.
Supported schemes:
- `Bearer AUTH_TOKEN` - OAuth bearer token scheme
- `Token AUTH_TOKEN` - InfluxDB v2 token scheme
- `Basic ` - Basic
authentication (username is ignored)
tags:
- Query data
post:
operationId: PostExecuteV1Query
responses:
'200':
description: |
Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
application/csv:
schema:
type: string
headers:
Content-Type:
description: >
The content type of the response.
Default is `application/json`.
If the `Accept` request header is `application/csv` or
`text/csv`, the `Content-type` response header is
`application/csv`
and the response is formatted as CSV.
schema:
type: string
default: application/json
enum:
- application/json
- application/csv
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query (v1-compatible)
description: >
Executes an InfluxQL query to retrieve data from the specified database.
#### Related
- [Use the InfluxDB v1 HTTP query API and InfluxQL to query
data](https://docs.influxdata.com/influxdb3/core/query-data/execute-queries/influxdb-v1-api/)
parameters:
- name: Accept
in: header
schema:
type: string
default: application/json
enum:
- application/json
- application/csv
- text/csv
required: false
description: >
The content type that the client can understand.
If `text/csv` is specified, the `Content-type` response header is
`application/csv` and the response is formatted as CSV.
Returns an error if the format is invalid or non-UTF8.
requestBody:
content:
application/json:
schema:
type: object
properties:
db:
type: string
description: >-
The database to query. If not provided, the InfluxQL query
string must specify the database.
q:
description: The InfluxQL query string.
type: string
chunked:
description: >
If true, the response is divided into chunks of size
`chunk_size`.
type: boolean
chunk_size:
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
type: integer
default: 10000
epoch:
description: >
A unix timestamp precision.
- `h` for hours
- `m` for minutes
- `s` for seconds
- `ms` for milliseconds
- `u` or `µ` for microseconds
- `ns` for nanoseconds
Formats timestamps as [unix (epoch)
timestamps](https://docs.influxdata.com/influxdb3/core/reference/glossary/#unix-timestamp)
with the specified precision
instead of [RFC3339
timestamps](https://docs.influxdata.com/influxdb3/core/reference/glossary/#rfc3339-timestamp)
with nanosecond precision.
enum:
- ns
- u
- µ
- ms
- s
- m
- h
type: string
pretty:
description: >
If true, the JSON response is formatted in a human-readable
format.
type: boolean
required:
- q
application/x-www-form-urlencoded:
schema:
type: object
properties:
db:
type: string
description: >-
The database to query. If not provided, the InfluxQL query
string must specify the database.
q:
description: The InfluxQL query string.
type: string
chunked:
description: >
If true, the response is divided into chunks of size
`chunk_size`.
type: boolean
chunk_size:
description: |
The number of records that will go into a chunk.
This parameter is only used if `chunked=true`.
type: integer
default: 10000
epoch:
description: >
A unix timestamp precision.
- `h` for hours
- `m` for minutes
- `s` for seconds
- `ms` for milliseconds
- `u` or `µ` for microseconds
- `ns` for nanoseconds
Formats timestamps as [unix (epoch)
timestamps](https://docs.influxdata.com/influxdb3/core/reference/glossary/#unix-timestamp)
with the specified precision
instead of [RFC3339
timestamps](https://docs.influxdata.com/influxdb3/core/reference/glossary/#rfc3339-timestamp)
with nanosecond precision.
enum:
- ns
- u
- µ
- ms
- s
- m
- h
type: string
pretty:
description: >
If true, the JSON response is formatted in a human-readable
format.
type: boolean
required:
- q
application/vnd.influxql:
schema:
type: string
description: InfluxQL query string sent as the request body.
tags:
- Query data
/write:
post:
operationId: PostV1Write
responses:
'204':
description: >-
Success ("No Content"). All data in the batch is written and
queryable.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'400':
description: >
Bad request. InfluxDB rejected the whole batch and wrote nothing.
This endpoint doesn't support partial writes: if any line is
invalid, no
lines are written, and an `accept_partial` parameter is ignored.
The body describes the first rejected line.
To write the valid lines of a batch, use `/api/v3/write_lp`.
content:
application/json:
examples:
rejectedBatch:
summary: One invalid line rejects the batch
value: |
{
"error": "line protocol parsing error",
"data": {
"error_message": "No fields were provided",
"line_number": 2,
"original_line": "home,room=Kitchen te"
}
}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
summary: Write line protocol (v1-compatible)
description: >
Writes line protocol to the specified database.
This endpoint provides backward compatibility for InfluxDB 1.x write
workloads using tools such as InfluxDB 1.x client libraries, the
Telegraf `outputs.influxdb` output plugin, or third-party tools.
Use this endpoint to send data in [line
protocol](https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/)
format to InfluxDB.
Use query parameters to specify options for writing data.
#### Related
- [Use compatibility APIs to write
data](https://docs.influxdata.com/influxdb3/core/write-data/http-api/compatibility-apis/)
parameters:
- $ref: '#/components/parameters/dbWriteParam'
- $ref: '#/components/parameters/compatibilityPrecisionParam'
- $ref: '#/components/parameters/v1UsernameParam'
- $ref: '#/components/parameters/v1PasswordParam'
- name: rp
in: query
required: false
schema:
type: string
description: >
Retention policy name. Honored but discouraged. InfluxDB 3 doesn't
use retention policies.
- name: consistency
in: query
required: false
schema:
type: string
description: >
Write consistency level. Ignored by InfluxDB 3. Provided for
compatibility with InfluxDB 1.x clients.
- name: Authorization
in: header
required: false
schema:
type: string
description: >
Authorization header for token-based authentication.
Supported schemes:
- `Bearer AUTH_TOKEN` - OAuth bearer token scheme
- `Token AUTH_TOKEN` - InfluxDB v2 token scheme
- `Basic ` - Basic
authentication (username is ignored)
- name: Content-Type
in: header
description: |
The content type of the request payload.
schema:
$ref: '#/components/schemas/LineProtocol'
required: false
- name: Accept
in: header
description: >
The content type that the client can understand.
Writes only return a response body if they fail (partially or
completely)--for example,
due to a syntax problem or type mismatch.
schema:
type: string
default: application/json
enum:
- application/json
required: false
- $ref: '#/components/parameters/ContentEncoding'
- $ref: '#/components/parameters/ContentLength'
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
tags:
- Write data
components:
parameters:
AcceptQueryHeader:
name: Accept
in: header
schema:
type: string
default: application/json
enum:
- application/json
- application/jsonl
- application/vnd.apache.parquet
- text/csv
required: false
description: |
The content type that the client can understand.
ContentEncoding:
name: Content-Encoding
in: header
description: |
The compression applied to the line protocol in the request payload.
To send a gzip payload, pass `Content-Encoding: gzip` header.
schema:
$ref: '#/components/schemas/ContentEncoding'
required: false
ContentLength:
name: Content-Length
in: header
description: |
The size of the entity-body, in bytes, sent to InfluxDB.
schema:
$ref: '#/components/schemas/ContentLength'
ContentType:
name: Content-Type
description: |
The format of the data in the request body.
in: header
schema:
type: string
enum:
- application/json
required: false
db:
name: db
in: query
required: true
schema:
type: string
description: |
The name of the database.
dbWriteParam:
name: db
in: query
required: true
schema:
type: string
description: |
The name of the database.
InfluxDB creates the database if it doesn't already exist, and then
writes all points in the batch to the database.
dbQueryParam:
name: db
in: query
required: false
schema:
type: string
description: >
The name of the database.
If you provide a query that specifies the database, you can omit the
'db' parameter from your request.
accept_partial:
name: accept_partial
in: query
required: false
schema:
$ref: '#/components/schemas/AcceptPartial'
compatibilityPrecisionParam:
name: precision
in: query
required: false
schema:
$ref: '#/components/schemas/PrecisionWriteCompatibility'
description: The precision for unix timestamps in the line protocol batch.
precisionParam:
name: precision
in: query
required: false
schema:
$ref: '#/components/schemas/PrecisionWrite'
description: The precision for unix timestamps in the line protocol batch.
querySqlParam:
name: q
in: query
required: true
schema:
type: string
format: SQL
description: |
The query to execute.
format:
name: format
in: query
required: false
schema:
$ref: '#/components/schemas/Format'
formatRequired:
name: format
in: query
required: true
schema:
$ref: '#/components/schemas/Format'
v1UsernameParam:
name: u
in: query
required: false
schema:
type: string
description: >
Username for v1 compatibility authentication.
When using Basic authentication or query string authentication, InfluxDB
3 ignores this parameter but allows any arbitrary string for
compatibility with InfluxDB 1.x clients.
v1PasswordParam:
name: p
in: query
required: false
schema:
type: string
description: >
Password for v1 compatibility authentication.
For query string authentication, pass a database token with write
permissions as this parameter.
InfluxDB 3 checks that the `p` value is an authorized token.
requestBodies:
lineProtocolRequestBody:
required: true
content:
text/plain:
schema:
type: string
examples:
line:
summary: Example line protocol
value: measurement,tag=value field=1 1234567890
multiline:
summary: Example line protocol with UTF-8 characters
value: |
measurement,tag=value field=1 1234567890
measurement,tag=value field=2 1234567900
measurement,tag=value field=3 1234568000
queryRequestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequestObject'
schemas:
AdminTokenObject:
type: object
properties:
id:
type: integer
name:
type: string
token:
type: string
hash:
type: string
created_at:
type: string
format: date-time
expiry:
format: date-time
example:
id: 0
name: _admin
token: apiv3_00xx0Xx0xx00XX0x0
hash: 00xx0Xx0xx00XX0x0
created_at: '2025-04-18T14:02:45.331Z'
expiry: null
ContentEncoding:
type: string
enum:
- gzip
- identity
description: >
Content coding.
Use `gzip` for compressed data or `identity` for unmodified,
uncompressed data.
#### Multi-member gzip support
InfluxDB 3 supports multi-member gzip payloads (concatenated gzip files
per [RFC 1952](https://www.rfc-editor.org/rfc/rfc1952)).
This allows you to:
- Concatenate multiple gzip files and send them in a single request
- Maintain compatibility with InfluxDB v1 and v2 write endpoints
- Simplify batch operations using standard compression tools
default: identity
LineProtocol:
type: string
enum:
- text/plain
- text/plain; charset=utf-8
description: >
`text/plain` is the content type for line protocol. `UTF-8` is the
default character set.
default: text/plain; charset=utf-8
ContentLength:
type: integer
description: The length in decimal number of octets.
AcceptPartial:
type: boolean
default: true
description: Accept partial writes.
Format:
type: string
enum:
- json
- csv
- parquet
- json_lines
- jsonl
- pretty
description: |-
The format of data in the response body.
`json_lines` is the canonical name; `jsonl` is accepted as an alias.
PrecisionWriteCompatibility:
enum:
- ms
- s
- us
- u
- ns
- 'n'
type: string
description: >-
The precision for unix timestamps in the line protocol batch.
Use `ms` for milliseconds, `s` for seconds, `us` or `u` for
microseconds, or `ns` or `n` for nanoseconds.
Optional — defaults to nanosecond precision if omitted.
PrecisionWrite:
enum:
- auto
- nanosecond
- microsecond
- millisecond
- second
type: string
description: >
The precision for unix timestamps in the line protocol batch.
Supported values:
- `auto` (default): Automatically detects precision based on timestamp
magnitude
- `nanosecond`: Nanoseconds
- `microsecond`: Microseconds
- `millisecond`: Milliseconds
- `second`: Seconds
QueryRequestObject:
type: object
properties:
db:
description: |
The name of the database to query.
Required if the query (`q`) doesn't specify the database.
type: string
q:
description: The query to execute.
type: string
format:
description: The format of the query results.
type: string
enum:
- json
- csv
- parquet
- json_lines
- jsonl
- pretty
params:
description: |
Additional parameters for the query.
Use this field to pass query parameters.
type: object
additionalProperties: true
required:
- db
- q
example:
db: mydb
q: SELECT * FROM mytable
format: json
params: {}
CreateDatabaseRequest:
type: object
properties:
db:
type: string
pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$
description: >-
The database name. Database names cannot contain underscores (_).
Names must start and end with alphanumeric characters and can
contain hyphens (-) in the middle.
retention_period:
type: string
description: >-
The retention period for the database. Specifies how long data
should be retained.
Use duration format (for example, "1d", "1h", "30m", "7d").
example: 7d
schema_mode:
type: string
enum:
- implicit
- explicit
default: implicit
description: >-
How tables in the database get their schemas. Set at creation and
can't be changed.
- `implicit` (default): writes create tables and columns.
- `explicit`: tables and columns are created only through the
configuration API, and writes that reference an undeclared table or
column are rejected.
Enterprise only; InfluxDB 3 Core returns `400 Bad Request`.
required:
- db
CreateTableRequest:
type: object
properties:
db:
type: string
table:
type: string
tags:
type: array
items:
type: string
fields:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
enum:
- utf8
- int64
- uint64
- float64
- bool
required:
- name
- type
retention_period:
type: string
description: >-
The retention period for the table. Specifies how long data in this
table should be retained.
Use duration format (for example, "1d", "1h", "30m", "7d").
example: 30d
required:
- db
- table
- tags
- fields
DistinctCacheCreateRequest:
type: object
properties:
db:
type: string
table:
type: string
name:
type: string
description: Optional cache name.
columns:
type: array
items:
type: string
max_cardinality:
type: integer
description: Optional maximum cardinality.
max_age:
type: integer
description: Optional maximum age in seconds.
required:
- db
- table
- columns
example:
db: mydb
table: mytable
columns:
- tag1
- tag2
max_cardinality: 1000
max_age: 3600
LastCacheCreateRequest:
type: object
properties:
db:
type: string
table:
type: string
name:
type: string
description: Optional cache name.
key_columns:
type: array
items:
type: string
description: Optional list of key columns.
value_columns:
type: array
items:
type: string
description: Optional list of value columns.
count:
type: integer
description: Optional count.
ttl:
type: integer
description: Optional time-to-live in seconds.
required:
- db
- table
example:
db: mydb
table: mytable
key_columns:
- tag1
value_columns:
- field1
count: 100
ttl: 3600
PatchTableRequest:
type: object
description: >-
Tags and fields to add to an existing table. At least one tag or field
is required.
properties:
db:
type: string
table:
type: string
tags:
type: array
items:
type: string
fields:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
enum:
- utf8
- int64
- uint64
- float64
- bool
required:
- name
- type
required:
- db
- table
ProcessingEngineTriggerRequest:
type: object
properties:
db:
type: string
plugin_filename:
type: string
description: >
The path and filename of the plugin to execute--for example,
`schedule.py` or `endpoints/report.py`.
The path can be absolute or relative to the `--plugin-dir` directory
configured when starting InfluxDB 3.
The plugin file must implement the trigger interface associated with
the trigger's specification.
Prefix the path with `gh:` to fetch the plugin remotely from the
configured `--plugin-repo` instead of reading it from the local
`--plugin-dir`--for example, `gh:examples/wal_plugin/wal_plugin.py`.
Despite the name, `gh:` doesn't require GitHub--`--plugin-repo`
accepts any HTTP/HTTPS URL that serves raw plugin files.
For defaults, fetch behavior, and limitations, see [Use example
plugins](https://docs.influxdata.com/influxdb3/core/plugins/#use-example-plugins).
trigger_name:
type: string
trigger_settings:
allOf:
- $ref: '#/components/schemas/TriggerSettings'
trigger_specification:
description: >
Specifies when and how the processing engine trigger should be
invoked.
## Supported trigger specifications:
### Cron-based scheduling
Format: `cron:CRON_EXPRESSION`
Uses extended (6-field) cron format (second minute hour day_of_month
month day_of_week):
```
┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31)
│ │ │ │ ┌───────────── month (1-12)
│ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │ │
* * * * * *
```
Examples:
- `cron:0 0 6 * * 1-5` - Every weekday at 6:00 AM
- `cron:0 30 14 * * 5` - Every Friday at 2:30 PM
- `cron:0 0 0 1 * *` - First day of every month at midnight
### Interval-based scheduling
Format: `every:DURATION`
Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d`
(days), `w` (weeks), `M` (months), `y` (years):
- `every:30s` - Every 30 seconds
- `every:5m` - Every 5 minutes
- `every:1h` - Every hour
- `every:1d` - Every day
- `every:1w` - Every week
- `every:1M` - Every month
- `every:1y` - Every year
**Maximum interval**: 1 year
### Table-based triggers
- `all_tables` - Triggers on write events to any table in the
database
- `table:TABLE_NAME` - Triggers on write events to a specific table
### On-demand triggers
Format: `request:REQUEST_PATH`
Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual
invocation:
- `request:hello-world` - Creates endpoint
`/api/v3/engine/hello-world`
- `request:data-export` - Creates endpoint
`/api/v3/engine/data-export`
pattern: >-
^(cron:[0-9
*,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|request:[a-zA-Z0-9_-]+)$
example: cron:0 0 6 * * 1-5
trigger_arguments:
type: object
additionalProperties:
type: string
description: >
Optional, plugin-specific arguments passed to the plugin entry point
as its `args` dictionary.
Provide string key-value pairs. Omit this field to pass `None` as
`args`.
Refer to the plugin documentation for supported argument names and
values.
example:
threshold: '90'
target_table: alerts
disabled:
type: boolean
default: false
description: Whether the trigger is disabled.
required:
- db
- plugin_filename
- trigger_name
- trigger_specification
TriggerSettings:
type: object
properties:
run_async:
type: boolean
default: false
description: >
Whether invocations of the trigger can run concurrently.
If `false`, invocations run serially--each invocation must finish
before the next one starts.
If `true`, invocations can run concurrently, up to the
`--async-trigger-concurrency-limit`
server option (default: `8`).
error_behavior:
type: string
default: log
enum:
- log
- retry
- disable
description: >
How the trigger responds when the plugin returns an error:
- `log`: Log the error and keep the trigger active.
- `retry`: Retry the failed invocation with exponential backoff (up
to 5 attempts), then log the failure. Errors identified as permanent
aren't retried.
- `disable`: Disable the trigger until you manually re-enable it.
WALPluginTestRequest:
type: object
description: |
Request body for testing a write-ahead logging (WAL) plugin.
properties:
filename:
type: string
description: |
The path and filename of the plugin to test.
database:
type: string
description: |
The database name to use for the test.
input_lp:
type: string
description: |
Line protocol data to use as input for the test.
cache_name:
type: string
description: |
Optional name of the cache to use in the test.
input_arguments:
type: object
additionalProperties:
type: string
description: |
Optional key-value pairs of arguments to pass to the plugin.
required:
- filename
- database
- input_lp
SchedulePluginTestRequest:
type: object
description: |
Request body for testing a scheduling plugin.
properties:
filename:
type: string
description: |
The path and filename of the plugin to test.
database:
type: string
description: |
The database name to use for the test.
schedule:
type: string
description: |
Optional schedule specification in cron or interval format.
cache_name:
type: string
description: |
Optional name of the cache to use in the test.
input_arguments:
type: object
additionalProperties:
type: string
description: |
Optional key-value pairs of arguments to pass to the plugin.
required:
- filename
- database
PluginFileRequest:
type: object
description: |
Request body for updating a plugin file.
properties:
plugin_name:
type: string
description: |
The name of the plugin file to update.
content:
type: string
description: |
The content of the plugin file.
required:
- plugin_name
- content
PluginDirectoryRequest:
type: object
description: |
Request body for updating plugin directory with multiple files.
properties:
plugin_name:
type: string
description: |
The name of the plugin directory to update.
files:
type: array
items:
$ref: '#/components/schemas/PluginFileEntry'
description: |
List of plugin files to include in the directory.
required:
- plugin_name
- files
PluginFileEntry:
type: object
description: |
Represents a single file in a plugin directory.
properties:
content:
type: string
description: |
The content of the file.
relative_path:
type: string
description: The relative path of the file within the plugin directory.
required:
- relative_path
- content
ShowDatabasesResponse:
type: object
properties:
databases:
type: array
items:
type: string
QueryResponse:
type: object
properties:
results:
type: array
items:
type: object
example:
results:
- series:
- name: mytable
columns:
- time
- value
values:
- - '2024-02-02T12:00:00Z'
- 42
ErrorMessage:
type: object
properties:
error:
type: string
data:
type: object
nullable: true
EpochCompatibility:
description: |
A unix timestamp precision.
- `h` for hours
- `m` for minutes
- `s` for seconds
- `ms` for milliseconds
- `u` or `µ` for microseconds
- `ns` for nanoseconds
enum:
- ns
- u
- µ
- ms
- s
- m
- h
type: string
UpdateDatabaseRequest:
type: object
properties:
retention_period:
type: string
description: >
The retention period for the database. Specifies how long data
should be retained.
Use duration format (for example, "1d", "1h", "30m", "7d").
example: 7d
description: Request schema for updating database configuration.
responses:
Unauthorized:
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
BadRequest:
description: |
Request failed. Possible reasons:
- Invalid database name
- Malformed request body
- Invalid timestamp precision
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
Forbidden:
description: Access denied.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
headers:
ClusterUUID:
description: |
The catalog UUID of the InfluxDB instance.
This header is included in all HTTP API responses and enables you to:
- Identify which cluster instance handled the request
- Monitor deployments across multiple InfluxDB instances
- Debug and troubleshoot distributed systems
schema:
type: string
format: uuid
example: 01234567-89ab-cdef-0123-456789abcdef
securitySchemes:
BasicAuthentication:
type: http
scheme: basic
description: >-
Use the `Authorization` header with the `Basic` scheme to authenticate
v1 API requests.
Works with v1 compatibility [`/write`](#operation/PostV1Write) and
[`/query`](#operation/GetV1ExecuteQuery) endpoints in InfluxDB 3.
When authenticating requests, InfluxDB 3 checks that the `password` part
of the decoded credential is an authorized token
and ignores the `username` part of the decoded credential.
### Syntax
```http
Authorization: Basic
```
### Example
```bash
curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \
--user "":"AUTH_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB 3 Core database
- **`AUTH_TOKEN`**: an admin token or database token authorized for the
database
QuerystringAuthentication:
type: apiKey
in: query
name: u=&p=
description: >-
Use InfluxDB 1.x API parameters to provide credentials through the query
string for v1 API requests.
Querystring authentication works with v1-compatible
[`/write`](#operation/PostV1Write) and
[`/query`](#operation/GetV1ExecuteQuery) endpoints.
When authenticating requests, InfluxDB 3 checks that the `p`
(_password_) query parameter is an authorized token
and ignores the `u` (_username_) query parameter.
### Syntax
```http
https://localhost:8181/query/?[u=any]&p=AUTH_TOKEN
https://localhost:8181/write/?[u=any]&p=AUTH_TOKEN
```
### Examples
```bash
curl
"http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=AUTH_TOKEN"
\
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB 3 Core database
- **`AUTH_TOKEN`**: an admin token or database token authorized for the
database
```bash
#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 HTTP API
#######################################
# Use authentication query parameters:
# ?p=AUTH_TOKEN
#######################################
curl --get "http://localhost:8181/query" \
--data-urlencode "p=AUTH_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
```
Replace the following:
- **`DATABASE_NAME`**: the database to query
- **`AUTH_TOKEN`**: a database token with sufficient permissions to the
database
BearerAuthentication:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Use the OAuth Bearer authentication
scheme to provide an authorization token to InfluxDB 3.
Bearer authentication works with all endpoints.
In your API requests, send an `Authorization` header.
For the header value, provide the word `Bearer` followed by a space and
a database token.
### Syntax
```http
Authorization: Bearer AUTH_TOKEN
```
### Example
```bash
curl http://localhost:8181/api/v3/query_influxql \
--header "Authorization: Bearer AUTH_TOKEN"
```
TokenAuthentication:
description: >-
Use InfluxDB v2 Token authentication to provide an authorization token
to InfluxDB 3.
The v2 Token scheme works with v1 and v2 compatibility endpoints in
InfluxDB 3.
In your API requests, send an `Authorization` header.
For the header value, provide the word `Token` followed by a space and a
database token.
The word `Token` is case-sensitive.
### Syntax
```http
Authorization: Token AUTH_TOKEN
```
### Example
```sh
########################################################
# Use the Token authentication scheme with /api/v2/write
# to write data.
########################################################
curl --request post
"http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Token AUTH_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'
```
in: header
name: Authorization
type: apiKey