openapi: 3.0.3
info:
title: InfluxDB 3 Enterprise API Service
description: >
The InfluxDB HTTP API for InfluxDB 3 Enterprise provides a programmatic
interface for
interacting with InfluxDB 3 Enterprise databases and resources.
Use this API to:
- Write data to InfluxDB 3 Enterprise 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 Enterprise 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-enterprise-openapi.yaml)
version: v3.9.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:1259b96096eab6c8dbf3f76c974924f124e9b3e08eedc6b0c9a66d3108857c52
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 Enterprise API URL
variables:
baseurl:
enum:
- localhost:8181
default: localhost:8181
description: InfluxDB 3 Enterprise URL
security:
- BearerAuthentication: []
- TokenAuthentication: []
- BasicAuthentication: []
- QuerystringAuthentication: []
tags:
- name: Authentication
description: >-
Use one of the following schemes to authenticate to the InfluxDB 3
Enterprise 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/enterprise/guides/api-compatibility/v1/
- title: Manage tokens
href: https://docs.influxdata.com/influxdb3/enterprise/admin/tokens/
- name: Export data (beta)
description: >-
Export data from InfluxDB 3 Enterprise databases. List databases, tables,
export windows, and retrieve window data for data migration and backup
workflows.
x-related:
- title: Export data
href: https://docs.influxdata.com/influxdb3/enterprise/admin/export/
- name: Database
description: Create, list, and delete databases in InfluxDB 3 Enterprise.
x-related:
- title: Manage databases
href: https://docs.influxdata.com/influxdb3/enterprise/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 Enterprise 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/enterprise/processing-engine/
- name: Query data
description: Query data stored in InfluxDB 3 Enterprise using SQL or InfluxQL.
x-related:
- title: Query data
href: https://docs.influxdata.com/influxdb3/enterprise/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, see the [Get
started](https://docs.influxdata.com/influxdb3/enterprise/get-started/)
guide.
x-traitTag: true
- name: Server information
description: >-
Retrieve server metrics, health status, and version information for
InfluxDB 3 Enterprise.
- name: Table
description: Manage table schemas in an InfluxDB 3 Enterprise database.
x-related:
- title: Manage tables
href: https://docs.influxdata.com/influxdb3/enterprise/admin/tables/
- name: Auth token
description: >-
Create and manage tokens used for authenticating and authorizing access to
InfluxDB 3 Enterprise resources.
x-related:
- title: Manage tokens
href: https://docs.influxdata.com/influxdb3/enterprise/admin/tokens/
- name: Write data
description: >-
Write data to InfluxDB 3 Enterprise 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/enterprise/write-data/http-api/
- title: Line protocol reference
href: >-
https://docs.influxdata.com/influxdb3/enterprise/reference/syntax/line-protocol/
- name: Backup and restore
description: >
Create, list, retrieve, and delete backups, and start, list, and cancel
restores.
Backup and restore endpoints require the upgraded storage engine, enabled
with the `--use-pacha-tree` flag, and a compactor node that runs the
backup and restore engine. If the storage engine is not present on the
node, these endpoints return `503 Service Unavailable`. All endpoints
require an admin (operator) token or admin user.
Backups and restores run asynchronously: starting one returns immediately
with a handle that you poll for status. Only one restore can run
cluster-wide at a time.
- name: Bulk import
description: >
Upload Parquet files for bulk import into existing tables and list the
status of bulk import jobs.
Bulk import endpoints require the upgraded storage engine, enabled with
the `--use-pacha-tree` flag, and a compactor node that runs the bulk
import scheduler to complete the import. All endpoints require an admin
(operator) token.
- name: Data deletion
description: |
Manage row-delete requests.
These endpoints are only available in InfluxDB 3 Enterprise.
- name: User management
description: >
Manage users and their role assignments, and look up users and roles.
These endpoints are only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by starting the server with
`--without-user-auth false`.
- 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/enterprise/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/enterprise/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
Enterprise.
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/enterprise/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/enterprise/write-data/http-api/compatibility-apis/)
- v1 and v2 write endpoints
- [Use the v1 HTTP query
API](https://docs.influxdata.com/influxdb3/enterprise/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 Enterprise.
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
x-compatibility-version: v2
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.
'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/enterprise/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/enterprise/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.
- name: accept_partial
in: query
required: false
schema:
$ref: '#/components/schemas/AcceptPartial'
- $ref: '#/components/parameters/compatibilityPrecisionParam'
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
tags:
- Write data
/api/v3/export/databases:
get:
operationId: GetExportDatabases
summary: List databases available for export (beta)
description: >
Returns a list of databases that have compacted data available for
Parquet export.
> **Beta**: This endpoint requires the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
> (`--use-pacha-tree` flag). The performance upgrade preview is a beta
feature
> and **should not be used for production workloads**.
responses:
'200':
description: Success. Returns a list of database names.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Export data (beta)
/api/v3/export/tables:
get:
operationId: GetExportTables
summary: List tables available for export (beta)
description: >
Returns a list of tables in a database that have compacted data
available for Parquet export.
> **Beta**: This endpoint requires the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
> (`--use-pacha-tree` flag). The performance upgrade preview is a beta
feature
> and **should not be used for production workloads**.
parameters:
- $ref: '#/components/parameters/db'
responses:
'200':
description: Success. Returns a list of table names.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
tags:
- Export data (beta)
/api/v3/export/windows:
get:
operationId: GetExportWindows
summary: List compacted windows for a table (beta)
description: >
Returns a list of compacted 24-hour UTC windows for a table.
Each window represents a time range of compacted data that can be
exported as Parquet.
> **Beta**: This endpoint requires the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
> (`--use-pacha-tree` flag). The performance upgrade preview is a beta
feature
> and **should not be used for production workloads**.
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
description: The table name.
responses:
'200':
description: Success. Returns a list of compacted 24-hour windows.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database or table not found.
tags:
- Export data (beta)
/api/v3/export/window_data:
get:
operationId: GetExportWindowData
summary: Export window data as Parquet (beta)
description: >
Downloads compacted data for the specified windows as a tar archive
containing Parquet files.
> **Beta**: This endpoint requires the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
> (`--use-pacha-tree` flag). The performance upgrade preview is a beta
feature
> and **should not be used for production workloads**.
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
description: The table name.
- name: windows
in: query
required: false
schema:
type: string
description: >
Comma-separated list of window dates to export (for example,
`2026-01-15,2026-01-16`).
If omitted, exports all available windows.
responses:
'200':
description: Success. Returns a tar archive containing Parquet files.
content:
application/x-tar:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database, table, or window not found.
tags:
- Export data (beta)
/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
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.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatabaseRequest'
tags:
- Database
put:
operationId: update_database
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
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
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
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.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LastCacheCreateRequest'
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.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
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/enterprise/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
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.
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.
tags:
- Table
post:
operationId: PostConfigureTable
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.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableRequest'
tags:
- Table
put:
operationId: PatchConfigureTable
responses:
'200':
description: Success. The table has been updated.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Table not found.
summary: Update a table
description: |
Updates table configuration, such as retention period.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTableRequest'
tags:
- Table
x-enterprise-only: true
/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.
tags:
- Authentication
- Auth token
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
/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/enterprise/configure/file_index:
post:
operationId: configure_file_index_create
summary: Create a file index
description: >-
Creates a file index for a database or table.
A file index improves query performance by indexing data files based on
specified columns, enabling the query engine to skip irrelevant files
during query execution.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FileIndexCreateRequest'
responses:
'200':
description: Success. The file index has been created.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database or table not found.
tags:
- Database
- Table
delete:
operationId: configure_file_index_delete
summary: Delete a file index
description: |-
Deletes a file index from a database or table.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FileIndexDeleteRequest'
responses:
'200':
description: Success. The file index has been deleted.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database, table, or file index not found.
tags:
- Database
- Table
/api/v3/enterprise/configure/node/stop:
post:
operationId: stop_node
summary: Mark a node as stopped
description: >-
Marks a node as stopped in the catalog, freeing up the licensed cores it
was using for other nodes.
Use this endpoint after you have already stopped the physical instance
(for example, using `kill` or stopping the container). This endpoint
does not shut down the running process — you must stop the instance
first.
When the node is marked as stopped:
1. Licensed cores from the stopped node are freed for reuse
2. Other nodes in the cluster see the update after their catalog sync
interval
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 stop
node](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/stop/node/)
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StopNodeRequest'
responses:
'200':
description: Success. The node has been marked as stopped.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Node not found.
tags:
- Server information
/api/v3/enterprise/configure/table/retention_period:
post:
operationId: create_or_update_retention_period_for_table
summary: Set table retention period
description: >-
Sets or updates the retention period for a specific table.
Use this endpoint to control how long data in a table is retained
independently of the database-level retention period.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 update
table](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/update/table/)
x-enterprise-only: true
parameters:
- name: db
in: query
required: true
schema:
type: string
description: The database name.
- name: table
in: query
required: true
schema:
type: string
description: The table name.
- name: duration
in: query
required: true
schema:
type: string
description: >-
The retention period as a human-readable duration (for example,
"30d", "24h", "1y").
responses:
'204':
description: Success. The table retention period has been set.
'400':
description: Bad request. Invalid duration format.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database or table not found.
tags:
- Table
delete:
operationId: delete_retention_period_for_table
summary: Clear table retention period
description: >-
Removes the retention period from a specific table, reverting to the
database-level retention period (or infinite retention if no
database-level retention is set).
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 update
table](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/update/table/)
x-enterprise-only: true
parameters:
- name: db
in: query
required: true
schema:
type: string
description: The database name.
- name: table
in: query
required: true
schema:
type: string
description: The table name.
responses:
'204':
description: Success. The table retention period has been cleared.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database or table not found.
tags:
- Table
/api/v3/enterprise/configure/token:
post:
operationId: PostCreateResourceToken
summary: Create a resource token
description: >
Creates a resource (fine-grained permissions) token.
A resource token is a token that has access to specific resources in the
system.
This endpoint is only available in InfluxDB 3 Enterprise.
responses:
'201':
description: |
Success. The resource token has been created.
The response body contains the token string and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Auth token
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTokenWithPermissionsRequest'
/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: create_plugin_file
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.
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.
tags:
- Processing engine
x-security-note: Requires an admin token
put:
operationId: PutPluginFile
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`.
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.
tags:
- Processing engine
x-security-note: Requires an admin token
/api/v3/query_influxql:
get:
operationId: GetExecuteInfluxQLQuery
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.
With the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
enabled
(`--use-pacha-tree` flag), queries automatically merge results from
Parquet and
`.pt` files (hybrid query mode).
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.
tags:
- Query data
post:
operationId: PostExecuteQueryInfluxQL
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.
With the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
enabled
(`--use-pacha-tree` flag), queries automatically merge results from
Parquet and
`.pt` files (hybrid query mode).
parameters:
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
requestBody:
$ref: '#/components/requestBodies/queryRequestBody'
tags:
- Query data
/api/v3/query_sql:
get:
operationId: GetExecuteQuerySQL
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.
With the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
enabled
(`--use-pacha-tree` flag), queries automatically merge results from
Parquet and
`.pt` files (hybrid query mode). Use the
[`/api/v3/query_sql_telemetry`](#operation/GetQuerySQLTelemetry)
endpoint after executing
a query to retrieve detailed execution statistics.
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.
tags:
- Query data
post:
operationId: PostExecuteQuerySQL
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.
With the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
enabled
(`--use-pacha-tree` flag), queries automatically merge results from
Parquet and
`.pt` files (hybrid query mode). Use the
[`/api/v3/query_sql_telemetry`](#operation/GetQuerySQLTelemetry)
endpoint after executing
a query to retrieve detailed execution statistics.
parameters:
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
requestBody:
$ref: '#/components/requestBodies/queryRequestBody'
tags:
- Query data
/api/v3/query_sql_telemetry:
get:
operationId: GetQuerySQLTelemetry
summary: Get query telemetry (beta)
description: >
Returns detailed execution statistics for the most recent SQL query,
including per-chunk I/O,
cache hit rates, and timing breakdowns.
Use this endpoint after executing a query to analyze performance.
> **Beta**: This endpoint requires the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
> (`--use-pacha-tree` flag). The performance upgrade preview is a beta
feature
> and **should not be used for production workloads**.
For more information, see
[Query
telemetry](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/monitor/#query-telemetry).
responses:
'200':
description: Success. Returns query telemetry data.
content:
application/json:
schema:
type: object
properties:
query_id:
type: string
description: Unique identifier for the query.
execution_time_us:
type: integer
description: Total execution time in microseconds.
chunks:
type: array
description: Per-chunk statistics.
items:
type: object
properties:
chunk_id:
type: string
files_scanned:
type: integer
blocks_processed:
type: integer
rows_read:
type: integer
rows_returned:
type: integer
bytes_read:
type: integer
cache_stats:
type: object
description: Cache hit rates by type.
properties:
gen0_hits:
type: integer
gen0_misses:
type: integer
compacted_hits:
type: integer
compacted_misses:
type: integer
example:
query_id: q_12345
execution_time_us: 4523
chunks:
- chunk_id: c_1
files_scanned: 3
blocks_processed: 12
rows_read: 24000
rows_returned: 150
bytes_read: 1234567
cache_stats:
gen0_hits: 5
gen0_misses: 1
compacted_hits: 8
compacted_misses: 2
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Query data
post:
operationId: PostQuerySQLTelemetry
summary: Get query telemetry (beta)
description: >
Returns detailed execution statistics for the most recent SQL query,
including per-chunk I/O,
cache hit rates, and timing breakdowns.
Use this endpoint after executing a query to analyze performance.
> **Beta**: This endpoint requires the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
> (`--use-pacha-tree` flag). The performance upgrade preview is a beta
feature
> and **should not be used for production workloads**.
For more information, see
[Query
telemetry](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/monitor/#query-telemetry).
responses:
'200':
description: Success. Returns query telemetry data.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Query data
/api/v3/write_lp:
post:
operationId: PostWriteLP
parameters:
- $ref: '#/components/parameters/dbWriteParam'
- $ref: '#/components/parameters/accept_partial'
- $ref: '#/components/parameters/precisionParam'
- name: no_sync
in: query
schema:
$ref: '#/components/schemas/NoSync'
- 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'
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.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
'422':
description: Unprocessable entity.
summary: Write line protocol
description: >
Writes line protocol to the specified database.
This is the native InfluxDB 3 Enterprise write endpoint that provides
enhanced control
over write behavior with advanced parameters for high-performance and
fault-tolerant operations.
Use this endpoint to send data in [line
protocol](https://docs.influxdata.com/influxdb3/enterprise/reference/syntax/line-protocol/)
format
to InfluxDB. Use query parameters to specify options for writing data.
#### Features
- **Partial writes**: Use `accept_partial=true` to allow partial success
when some lines in a batch fail
- **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)
#### Column families (performance upgrade preview)
With the [performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
enabled
(`--use-pacha-tree` flag), you can assign fields to column families
using the `::` delimiter
in field names. The portion before `::` is the family name; everything
after is the field name.
```txt
metrics,host=sA cpu::usage_user=55.2,cpu::usage_sys=12.1,mem::free=2048i
1000000000
```
Fields in the same family are stored together on disk. For wide tables,
this reduces I/O
by letting queries read only the families they need. Fields written
without `::` are assigned
to auto-generated families.
For more information, see [Column
families](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/#column-families).
#### 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 to
convert to nanoseconds)
- 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/enterprise/write-data/http-api/v3-write-lp/)
- [Performance upgrade
preview](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/)
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.
'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 Enterprise.
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: Enterprise
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.
'404':
description: |
Not Found. Returned for HEAD requests.
Use a GET request to retrieve version information.
x-client-method: ping
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` and `x-influxdb-build`
- **Body**: JSON object with `version`, `revision`, and `process_id`
> **Note**: This endpoint requires authentication by default in InfluxDB
3 Enterprise.
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: Enterprise
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.
'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
x-compatibility-version: v1
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/enterprise/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/enterprise/reference/glossary/#unix-timestamp)
with the specified precision
instead of [RFC3339
timestamps](https://docs.influxdata.com/influxdb3/enterprise/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
x-compatibility-version: v1
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/enterprise/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/enterprise/reference/glossary/#unix-timestamp)
with the specified precision
instead of [RFC3339
timestamps](https://docs.influxdata.com/influxdb3/enterprise/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/enterprise/reference/glossary/#unix-timestamp)
with the specified precision
instead of [RFC3339
timestamps](https://docs.influxdata.com/influxdb3/enterprise/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
x-compatibility-version: v1
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 (a _partial write_) or all of the data from the
batch was rejected and not written.
If a partial write occurred, then some points from the batch are
written and queryable.
The response body:
- indicates if a partial write occurred or all data was rejected.
- contains details about the [rejected points](https://docs.influxdata.com/influxdb3/enterprise/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
content:
application/json:
examples:
rejectedAllPoints:
summary: Rejected all points in the batch
value: |
{
"error": "write of line protocol failed",
"data": [
{
"original_line": "dquote> home,room=Kitchen temp=hi",
"line_number": 2,
"error_message": "No fields were provided"
}
]
}
partialWriteErrorWithRejectedPoints:
summary: Partial write rejected some points in the batch
value: |
{
"error": "partial write of line protocol occurred",
"data": [
{
"original_line": "dquote> home,room=Kitchen temp=hi",
"line_number": 2,
"error_message": "No fields were provided"
}
]
}
'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/enterprise/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/enterprise/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
/api/v3/configure/query_concurrency_limit:
get:
operationId: get_query_concurrency_limit
summary: Get the query concurrency limit
description: >-
Returns the current runtime limit on the maximum number of queries that
can run concurrently. When the limit is set to the maximum allowed
value, `maxConcurrentQueries` is omitted from the response.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
responses:
'200':
description: Success. Returns the current query concurrency limit.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConcurrencyLimitResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Server information
put:
operationId: set_query_concurrency_limit
summary: Set the query concurrency limit
description: >-
Sets the runtime limit on the maximum number of queries that can run
concurrently. Omit `max_concurrent_queries` (or set it to `null`) to
restore the limit configured at server startup.
Values below 16 are rejected unless `force=true` is set in the query
string. A value of `0` is invalid, and values above the maximum allowed
limit are rejected.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
parameters:
- name: force
in: query
required: false
description: >-
Set to `true` to allow setting `max_concurrent_queries` to a value
below the minimum of 16.
schema:
type: boolean
default: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetQueryConcurrencyLimitRequest'
responses:
'204':
description: No content. The query concurrency limit was updated.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Server information
delete:
operationId: reset_query_concurrency_limit
summary: Reset the query concurrency limit
description: >-
Resets the runtime query concurrency limit to the value configured at
server startup.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
responses:
'204':
description: No content. The query concurrency limit was reset.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Server information
/api/v3/enterprise/backup:
post:
operationId: create_backup
summary: Start a backup
description: >-
Registers and asynchronously starts a full backup. Returns immediately
with the resolved backup name and an in-progress acknowledgement.
Backups run asynchronously. Poll [List backups](#operation/list_backups)
or [Get a backup](#operation/get_backup) to track progress.
Requires an admin (operator) token. Requires the upgraded storage engine
(enabled with the `--use-pacha-tree` flag) present on a compactor node;
otherwise the endpoint returns `503 Service Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBackupRequest'
responses:
'202':
description: Accepted. The backup has started.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBackupResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: >-
Conflict. A backup with that name already exists and `force` is
`false`, or a duplicate backup job is already in flight.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: >-
Service unavailable. The backup engine is not present on this node
(not a compactor node).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
delete:
operationId: cancel_backup
summary: Cancel a running backup
description: >-
Cancels an in-progress backup job by name.
Requires an admin (operator) token or admin user. Requires the upgraded
storage engine (enabled with the `--use-pacha-tree` flag) present on a
compactor node; otherwise the endpoint returns `503 Service
Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelBackupRequest'
responses:
'200':
description: Success. The cancellation has been accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelBackupResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No backup is running with that name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: >-
Service unavailable. The backup engine is not present on this node
(not a compactor node).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
get:
operationId: list_backups
summary: List backups
description: >-
Lists all full backups.
Requires an admin (operator) token. Requires the upgraded storage engine
(enabled with the `--use-pacha-tree` flag) present on a compactor node;
otherwise the endpoint returns `503 Service Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
responses:
'200':
description: Success. Returns the list of backups.
content:
application/json:
schema:
$ref: '#/components/schemas/ListBackupsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
description: Internal server error. Listing backups failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: >-
Service unavailable. The backup engine is not present on this node
(not a compactor node).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
/api/v3/enterprise/backup/{name}:
get:
operationId: get_backup
summary: Get a backup
description: >-
Returns a single backup's manifest.
Requires an admin (operator) token or admin user. Requires the upgraded
storage engine (enabled with the `--use-pacha-tree` flag) present on a
compactor node; otherwise the endpoint returns `503 Service
Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
parameters:
- name: name
in: path
required: true
schema:
type: string
description: The backup name. URL-encoded names are decoded by the server.
responses:
'200':
description: Success. Returns the backup manifest.
content:
application/json:
schema:
$ref: '#/components/schemas/GetBackupResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No backup exists with that name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: >-
Service unavailable. The backup engine is not present on this node
(not a compactor node).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
delete:
operationId: delete_backup
summary: Delete a backup
description: >-
Deletes a backup by name.
Requires an admin (operator) token or admin user. Requires the upgraded
storage engine (enabled with the `--use-pacha-tree` flag) present on a
compactor node; otherwise the endpoint returns `503 Service
Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
parameters:
- name: name
in: path
required: true
schema:
type: string
description: The backup name. URL-encoded names are decoded by the server.
responses:
'200':
description: Success. The backup has been deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteBackupResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No backup exists with that name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'409':
description: >-
Conflict. The backup is in progress and cannot be deleted, or the
backup chain is in a conflicting state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: >-
Service unavailable. The backup engine is not present on this node
(not a compactor node).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
/api/v3/enterprise/import:
post:
operationId: create_bulk_import
summary: Upload a Parquet file for bulk import
description: >-
Uploads a Parquet file, and optional column metadata, for bulk import
into an existing table. The compactor node asynchronously picks up and
imports the file. Returns the staged import job info synchronously after
the upload is staged.
Requires an admin (operator) token. Requires the upgraded storage engine
(enabled with the `--use-pacha-tree` flag); the compactor node runs the
bulk import scheduler that completes the import.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/BulkImportUploadRequest'
responses:
'200':
description: Success. The upload has been staged for import.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadedImportInfo'
'400':
description: >-
Bad request. Possible reasons: missing multipart boundary; missing
`file_bytes`, `database`, or `table`; unparseable multipart; invalid
or empty Parquet; malformed `column_metadata`; column type or
mapping mismatch; or a missing time column.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. The target database or table does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'500':
description: >-
Internal server error. Object store, status write, or catalog
failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Bulk import
get:
operationId: list_bulk_imports
summary: List bulk import statuses
description: >-
Lists the status of all uploaded bulk import jobs.
Requires an admin (operator) token. Requires the upgraded storage engine
(enabled with the `--use-pacha-tree` flag).
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
responses:
'200':
description: Success. Returns the list of bulk import statuses.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UploadedImportInfo'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
description: Internal server error. Object store or read failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Bulk import
/api/v3/enterprise/restore:
post:
operationId: create_restore
summary: Start a restore
description: >-
Registers and asynchronously starts a restore from a named backup.
Returns a `restore_id` handle for tracking and cancellation.
Restores run asynchronously. Poll [Get a
restore](#operation/get_restore) to track progress. Only one restore can
run cluster-wide at a time; if a restore is already running, this
endpoint returns `409 Conflict`.
Requires an admin (operator) token. Requires the upgraded storage engine
(enabled with the `--use-pacha-tree` flag) present on a compactor node;
otherwise the endpoint returns `503 Service Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRestoreRequest'
responses:
'202':
description: Accepted. The restore has started.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRestoreResponse'
'400':
description: Bad request. `backup_name` is empty.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: >-
Conflict. A restore is already running. Only one restore can run at
a time.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: >-
Service unavailable. The restore engine is not present on this node,
or the restore lease could not be acquired.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
get:
operationId: list_restores
summary: List restores
description: >-
Lists every restore for the cluster, newest first, including in-flight
and completed restores.
Requires an admin (operator) token or admin user. Requires the upgraded
storage engine (enabled with the `--use-pacha-tree` flag) present on a
compactor node; otherwise the endpoint returns `503 Service
Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
responses:
'200':
description: Success. Returns the list of restores.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRestoresResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
description: Internal server error. Listing restores failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: Service unavailable. The restore engine is not present on this node.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
/api/v3/enterprise/restore/{id}:
get:
operationId: get_restore
summary: Get a restore
description: >-
Reports a restore's state by `restore_id`. Reads the persisted manifest,
so it works for in-flight and completed restores.
Requires an admin (operator) token or admin user. Requires the upgraded
storage engine (enabled with the `--use-pacha-tree` flag) present on a
compactor node; otherwise the endpoint returns `503 Service
Unavailable`.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The `restore_id` returned when the restore started.
responses:
'200':
description: Success. Returns the restore status.
content:
application/json:
schema:
$ref: '#/components/schemas/GetRestoreResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No restore exists with that ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'503':
description: Service unavailable. The restore engine is not present on this node.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
delete:
operationId: cancel_restore
summary: Cancel a running restore
description: >-
Cancels an in-flight restore by `restore_id`.
Requires an admin (operator) token or admin user. Requires the upgraded
storage engine (enabled with the `--use-pacha-tree` flag) present on a
compactor node.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The `restore_id` returned when the restore started.
responses:
'204':
description: No content. The cancellation has been accepted.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >-
Not found. No restore exists with that ID, the restore is already
completed, or the restore engine is not present on this node.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Backup and restore
/api/v3/roles/{id}/permissions:
get:
operationId: get_role_permissions
summary: Get a role's permissions
description: >-
Returns the permissions granted to the role with the specified ID.
Requires a token or user with permission to read roles.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
description: The ID of the role.
schema:
type: integer
format: int64
responses:
'200':
description: Success. Returns the role's permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/RolePermissionsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No role exists with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
/api/v3/roles_by_name/{roleName}:
get:
operationId: get_role_by_name
summary: Get a role by name
description: >-
Returns the role with the specified name.
Requires a token or user with permission to read roles.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: roleName
in: path
required: true
description: The name of the role to retrieve.
schema:
type: string
responses:
'200':
description: Success. Returns the matching role.
content:
application/json:
schema:
$ref: '#/components/schemas/RoleByNameResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No role exists with the specified name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
/api/v3/row_delete_requests/{seq}/abort:
post:
operationId: abort_row_delete_request
summary: Abort a pending row-delete request
description: >-
Aborts a pending row-delete request identified by its sequence number.
Returns the updated request with a disposition of `aborted`.
Requires a token or user with `delete` permission on the database that
the row-delete request targets.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
parameters:
- name: seq
in: path
required: true
description: The sequence number of the row-delete request to abort.
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AbortDeleteRequestBody'
responses:
'200':
description: Success. Returns the aborted row-delete request.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteRequestResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >-
Not found. No row-delete request exists with the specified sequence
number.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Data deletion
/api/v3/users/{id}:
patch:
operationId: update_user
summary: Update a user's information
description: >-
Updates a user's profile information. Currently, only the user's display
name can be updated.
Requires a token or user with permission to update users.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
description: The numeric ID of the user to update.
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRequest'
responses:
'200':
description: Success. Returns the updated user.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No user exists with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
delete:
operationId: delete_user
summary: Delete a user
description: >-
Soft deletes a user. A user can self-delete as long as they are not the
last remaining user; the last user can only be deleted with an operator
token. Deleting a user revokes all of that user's refresh tokens.
Requires a token or user with permission to delete users.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
description: The numeric ID of the user to delete.
schema:
type: integer
format: int64
responses:
'200':
description: Success. Returns the deleted user with `deletedAt` set.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: >-
Access denied. The caller cannot delete their own account when they
are the last remaining user, or lacks permission to delete users.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: Not found. No user exists with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
/api/v3/users/{id}/require-password-reset:
post:
operationId: require_password_reset
summary: Require a user to reset their password on next login
description: >-
Marks the specified user as requiring a password reset. The user must
set a new password before they are able to authenticate and receive a
token.
Requires a token or user with permission to update users.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
description: The numeric ID of the user.
schema:
type: integer
format: int64
responses:
'200':
description: >-
Success. Returns the user with `requiresPasswordReset` set to
`true`.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No user exists with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
/api/v3/users/{id}/roles:
get:
operationId: list_user_roles
summary: List all roles assigned to a user
description: >-
Lists all roles assigned to the specified user.
Requires a token or user with permission to read users.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
description: The numeric ID of the user.
schema:
type: integer
format: int64
responses:
'200':
description: Success. Returns the list of roles assigned to the user.
content:
application/json:
schema:
$ref: '#/components/schemas/ListUserRolesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No user exists with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
put:
operationId: update_user_roles
summary: Replace all roles assigned to a user
description: >-
Replaces all role assignments for the specified user with the provided
list of role IDs. Roles not included in the request are removed from the
user.
Requires a token or user with permission to update users.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: id
in: path
required: true
description: The numeric ID of the user.
schema:
type: integer
format: int64
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRolesRequest'
responses:
'200':
description: Success. Returns the user's updated role assignments.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserRolesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. No user exists with the specified ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
/api/v3/users_by_oauth_id/{oauth_id}:
get:
operationId: get_user_by_oauth_id
summary: Get a user by OAuth identity-provider ID
description: >-
Returns the user associated with the specified OAuth identity-provider
ID. Requires the server to be configured with an OAuth validator.
Requires a token or user with permission to read users.
This endpoint is only available in InfluxDB 3 Enterprise. User
authentication is a preview feature enabled by setting
`--without-user-auth false`.
x-enterprise-only: true
parameters:
- name: oauth_id
in: path
required: true
description: The OAuth identity-provider ID of the user.
schema:
type: string
responses:
'200':
description: Success. Returns the matching user.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >-
Not found. No user matches the specified OAuth ID, or OAuth is not
configured on the server.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- User management
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
ResourceTokenObject:
type: object
properties:
token_name:
type: string
permissions:
type: array
items:
type: object
properties:
resource_type:
type: string
enum:
- system
- db
actions:
type: array
items:
type: string
enum:
- read
- write
resource_names:
type: array
items:
type: string
description: List of resource names. Use "*" for all resources.
expiry_secs:
type: integer
description: The expiration time in seconds.
example:
token_name: All system information
permissions:
- resource_type: system
actions:
- read
resource_names:
- '*'
expiry_secs: 300000
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.
Database:
type: string
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.
NoSync:
type: boolean
default: false
description: >
Acknowledges a successful write without waiting for WAL persistence.
#### Related
- [Use the HTTP API and client libraries to write
data](https://docs.influxdata.com/influxdb3/enterprise/write-data/api-client-libraries/)
- [Data
durability](https://docs.influxdata.com/influxdb3/enterprise/reference/internals/durability/)
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
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
node_spec:
$ref: '#/components/schemas/ApiNodeSpec'
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
node_spec:
$ref: '#/components/schemas/ApiNodeSpec'
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
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 `--plugins-dir`
directory configured when starting InfluxDB 3.
The plugin file must implement the trigger interface associated with
the trigger's specification.
node_spec:
$ref: '#/components/schemas/ApiNodeSpec'
trigger_name:
type: string
trigger_settings:
description: |
Configuration for trigger error handling and execution behavior.
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: true
description: Optional arguments passed to the plugin.
disabled:
type: boolean
default: false
description: Whether the trigger is disabled.
required:
- db
- plugin_filename
- trigger_name
- trigger_settings
- trigger_specification
- disabled
TriggerSettings:
type: object
description: >
Configuration settings for processing engine trigger error handling and
execution behavior.
properties:
run_async:
type: boolean
default: false
description: >
Whether to run the trigger asynchronously.
When `true`, the trigger executes in the background without
blocking.
When `false`, the trigger executes synchronously.
error_behavior:
type: string
enum:
- Log
- Retry
- Disable
description: |
Specifies how to handle errors that occur during trigger execution:
- `Log`: Log the error and continue (default)
- `Retry`: Retry the trigger execution
- `Disable`: Disable the trigger after an error
default: Log
required:
- run_async
- error_behavior
ApiNodeSpec:
x-enterprise-only: true
type: object
description: >
Optional specification for targeting specific nodes in a multi-node
InfluxDB 3 Enterprise cluster.
Use this to control which node(s) should handle the cache or trigger.
properties:
node_id:
type: string
description: >
The ID of a specific node in the cluster.
If specified, the cache or trigger will only be created on this
node.
node_group:
type: string
description: >
The name of a node group in the cluster.
If specified, the cache or trigger will be created on all nodes in
this group.
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
LineProtocolError:
properties:
code:
description: Code is the machine-readable error code.
enum:
- internal error
- not found
- conflict
- invalid
- empty value
- unavailable
readOnly: true
type: string
err:
description: >-
Stack of errors that occurred during processing of the request.
Useful for debugging.
readOnly: true
type: string
line:
description: First line in the request body that contains malformed data.
format: int32
readOnly: true
type: integer
message:
description: Human-readable message.
readOnly: true
type: string
op:
description: >-
Describes the logical code operation when the error occurred. Useful
for debugging.
readOnly: true
type: string
required:
- code
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.
UpdateTableRequest:
type: object
properties:
db:
type: string
description: The name of the database containing the table.
table:
type: string
description: The name of the table to update.
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
description: Request schema for updating table configuration.
LicenseResponse:
type: object
properties:
license_type:
type: string
description: The type of license (for example, "enterprise", "trial").
example: enterprise
expires_at:
type: string
format: date-time
description: The expiration date of the license in ISO 8601 format.
example: '2025-12-31T23:59:59Z'
features:
type: array
items:
type: string
description: List of features enabled by the license.
example:
- clustering
- processing_engine
- advanced_auth
status:
type: string
enum:
- active
- expired
- invalid
description: The current status of the license.
example: active
description: Response schema for license information.
CreateTokenWithPermissionsRequest:
type: object
properties:
token_name:
type: string
description: The name for the resource token.
permissions:
type: array
items:
$ref: '#/components/schemas/PermissionDetailsApi'
description: List of permissions to grant to the token.
expiry_secs:
type: integer
description: Optional expiration time in seconds.
nullable: true
required:
- token_name
- permissions
PermissionDetailsApi:
type: object
properties:
resource_type:
type: string
enum:
- system
- db
description: The type of resource.
resource_names:
type: array
items:
type: string
description: List of resource names. Use "*" for all resources.
actions:
type: array
items:
type: string
enum:
- read
- write
description: List of actions to grant.
required:
- resource_type
- resource_names
- actions
FileIndexCreateRequest:
type: object
description: Request body for creating a file index.
properties:
db:
type: string
description: The database name.
table:
type: string
description: The table name. If omitted, the file index applies to the database.
nullable: true
columns:
type: array
items:
type: string
description: The columns to use for the file index.
required:
- db
- columns
example:
db: mydb
table: mytable
columns:
- tag1
- tag2
FileIndexDeleteRequest:
type: object
description: Request body for deleting a file index.
properties:
db:
type: string
description: The database name.
table:
type: string
description: The table name. If omitted, deletes the database-level file index.
nullable: true
required:
- db
example:
db: mydb
table: mytable
StopNodeRequest:
type: object
description: Request body for marking a node as stopped in the catalog.
properties:
node_id:
type: string
description: The ID of the node to mark as stopped.
required:
- node_id
example:
node_id: node-1
AbortDeleteRequestBody:
type: object
description: Request body for aborting a row-delete request.
properties:
reason:
type: string
description: The reason for aborting the row-delete request.
required:
- reason
example:
reason: Predicate was too broad
ApiPermission:
type: object
description: >-
A permission granted to a user or role. `resourceType` discriminates the
permission category and `actions` lists the granted actions (snake_case)
for that category. Database permissions may additionally carry
`identifiers` (specific databases) or `allResources: true`.
properties:
resourceType:
type: string
description: The resource category the permission applies to.
enum:
- database
- token
- user
- role
- admin_token
actions:
type: array
description: The granted actions (snake_case) for this resource type.
items:
type: string
identifiers:
type: array
description: >-
Database permissions only. Specific database names the permission
targets. Empty when `allResources` is `true`.
items:
type: string
allResources:
type: boolean
description: >-
Database permissions only. `true` when the permission applies to all
databases.
required:
- resourceType
- actions
BackupKind:
type: string
enum:
- full
- incremental
description: The backup type.
BackupStatus:
type: string
enum:
- in_progress
- completed
- failed
description: The status of a backup or restore.
BulkImportColumnType:
type: string
enum:
- i64
- u64
- f64
- bool
- string
- time
- tag
description: >-
The InfluxDB column type for a mapped column. These are the supported
`--column` types.
BulkImportJobStatus:
type: string
enum:
- queued
- dispatched
- imported
- compacted
- failed
- terminal_failed
description: The status of a bulk import job.
BulkImportUploadRequest:
type: object
description: >-
Multipart form data for a bulk import upload. Send `database`, `table`,
and `file_bytes`, and optionally `column_metadata`.
properties:
database:
type: string
description: The target database name.
table:
type: string
description: The target table name. The table must already exist.
file_bytes:
type: string
format: binary
description: The Parquet file bytes. Must be valid Parquet with at least one row.
column_metadata:
$ref: '#/components/schemas/ColumnMetadata'
required:
- database
- table
- file_bytes
CancelBackupRequest:
type: object
description: Request body for cancelling a running backup.
properties:
name:
type: string
description: The name of the backup job to cancel.
required:
- name
example:
name: nightly-backup
CancelBackupResponse:
type: object
description: Response returned when a backup is cancelled.
properties:
backup_name:
type: string
description: The cancelled backup name.
required:
- backup_name
example:
backup_name: nightly-backup
ColumnMetadata:
type: object
description: >-
Column metadata for a bulk import. Maps column names to InfluxDB column
types to declare tag, field, and time columns.
properties:
column_mapping:
type: object
description: >-
A map of column name to InfluxDB column type. The JSON key accepts
the aliases `column_mapping`, `schema`, and `column_metadata`.
additionalProperties:
$ref: '#/components/schemas/BulkImportColumnType'
required:
- column_mapping
example:
column_mapping:
room: tag
temp: f64
time: time
CreateBackupRequest:
type: object
description: Request body for starting a backup.
properties:
type:
type: string
enum:
- full
description: The backup type. Only `full` backups are supported.
name:
type: string
description: The backup name. Defaults to a generated name when omitted.
force:
type: boolean
default: false
description: Overwrite an existing backup of the same name.
required:
- type
example:
type: full
name: nightly-backup
force: false
CreateBackupResponse:
type: object
description: Response returned when a backup starts.
properties:
backup_name:
type: string
description: The resolved backup name.
status:
$ref: '#/components/schemas/CreateBackupStatus'
required:
- backup_name
- status
example:
backup_name: nightly-backup
status: in_progress
CreateBackupStatus:
type: string
enum:
- in_progress
description: The status of a newly started backup. Always `in_progress`.
CreateRestoreRequest:
type: object
description: Request body for starting a restore.
properties:
backup_name:
type: string
description: The name of the backup to restore from. Must not be empty.
required:
- backup_name
example:
backup_name: nightly-backup
CreateRestoreResponse:
type: object
description: Response returned when a restore starts.
properties:
restore_id:
type: string
description: The handle used to track or cancel the restore.
status:
$ref: '#/components/schemas/CreateRestoreStatus'
required:
- restore_id
- status
example:
restore_id: 01J8X9Z0ABCDEF
status: in_progress
CreateRestoreStatus:
type: string
enum:
- in_progress
description: The status of a newly started restore. Always `in_progress`.
DeleteBackupResponse:
type: object
description: Response returned when a backup is deleted.
properties:
backup_name:
type: string
description: The deleted backup name.
type:
$ref: '#/components/schemas/BackupKind'
required:
- backup_name
- type
example:
backup_name: nightly-backup
type: full
DeleteRequestProgressDto:
type: object
description: Progress tracking for a single row-delete request.
properties:
sequence_id:
type: integer
format: int64
description: The sequence number of the row-delete request.
in_range:
$ref: '#/components/schemas/PerLevelCountsDto'
out_of_range:
$ref: '#/components/schemas/OutOfRangeCountsDto'
required:
- sequence_id
- in_range
- out_of_range
DeleteRequestResponse:
type: object
description: A row-delete request.
properties:
sequence:
type: integer
format: int64
description: The sequence number of the row-delete request.
db_id:
type: integer
format: int64
description: The numeric ID of the target database.
table_id:
type: integer
format: int64
description: The numeric ID of the target table.
db_name:
type: string
description: The name of the target database.
table_name:
type: string
description: The name of the target table.
db_name_stale:
type: boolean
description: >-
Whether the database name no longer matches the current catalog
state for the stored database ID.
table_name_stale:
type: boolean
description: >-
Whether the table name no longer matches the current catalog state
for the stored table ID.
min_time:
type: integer
format: int64
description: The minimum timestamp (nanoseconds) of the delete range.
max_time:
type: integer
format: int64
description: The maximum timestamp (nanoseconds) of the delete range.
delete_predicate:
type: string
description: The predicate that selects rows to delete.
created_at:
type: integer
format: int64
description: The Unix timestamp (seconds) when the request was created.
disposition:
type: string
description: >-
The current disposition of the request: `pending`, `completed`, or
`aborted`.
completed_at:
type: integer
format: int64
description: >-
The Unix timestamp (seconds) when the request completed. Present
only for completed requests.
aborted_at:
type: integer
format: int64
description: >-
The Unix timestamp (seconds) when the request was aborted. Present
only for aborted requests.
abort_reason:
type: string
description: >-
The reason the request was aborted. Present only for aborted
requests.
progress:
$ref: '#/components/schemas/DeleteRequestProgressDto'
required:
- sequence
- db_id
- table_id
- db_name
- table_name
- db_name_stale
- table_name_stale
- delete_predicate
- created_at
- disposition
example:
sequence: 42
db_id: 1
table_id: 3
db_name: sensors
table_name: home
db_name_stale: false
table_name_stale: false
delete_predicate: room = 'kitchen'
created_at: 1717000000
disposition: aborted
aborted_at: 1717000100
abort_reason: Predicate was too broad
FullBackupListItem:
type: object
description: A single backup's manifest.
properties:
name:
type: string
description: The backup name.
type:
$ref: '#/components/schemas/BackupKind'
status:
$ref: '#/components/schemas/BackupStatus'
created_at:
type: string
format: date-time
description: The creation timestamp.
completed_at:
type: string
format: date-time
description: The completion timestamp. Omitted when the backup is not complete.
total_files:
type: integer
format: int64
description: The number of files in the backup.
total_size_bytes:
type: integer
format: int64
description: The total backup size in bytes.
required:
- name
- type
- status
- created_at
- total_files
- total_size_bytes
example:
name: nightly-backup
type: full
status: completed
created_at: '2025-06-16T02:00:00Z'
completed_at: '2025-06-16T02:05:30Z'
total_files: 128
total_size_bytes: 524288000
GetBackupResponse:
allOf:
- $ref: '#/components/schemas/FullBackupListItem'
description: A single backup's manifest. Only full backups are returned.
GetRestoreResponse:
type: object
description: The status of a single restore.
properties:
restore_id:
type: string
description: The restore handle.
backup_name:
type: string
description: The source backup name.
status:
$ref: '#/components/schemas/BackupStatus'
created_at:
type: string
format: date-time
description: When the restore started.
completed_at:
type: string
format: date-time
description: The completion timestamp. Null when the restore is not complete.
nullable: true
total_files:
type: integer
format: int64
description: The number of files.
total_size_bytes:
type: integer
format: int64
description: The total size in bytes.
required:
- restore_id
- backup_name
- status
- created_at
- total_files
- total_size_bytes
example:
restore_id: 01J8X9Z0ABCDEF
backup_name: nightly-backup
status: in_progress
created_at: '2025-06-16T03:00:00Z'
completed_at: null
total_files: 128
total_size_bytes: 524288000
LevelProgressDto:
type: object
description: Progress for a single compaction level.
properties:
total:
type: integer
format: int64
description: The total number of run sets at this level.
processed:
type: integer
format: int64
description: The number of run sets processed at this level.
required:
- total
- processed
ListBackupsResponse:
type: object
description: Response containing the list of backups.
properties:
backups:
type: array
description: All full backups.
items:
$ref: '#/components/schemas/FullBackupListItem'
required:
- backups
ListRestoresResponse:
type: object
description: Response containing the list of restores.
properties:
restores:
type: array
description: All restores, newest first.
items:
$ref: '#/components/schemas/RestoreListItem'
required:
- restores
ListUserRolesResponse:
type: object
description: The roles assigned to a user.
properties:
items:
type: array
description: The roles assigned to the user.
items:
$ref: '#/components/schemas/UserRoleResponse'
required:
- items
OutOfRangeCountsDto:
type: object
description: >-
Progress counts for run sets outside the delete criteria that require
only watermark updates.
properties:
total:
type: integer
format: int64
description: The total number of out-of-range run sets.
processed:
type: integer
format: int64
description: The number of out-of-range run sets processed.
required:
- total
- processed
PerLevelCountsDto:
type: object
description: Per-level progress counts for run sets that overlap the delete criteria.
properties:
l1:
$ref: '#/components/schemas/LevelProgressDto'
l2:
$ref: '#/components/schemas/LevelProgressDto'
l3:
$ref: '#/components/schemas/LevelProgressDto'
l4:
$ref: '#/components/schemas/LevelProgressDto'
required:
- l1
- l2
- l3
- l4
QueryConcurrencyLimitResponse:
type: object
description: The current runtime query concurrency limit.
properties:
max_concurrent_queries:
type: integer
description: >-
The maximum number of queries that can run concurrently. Omitted
when the limit is set to the maximum allowed value.
example:
max_concurrent_queries: 32
RestoreListItem:
type: object
description: A single restore's status.
properties:
restore_id:
type: string
description: The restore handle.
backup_name:
type: string
description: The source backup name.
status:
$ref: '#/components/schemas/BackupStatus'
created_at:
type: string
format: date-time
description: When the restore started.
completed_at:
type: string
format: date-time
description: The completion timestamp. Omitted when the restore is not complete.
total_files:
type: integer
format: int64
description: The number of files.
total_size_bytes:
type: integer
format: int64
description: The total size in bytes.
required:
- restore_id
- backup_name
- status
- created_at
- total_files
- total_size_bytes
RoleByNameResponse:
type: object
description: A role retrieved by name.
properties:
id:
type: integer
format: int64
description: The numeric ID of the role.
name:
type: string
description: The role name.
isRequiredRole:
type: boolean
description: Whether the role is a required role.
description:
type: string
description: The role description.
createdAt:
type: integer
format: int64
description: The Unix timestamp (seconds) when the role was created.
updatedAt:
type: integer
format: int64
description: The Unix timestamp (seconds) when the role was last updated.
required:
- id
- name
- isRequiredRole
- createdAt
- updatedAt
example:
id: 1
name: read-write
isRequiredRole: false
createdAt: 1717000000
updatedAt: 1717000000
RolePermissionsResponse:
type: object
description: The permissions granted to a role.
properties:
permissions:
type: array
description: The permissions granted to the role.
items:
$ref: '#/components/schemas/ApiPermission'
required:
- permissions
SetQueryConcurrencyLimitRequest:
type: object
description: Request body for setting the runtime query concurrency limit.
properties:
max_concurrent_queries:
type: integer
nullable: true
description: >-
The maximum number of queries that can run concurrently. Set to
`null` (or omit) to restore the limit configured at server startup.
Must be a positive integer; values below 16 require `force=true`.
example:
max_concurrent_queries: 32
UpdateUserRequest:
type: object
description: Request body for updating a user's profile.
properties:
displayName:
type: string
description: The user's new display name.
example:
displayName: Jane Smith
UpdateUserRolesRequest:
type: object
description: Request body for replacing all of a user's role assignments.
properties:
roleIds:
type: array
description: The complete set of role IDs to assign to the user.
items:
type: integer
format: int64
required:
- roleIds
example:
roleIds:
- 1
- 2
UpdateUserRolesResponse:
type: object
description: A user's role assignments after an update.
properties:
items:
type: array
description: The roles assigned to the user.
items:
$ref: '#/components/schemas/UserRoleResponse'
required:
- items
UploadedImportInfo:
type: object
description: The status of a staged or completed bulk import job.
properties:
upload_uuid:
type: string
description: The UUID of the upload.
db_id:
type: integer
description: The ID of the database resolved from the supplied name.
table_id:
type: integer
description: The ID of the table resolved from the supplied name.
filename:
type: string
description: The filename of the uploaded Parquet data file.
status:
$ref: '#/components/schemas/BulkImportJobStatus'
last_message:
type: string
description: The last error message if the job has errored.
nullable: true
created_at:
type: integer
format: int64
description: >-
When the uploaded file was ready for import, in nanoseconds since
the Unix epoch.
started_at:
type: integer
format: int64
description: When the import began, in nanoseconds since the Unix epoch.
nullable: true
completed_at:
type: integer
format: int64
description: When the import completed, in nanoseconds since the Unix epoch.
nullable: true
last_updated_at:
type: integer
format: int64
description: When this info last changed, in nanoseconds since the Unix epoch.
nullable: true
column_metadata:
$ref: '#/components/schemas/ColumnMetadata'
iox_parquet:
type: boolean
description: Whether the file was written by IOx (richer embedded metadata).
size_bytes:
type: integer
format: int64
description: The total size of the uploaded Parquet file in bytes.
row_count:
type: integer
format: int64
description: The row count from Parquet metadata.
min_timestamp_ns:
type: integer
format: int64
description: >-
The minimum timestamp in the file (nanoseconds), from column
statistics.
max_timestamp_ns:
type: integer
format: int64
description: >-
The maximum timestamp in the file (nanoseconds), from column
statistics.
required:
- upload_uuid
- db_id
- table_id
- filename
- status
- created_at
- iox_parquet
- size_bytes
- row_count
- min_timestamp_ns
- max_timestamp_ns
UserResponse:
type: object
description: A user account.
properties:
userId:
type: integer
format: int64
description: The numeric ID of the user.
username:
type: string
description: >-
The user's username. Present when the user has a username and
password login identity.
displayName:
type: string
description: The user's display name.
requiresPasswordReset:
type: boolean
description: >-
Whether the user must reset their password on next login. Present
when the user has a username and password login identity.
createdAt:
type: integer
format: int64
description: The Unix timestamp (seconds) when the user was created.
updatedAt:
type: integer
format: int64
description: The Unix timestamp (seconds) when the user was last updated.
deletedAt:
type: integer
format: int64
description: >-
The Unix timestamp (seconds) when the user was deleted. Present only
for deleted users.
operatorToken:
type: string
description: The operator token. Returned only when creating the initial user.
oauthId:
type: string
description: >-
The user's OAuth identity-provider ID. Present when the user has an
OAuth login identity.
required:
- userId
- createdAt
- updatedAt
example:
userId: 1
username: jsmith
displayName: Jane Smith
requiresPasswordReset: false
createdAt: 1717000000
updatedAt: 1717000000
UserRoleResponse:
type: object
description: A role assigned to or available to a user.
properties:
id:
type: integer
format: int64
description: The numeric ID of the role.
name:
type: string
description: The role name.
isRequiredRole:
type: boolean
description: Whether the role is a required role.
description:
type: string
description: The role description.
createdAt:
type: integer
format: int64
description: The Unix timestamp (seconds) when the role was created.
updatedAt:
type: integer
format: int64
description: The Unix timestamp (seconds) when the role was last updated.
required:
- id
- name
- isRequiredRole
- createdAt
- updatedAt
example:
id: 1
name: read-write
isRequiredRole: false
createdAt: 1717000000
updatedAt: 1717000000
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/GetV1Query) 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 Enterprise 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/GetV1Query)
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 Enterprise 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