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.12.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: InfluxData
url: https://www.influxdata.com
email: support@influxdata.com
x-source-hash: sha256:24c3cc46699dc72e1bbfe45f0a3d91b32ed9f7635526e0a44136a3982870f228
x-influxdata-download-url: /openapi/influxdb3-enterprise-openapi.yaml
x-influxdata-short-title: InfluxDB 3 API
x-influxdata-version-matrix:
v1: Compatibility layer for InfluxDB 1.x clients (supported)
v2: Compatibility layer for InfluxDB 2.x clients (supported)
v3: Native API for InfluxDB 3.x (current)
x-influxdata-short-description: >-
The InfluxDB 3 HTTP API provides a programmatic interface for interactions
with InfluxDB, including writing, querying, and processing data, and
managing an InfluxDB 3 instance.
servers:
- url: https://{baseurl}
description: InfluxDB 3 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
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: Query groups
description: >
Manage distributed query groups--named sets of query nodes that InfluxDB 3
Enterprise load-balances queries across.
> **Not yet operational**: These endpoints work and store query group
definitions in the catalog, but InfluxDB 3 Enterprise doesn't yet use
those definitions to affect query routing, data placement, or replication.
x-related:
- title: Configure query groups
href: https://docs.influxdata.com/influxdb3/enterprise/admin/query-groups/
- 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: Load capture
description: >-
Capture an anonymized profile of write requests, query requests, or both
on a query-capable node.
x-related:
- title: Capture workload data
href: https://docs.influxdata.com/influxdb3/enterprise/admin/load-capture/
- 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: Enterprise
description: >-
Endpoints available only in InfluxDB 3 Enterprise. Operations carrying
this tag also set `x-enterprise-only: true` for programmatic detection.
- 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
responses:
'204':
description: >-
Success ("No Content"). All data in the batch is written and
queryable.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'400':
description: >
Bad request. InfluxDB rejected the whole batch and wrote nothing.
This endpoint doesn't support partial writes: if any line is
invalid, no
lines are written, and an `accept_partial` parameter is ignored.
To write the valid lines of a batch, use `/api/v3/write_lp`.
content:
application/json:
examples:
rejectedBatch:
summary: One invalid line rejects the batch
value: |
{
"code": "invalid",
"message": "write buffer error: line protocol parse failed: No fields were provided"
}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
summary: Write line protocol (v2-compatible)
description: >
Writes line protocol to the specified database.
This endpoint provides backward compatibility for InfluxDB 2.x write
workloads using tools such as InfluxDB 2.x client libraries, the
Telegraf `outputs.influxdb_v2` output plugin, or third-party tools.
Use this endpoint to send data in [line
protocol](https://docs.influxdata.com/influxdb3/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.
- $ref: '#/components/parameters/compatibilityPrecisionParam'
requestBody:
$ref: '#/components/requestBodies/lineProtocolRequestBody'
tags:
- Write data
/api/v3/authorize:
post:
operationId: PostAuthorize
requestBody:
required: true
content:
application/json:
schema:
type: object
description: AuthorizeRequest
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/authorize/refresh:
post:
operationId: PostAuthorizeRefresh
requestBody:
required: true
content:
application/json:
schema:
type: object
description: RefreshTokenRequest
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/authorize/reset-password:
post:
operationId: PostAuthorizeResetPassword
requestBody:
required: true
content:
application/json:
schema:
type: object
description: ResetPasswordRequest
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/configure/database:
delete:
operationId: DeleteConfigureDatabase
parameters:
- $ref: '#/components/parameters/db'
- name: data_only
in: query
required: false
schema:
type: boolean
default: false
description: >
Delete only data while preserving the database schema and all
associated resources
(tokens, triggers, last value caches, distinct value caches,
processing engine configurations).
When `false` (default), the entire database is deleted.
- name: remove_tables
in: query
required: false
schema:
type: boolean
default: false
description: >
Used with `data_only=true` to remove table resources (caches) while
preserving
database-level resources (tokens, triggers, processing engine
configurations).
Has no effect when `data_only=false`.
- name: hard_delete_at
in: query
required: false
schema:
type: string
format: date-time
description: >-
Schedule the database for hard deletion at the specified time.
If not provided, the database will be soft deleted.
Use ISO 8601 date-time format (for example, "2025-12-31T23:59:59Z").
#### Deleting a database cannot be undone
Deleting a database is a destructive action.
Once a database is deleted, data stored in that database cannot be
recovered.
Also accepts special string values:
- `now` — hard delete immediately
- `never` — soft delete only (default behavior)
- `default` — use the system default hard deletion time
responses:
'200':
description: Success. Database deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: Delete a database
description: >
Soft deletes a database.
The database is scheduled for deletion and unavailable for querying.
Use the `hard_delete_at` parameter to schedule a hard deletion.
Use the `data_only` parameter to delete data while preserving the
database schema and resources.
tags:
- Database
get:
operationId: GetConfigureDatabase
responses:
'200':
description: Success. The response body contains the list of databases.
content:
application/json:
schema:
$ref: '#/components/schemas/ShowDatabasesResponse'
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: List databases
description: Retrieves a list of databases.
parameters:
- $ref: '#/components/parameters/formatRequired'
- name: show_deleted
in: query
required: false
schema:
type: boolean
default: false
description: |
Include soft-deleted databases in the response.
By default, only active databases are returned.
tags:
- Database
post:
operationId: PostConfigureDatabase
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatabaseRequest'
responses:
'200':
description: Success. Database created.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: Database already exists.
summary: Create a database
description: Creates a new database in the system.
tags:
- Database
put:
operationId: PutConfigureDatabase
responses:
'200':
description: Success. The database has been updated.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: Update a database
description: |
Updates database configuration, such as retention period.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDatabaseRequest'
tags:
- Database
/api/v3/configure/database/retention_period:
delete:
operationId: DeleteDatabaseRetentionPeriod
summary: Remove database retention period
description: >
Removes the retention period from a database, setting it to infinite
retention.
parameters:
- $ref: '#/components/parameters/db'
responses:
'204':
description: Success. The database retention period has been removed.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
tags:
- Database
/api/v3/configure/distinct_cache:
delete:
operationId: DeleteConfigureDistinctCache
requestBody:
required: true
content:
application/json:
schema:
type: object
description: DistinctCacheDeleteRequest
responses:
'200':
description: Success. The distinct cache has been deleted.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Cache not found.
summary: Delete distinct cache
description: Deletes a distinct cache.
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
description: The name of the table containing the distinct cache.
- name: name
in: query
required: true
schema:
type: string
description: The name of the distinct cache to delete.
tags:
- Cache distinct values
- Table
post:
operationId: PostConfigureDistinctCache
responses:
'201':
description: Success. The distinct cache has been created.
'400':
description: >
Bad request.
The server responds with status `400` if the request would overwrite
an existing cache with a different configuration.
'409':
description: Conflict. A distinct cache with this configuration already exists.
summary: Create distinct cache
description: Creates a distinct cache for a table.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DistinctCacheCreateRequest'
tags:
- Cache distinct values
- Table
/api/v3/configure/last_cache:
delete:
operationId: DeleteConfigureLastCache
requestBody:
required: true
content:
application/json:
schema:
type: object
description: LastCacheDeleteRequest
responses:
'200':
description: Success. The last cache has been deleted.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Cache not found.
summary: Delete last cache
description: Deletes a last cache.
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
description: The name of the table containing the last cache.
- name: name
in: query
required: true
schema:
type: string
description: The name of the last cache to delete.
tags:
- Cache last value
- Table
post:
operationId: PostConfigureLastCache
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LastCacheCreateRequest'
responses:
'201':
description: Success. Last cache created.
'400':
description: >-
Bad request. A cache with this name already exists or the request is
malformed.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Cache not found.
summary: Create last cache
description: Creates a last cache for a table.
tags:
- Cache last value
- Table
/api/v3/configure/plugin_environment/install_packages:
post:
operationId: PostInstallPluginPackages
summary: Install plugin packages
description: >-
Installs the specified Python packages into the processing engine plugin
environment.
This endpoint is synchronous and blocks until the packages are
installed.
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
packages:
type: array
items:
type: string
description: >
A list of Python package names to install.
Can include version specifiers (for example,
"scipy==1.9.0").
example:
- influxdb3-python
- scipy
- pandas==1.5.0
- requests
required:
- packages
example:
packages:
- influxdb3-python
- scipy
- pandas==1.5.0
- requests
responses:
'200':
description: >-
Success. The packages are installed. In InfluxDB 3 Core 3.12, a
failed install can also return `200`; confirm that the package
imports before relying on it.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'500':
description: >-
The package install failed, for example because pip couldn't find
the package. The body includes the package manager's error.
tags:
- Processing engine
/api/v3/configure/plugin_environment/install_requirements:
post:
operationId: PostInstallPluginRequirements
summary: Install plugin requirements
description: >
Installs requirements from a requirements file (also known as a "pip
requirements file") into the processing engine plugin environment.
This endpoint is synchronous and blocks until the requirements are
installed.
### Related
- [Processing engine and Python
plugins](https://docs.influxdata.com/influxdb3/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
github_plugin:
summary: Trigger using a remotely fetched plugin
description: >
Trigger that uses a plugin referenced with the `gh:` prefix.
InfluxDB fetches the plugin from the default
`influxdata/influxdb3_plugins`
repository (or the repository configured with `--plugin-repo`)
instead of the local `--plugin-dir`.
value:
db: mydb
plugin_filename: gh:examples/wal_plugin/wal_plugin.py
trigger_name: my_trigger
trigger_specification: all_tables
disabled: false
trigger_settings:
run_async: false
error_behavior: log
node_specific:
x-enterprise-only: true
summary: Trigger on specific cluster nodes
description: |
In `node_spec`, use `"all"` (default) to run the trigger on
all nodes, or `{"nodes": ["NODE_ID"]}` to run it only on the
specified nodes.
value:
db: mydb
plugin_filename: table.py
trigger_name: node_specific_trigger
trigger_specification: table:sensors
node_spec:
nodes:
- node-01
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/query_concurrency_limit:
get:
operationId: GetConfigureQueryConcurrencyLimit
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
- Enterprise
put:
operationId: PutConfigureQueryConcurrencyLimit
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
- Enterprise
delete:
operationId: DeleteConfigureQueryConcurrencyLimit
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
- Enterprise
/api/v3/configure/table:
delete:
operationId: DeleteConfigureTable
parameters:
- $ref: '#/components/parameters/db'
- name: table
in: query
required: true
schema:
type: string
- name: data_only
in: query
required: false
schema:
type: boolean
default: false
description: >
Delete only data while preserving the table schema and all
associated resources
(last value caches, distinct value caches).
When `false` (default), the entire table is deleted.
- name: hard_delete_at
in: query
required: false
schema:
type: string
format: date-time
description: |-
Schedule the table for hard deletion at the specified time.
If not provided, the table will be soft deleted.
Use ISO 8601 format (for example, "2025-12-31T23:59:59Z").
Also accepts special string values:
- `now` — hard delete immediately
- `never` — soft delete only (default behavior)
- `default` — use the system default hard deletion time
responses:
'200':
description: Success (no content). The table has been deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Table not found.
'409':
description: Conflict. The table is already deleted.
summary: Delete a table
description: >
Soft deletes a table.
The table is scheduled for deletion and unavailable for querying.
Use the `hard_delete_at` parameter to schedule a hard deletion.
Use the `data_only` parameter to delete data while preserving the table
schema and resources.
#### Deleting a table cannot be undone
Deleting a table is a destructive action.
Once a table is deleted, data stored in that table cannot be recovered.
#### Soft-deleted tables keep a renamed, visible entry until hard
deletion
A soft delete renames the table to `-`
instead of removing it.
Until the table is hard deleted, this renamed entry still appears in
`SHOW TABLES` output and in
`information_schema.tables` queries. Filter out names that end in a
deleted-at timestamp to account for
these renamed entries when listing or counting tables.
Deleting an already-deleted table returns `409 Conflict`. There's no API
to remove the renamed entry
directly; only a scheduled or immediate (`hard_delete_at=now`) hard
deletion removes it.
tags:
- Table
post:
operationId: PostConfigureTable
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTableRequest'
responses:
'200':
description: Success. The table has been created.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database not found.
summary: Create a table
description: Creates a new table within a database.
tags:
- Table
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.
x-enterprise-only: true
summary: Update a table
description: |
Updates a table's retention period.
This endpoint doesn't add columns. Other properties in the request body,
such as `tags` or `fields`, are ignored, and the request still returns
`200`. To add columns, use `PATCH /api/v3/configure/table`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTableRequest'
tags:
- Enterprise
patch:
operationId: PatchConfigureTable2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchTableRequest'
responses:
'200':
description: >-
Success. The columns have been added to the table. The response body
is empty.
'400':
description: >-
Bad request. The request names no tags or fields, or is otherwise
invalid.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Database or table not found.
summary: Add columns to a table
description: >
Adds tag and field columns to an existing table.
The change is additive: a column that already exists with the requested
type is left unchanged.
No other table settings are modified.
The request must name at least one tag or field.
tags:
- Table
/api/v3/configure/token:
delete:
operationId: DeleteToken
parameters:
- name: token_name
in: query
required: true
schema:
type: string
description: The name of the token to delete.
responses:
'200':
description: Success. The token has been deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Token not found.
summary: Delete token
description: |
Deletes a token.
tags:
- Authentication
- Auth token
/api/v3/configure/token/admin:
post:
operationId: PostCreateAdminToken
responses:
'201':
description: |
Success. The admin token has been created.
The response body contains the token string and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
summary: Create admin token
description: >
Creates an admin token.
An admin token is a special type of token that has full access to all
resources in the system.
tags:
- Authentication
- Auth token
/api/v3/configure/token/admin/regenerate:
post:
operationId: PostRegenerateAdminToken
summary: Regenerate admin token
description: >
Regenerates an admin token and revokes the previous token with the same
name.
parameters: []
responses:
'201':
description: Success. The admin token has been regenerated.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Authentication
- Auth token
/api/v3/configure/token/named_admin:
post:
operationId: PostCreateNamedAdminToken
responses:
'201':
description: |
Success. The named admin token has been created.
The response body contains the token string and metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTokenObject'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: A token with this name already exists.
summary: Create named admin token
description: >
Creates a named admin token.
A named admin token is a special type of admin token with a custom name
for identification and management.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
token_name:
type: string
description: The name for the admin token.
expiry_secs:
type: integer
description: >-
Optional expiration time in seconds. If not provided, the
token does not expire.
nullable: true
required:
- token_name
tags:
- Authentication
- Auth token
/api/v3/configure/user:
post:
operationId: PostConfigureUser
requestBody:
required: true
content:
application/json:
schema:
type: object
description: CreateInitialUserRequest
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/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/backup:
post:
operationId: PostEnterpriseBackup
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/GetEnterpriseBackup) or [Get a
backup](#operation/GetEnterpriseBackupByName) 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
- Enterprise
delete:
operationId: DeleteEnterpriseBackup
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
- Enterprise
get:
operationId: GetEnterpriseBackup
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
- Enterprise
/api/v3/enterprise/backup/{name}:
get:
operationId: GetEnterpriseBackupByName
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
- Enterprise
delete:
operationId: DeleteEnterpriseBackupByName
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
- Enterprise
/api/v3/enterprise/configure/file_index:
post:
operationId: PostEnterpriseConfigureFileIndex
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
- Enterprise
delete:
operationId: DeleteEnterpriseConfigureFileIndex
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
- Enterprise
/api/v3/enterprise/configure/node/stop:
post:
operationId: PostEnterpriseConfigureNodeStop
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
- Enterprise
/api/v3/enterprise/configure/node/remove:
post:
operationId: PostEnterpriseConfigureNodeRemove
summary: Permanently remove a stopped node
description: >-
Permanently removes a node that has already been marked as stopped,
deleting its data from object storage once the compactor finishes
reassigning its work.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 remove
node](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/remove/node/)
- [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/RemoveNodeRequest'
responses:
'200':
description: Success. The node has been removed.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Node not found.
'409':
description: >-
The node is not in a state that allows removal (for example, still
running).
tags:
- Server information
- Enterprise
/api/v3/enterprise/upgrade/parquet_cleanup:
post:
operationId: PostEnterpriseUpgradeParquetCleanup
summary: Request Parquet cleanup after a storage engine upgrade
description: >-
Requests removal of the Parquet-era data left behind by a completed
Parquet-to-PachaTree storage engine upgrade. Any node in the cluster
accepts the request. The compactor node executes it.
Requires the cluster to be fully on the upgraded (PachaTree) storage
engine, with the Parquet-to-PachaTree upgrade already complete. Use
`dry_run` to count and size the data a real cleanup would delete without
deleting anything.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 manage
cleanup-parquet](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/manage/cleanup-parquet/)
x-enterprise-only: true
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ParquetCleanupRequest'
responses:
'202':
description: >-
Success. The cleanup started, is already running, or already
completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ParquetCleanupResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: >-
The cluster isn't on the upgraded storage engine, no
Parquet-to-PachaTree upgrade was ever recorded, the upgrade hasn't
completed, or a cleanup is already active in a different mode (dry
run vs. delete).
tags:
- Server information
- Enterprise
x-influxdb-introduced-in: v3.11.1
get:
operationId: GetEnterpriseUpgradeParquetCleanup
summary: Get Parquet cleanup status
description: >-
Returns the current or most recent Parquet cleanup state for the
cluster.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 manage
cleanup-parquet](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/manage/cleanup-parquet/)
x-enterprise-only: true
responses:
'200':
description: Success. Returns the current Parquet cleanup state.
content:
application/json:
schema:
$ref: '#/components/schemas/ParquetCleanupStatusSnapshot'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: No Parquet cleanup has ever been requested on this cluster.
tags:
- Server information
- Enterprise
x-influxdb-introduced-in: v3.11.1
/api/v3/enterprise/upgrade/retry_parquet_to_pacha_tree:
post:
operationId: PostEnterpriseUpgradeRetryParquetToPachaTree
summary: Retry a failed Parquet-to-PachaTree upgrade
description: >-
Resets a Parquet-to-PachaTree storage engine upgrade that latched to a
`failed` state, so it resumes the next time a compactor node starts with
`--upgrade-pacha-tree`.
Re-checks every previously failed upgrade source against the catalog and
object store: sources that are still readable are requeued, sources
whose table or database was dropped are recorded as skipped, and sources
that can't be read back are left unresolved for the next retry.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 manage
retry-upgrade-to-pacha-tree](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/manage/retry-upgrade-to-pacha-tree/)
x-enterprise-only: true
responses:
'200':
description: Success. Returns a summary of what the retry changed.
content:
application/json:
schema:
$ref: '#/components/schemas/UpgradeRetryResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: >-
The upgrade isn't in a state this request can act on (for example,
it isn't `failed`), or another request already reset it.
tags:
- Server information
- Enterprise
x-influxdb-introduced-in: v3.11.2
/api/v3/enterprise/configure/query_groups:
post:
operationId: PostEnterpriseConfigureQueryGroups
summary: Create a distributed query group (not yet operational)
description: >-
Reserved for the distributed query group feature.
> **Not yet operational**: Request and response fields aren't finalized,
and InfluxDB 3 Enterprise doesn't yet use query group definitions to
affect query routing, data placement, or replication.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 create
query_group](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/create/query_group/)
x-enterprise-only: true
x-lifecycle: not-operational
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
Not documented. This endpoint is not yet operational; request
fields aren't finalized.
responses:
'201':
description: >-
Created. Not documented. This endpoint is not yet operational;
response fields aren't finalized.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Query groups
- Enterprise
get:
operationId: GetEnterpriseConfigureQueryGroups
summary: List distributed query groups (not yet operational)
description: >-
Reserved for the distributed query group feature.
> **Not yet operational**: Request and response fields aren't finalized,
and InfluxDB 3 Enterprise doesn't yet use query group definitions to
affect query routing, data placement, or replication.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 show
query_groups](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/show/query_groups/)
x-enterprise-only: true
x-lifecycle: not-operational
responses:
'200':
description: >-
Success. Not documented. This endpoint is not yet operational;
response fields aren't finalized.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
tags:
- Query groups
- Enterprise
/api/v3/enterprise/configure/query_groups/{id}:
get:
operationId: GetEnterpriseConfigureQueryGroupsById
summary: Retrieve a distributed query group (not yet operational)
description: >-
Reserved for the distributed query group feature.
> **Not yet operational**: Request and response fields aren't finalized,
and InfluxDB 3 Enterprise doesn't yet use query group definitions to
affect query routing, data placement, or replication.
This endpoint is only available in InfluxDB 3 Enterprise.
x-enterprise-only: true
x-lifecycle: not-operational
parameters:
- name: id
in: path
required: true
description: The ID of the query group.
schema:
type: integer
responses:
'200':
description: >-
Success. Not documented. This endpoint is not yet operational;
response fields aren't finalized.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Query group not found.
tags:
- Query groups
- Enterprise
put:
operationId: PutEnterpriseConfigureQueryGroupsById
summary: Replace a distributed query group (not yet operational)
description: >-
Reserved for the distributed query group feature.
> **Not yet operational**: Request and response fields aren't finalized,
and InfluxDB 3 Enterprise doesn't yet use query group definitions to
affect query routing, data placement, or replication.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 update
query_group](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/update/query_group/)
x-enterprise-only: true
x-lifecycle: not-operational
parameters:
- name: id
in: path
required: true
description: The ID of the query group.
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
Not documented. This endpoint is not yet operational; request
fields aren't finalized.
responses:
'200':
description: >-
Success. Not documented. This endpoint is not yet operational;
response fields aren't finalized.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Query group not found.
tags:
- Query groups
- Enterprise
patch:
operationId: PatchEnterpriseConfigureQueryGroupsById
summary: Update a distributed query group (not yet operational)
description: >-
Reserved for the distributed query group feature.
> **Not yet operational**: Request and response fields aren't finalized,
and InfluxDB 3 Enterprise doesn't yet use query group definitions to
affect query routing, data placement, or replication.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 update
query_group](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/update/query_group/)
x-enterprise-only: true
x-lifecycle: not-operational
parameters:
- name: id
in: path
required: true
description: The ID of the query group.
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
Not documented. This endpoint is not yet operational; request
fields aren't finalized.
responses:
'200':
description: >-
Success. Not documented. This endpoint is not yet operational;
response fields aren't finalized.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Query group not found.
tags:
- Query groups
- Enterprise
delete:
operationId: DeleteEnterpriseConfigureQueryGroupsById
summary: Delete a distributed query group (not yet operational)
description: >-
Reserved for the distributed query group feature.
> **Not yet operational**: Request and response fields aren't finalized,
and InfluxDB 3 Enterprise doesn't yet use query group definitions to
affect query routing, data placement, or replication.
This endpoint is only available in InfluxDB 3 Enterprise.
#### Related
- [influxdb3 delete
query_group](https://docs.influxdata.com/influxdb3/enterprise/reference/cli/influxdb3/delete/query_group/)
x-enterprise-only: true
x-lifecycle: not-operational
parameters:
- name: id
in: path
required: true
description: The ID of the query group.
schema:
type: integer
responses:
'200':
description: Success. The query group has been deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Query group not found.
tags:
- Query groups
- Enterprise
/api/v3/enterprise/configure/table/retention_period:
post:
operationId: PostEnterpriseConfigureTableRetentionPeriod
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
- Enterprise
delete:
operationId: DeleteEnterpriseConfigureTableRetentionPeriod
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
- Enterprise
/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.
InfluxDB 3 Cloud supports a narrower set of database-scoped read and
write tokens instead of resource
tokens---see [Manage tokens in InfluxDB 3
Cloud](https://docs.influxdata.com/influxdb3/cloud/admin/tokens/).
InfluxDB 3 Core doesn't support resource tokens.
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
- Enterprise
x-enterprise-only: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTokenWithPermissionsRequest'
/api/v3/enterprise/import:
post:
operationId: PostEnterpriseImport
summary: Import Parquet data
description: >-
Imports Parquet data into an existing table. Send the data one of two
ways:
- **Upload** (`multipart/form-data`): send one Parquet file in the
request.
- **Object-store pull** (`application/json`): name a `source` prefix,
and the server imports every Parquet
file under it. The source is either a prefix in the cluster's own object store or an `s3://bucket/prefix`
URL. The server reads another bucket with its own object-store credentials; the request carries none, so
those credentials must be able to read the bucket. A server whose own object store isn't S3 can't read
another bucket and returns `400`.
The request returns after the import is staged. The compactor node
imports the data asynchronously. A job
moves through `queued`, `imported`, and `compacted`; rows become
queryable once the job is `compacted`.
Use [List bulk import statuses](#operation/GetEnterpriseImport) to
follow it.
#### Column types
For generic Parquet files, a column that isn't in `column_metadata` is
imported as a field, typed from its
Parquet type. This applies even when the target table already declares
the column as a tag, so map every
string tag column (for example, `{"column_mapping": {"host": "tag"}}`).
Otherwise the import fails with
`invalid column type for column 'host', expected iox::column_type::tag,
got iox::column_type::field::string`.
A string column with no mapping can also fail with `400` `Unable to
infer data type for column`.
#### Explicit schema databases
In a database created with `schema_mode: explicit`, every column in the
file must already be declared on the
table. Otherwise the import is rejected and no job is created. Declare
columns with
`PATCH /api/v3/configure/table`.
#### Permissions
Requires a token with the `write` action on the target database (for
example, `db:DATABASE_NAME:write`), or an
admin token. For a token without that permission, including when the
database doesn't exist, the request
returns `403`.
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'
application/json:
schema:
$ref: '#/components/schemas/BulkImportObjectStoreRequest'
example:
database: sensors
table: cpu
source: s3://import-bucket/exports/cpu/
column_metadata:
column_mapping:
host: tag
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':
description: >-
Forbidden. The token doesn't have the `write` action on the target
database. A token without that permission also gets `403` when the
database doesn't exist (`Not authorized to import into database`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'404':
description: >-
Not found. The target table does not exist ("Table `cpu` does not
exist").
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'500':
description: >-
Internal server error. Object store, status write, or catalog
failure. In 3.12, a file whose columns don't match the table also
returns `500` with `Could not modify catalog`: a column that an
explicit schema database doesn't declare, or an unmapped string
column that the table declares as a tag.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
tags:
- Bulk import
- Enterprise
get:
operationId: GetEnterpriseImport
summary: List bulk import statuses
description: >-
Lists the status of bulk import jobs, for both uploads and object-store
pulls.
Requires a token with the `describe` action on at least one database, or
an admin token. The list includes only jobs for databases the token can
describe. A token that can't describe any database gets `403`.
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
- Enterprise
/api/v3/enterprise/restore:
post:
operationId: PostEnterpriseRestore
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/GetEnterpriseRestoreById) 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
- Enterprise
get:
operationId: GetEnterpriseRestore
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
- Enterprise
/api/v3/enterprise/restore/{id}:
get:
operationId: GetEnterpriseRestoreById
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
- Enterprise
delete:
operationId: DeleteEnterpriseRestoreById
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
- Enterprise
/api/v3/export/databases:
get:
operationId: GetExportDatabases
responses:
'200':
description: Success. Returns a list of database names.
content:
application/json:
schema:
type: object
'401':
$ref: '#/components/responses/Unauthorized'
x-enterprise-only: true
summary: List databases available for export
description: >
Returns a list of databases that have compacted data available for
Parquet export.
> **Requires the upgraded storage engine**: This endpoint requires the
> [upgraded storage
engine](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/),
which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the
storage engine upgrade with
>
[`--upgrade-pacha-tree`](https://docs.influxdata.com/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
tags:
- Export data
- Enterprise
/api/v3/export/tables:
get:
operationId: GetExportTables
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.
x-enterprise-only: true
summary: List tables available for export
description: >
Returns a list of tables in a database that have compacted data
available for Parquet export.
> **Requires the upgraded storage engine**: This endpoint requires the
> [upgraded storage
engine](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/),
which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the
storage engine upgrade with
>
[`--upgrade-pacha-tree`](https://docs.influxdata.com/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
tags:
- Export data
- Enterprise
/api/v3/export/window_data:
get:
operationId: GetExportWindowData
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.
x-enterprise-only: true
summary: Export window data as Parquet
description: >
Downloads compacted data for the specified windows as a tar archive
containing Parquet files.
> **Requires the upgraded storage engine**: This endpoint requires the
> [upgraded storage
engine](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/),
which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the
storage engine upgrade with
>
[`--upgrade-pacha-tree`](https://docs.influxdata.com/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
tags:
- Export data
- Enterprise
/api/v3/export/windows:
get:
operationId: GetExportWindows
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.
x-enterprise-only: true
summary: List compacted windows for a table
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.
> **Requires the upgraded storage engine**: This endpoint requires the
> [upgraded storage
engine](https://docs.influxdata.com/influxdb3/enterprise/performance-preview/),
which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the
storage engine upgrade with
>
[`--upgrade-pacha-tree`](https://docs.influxdata.com/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
tags:
- Export data
- Enterprise
/api/v3/isAuthorized:
post:
operationId: PostIsAuthorized
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationCheck'
responses:
'200':
description: >
The check was evaluated.
`authorized` is `false` when the caller isn't permitted to perform
the action.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationResult'
'400':
description: >-
Bad request. The body must name exactly one action; boolean actions
must be `true`.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: >-
Forbidden. Only user subjects can call this endpoint; token subjects
receive `403`.
x-enterprise-only: true
summary: Check whether the caller is authorized for an action
description: >
Reports whether the calling user may perform the single action named in
the request body.
A denied action returns `200` with `authorized: false`.
A `403` response means the caller can't use this endpoint.
tags:
- Enterprise
/api/v3/loadcap/profiles:
get:
operationId: GetLoadcapProfiles
summary: List load capture profiles
description: >
Returns load capture profiles stored by a query-capable Enterprise node
that has the performance upgrade preview enabled and an explicit
`--mode` setting that includes `query`.
This endpoint requires an admin token.
responses:
'200':
description: Load capture profiles.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LoadCaptureProfile'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. An admin token is required.
'404':
description: >-
Load capture is unavailable because this node does not use the
performance upgrade preview with an explicit `--mode` setting that
includes `query`.
tags:
- Load capture
- Enterprise
x-enterprise-only: true
x-influxdb-introduced-in: v3.10.0
/api/v3/loadcap/start:
post:
operationId: PostLoadcapStart
summary: Start a load capture
description: >
Starts a timed capture of write requests, query requests, or both on a
query-capable Enterprise node that has the performance upgrade preview
enabled and an explicit `--mode` setting that includes `query`.
Only one capture can run at a time on a node. This endpoint requires an
admin token.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LoadCaptureStartRequest'
responses:
'200':
description: Load capture started.
content:
application/json:
schema:
$ref: '#/components/schemas/LoadCaptureStartResponse'
'400':
description: Invalid capture type or duration.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. An admin token is required.
'404':
description: >-
Load capture is unavailable because this node does not use the
performance upgrade preview with an explicit `--mode` setting that
includes `query`.
'409':
description: A load capture is already running on this node.
tags:
- Load capture
- Enterprise
x-enterprise-only: true
x-influxdb-introduced-in: v3.10.0
/api/v3/loadcap/profiles/{profile_id}:
parameters:
- $ref: '#/components/parameters/LoadCaptureProfileId'
get:
operationId: GetLoadcapProfile
summary: Retrieve load capture profile details
description: >
Returns file counts, total size, and an anonymized catalog summary for a
load capture profile. The response is the same as the profile preview.
This endpoint requires an admin token.
responses:
'200':
description: Load capture profile details.
content:
application/json:
schema:
$ref: '#/components/schemas/LoadCapturePreview'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. An admin token is required.
'404':
description: >-
The profile does not exist, or load capture is unavailable because
this node does not use the performance upgrade preview with an
explicit `--mode` setting that includes `query`.
tags:
- Load capture
- Enterprise
x-enterprise-only: true
x-influxdb-introduced-in: v3.10.0
delete:
operationId: DeleteLoadcapProfile
summary: Delete a load capture profile
description: >
Deletes a load capture profile and its stored artifacts from object
storage.
This endpoint requires an admin token.
responses:
'200':
description: The profile was deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. An admin token is required.
'404':
description: >-
The profile does not exist, or load capture is unavailable because
this node does not use the performance upgrade preview with an
explicit `--mode` setting that includes `query`.
'409':
description: >-
The profile is still capturing. Wait for it to finish (or its status
to catch up to `complete`), then retry.
tags:
- Load capture
- Enterprise
x-enterprise-only: true
x-influxdb-introduced-in: v3.10.0
/api/v3/loadcap/profiles/{profile_id}/preview:
parameters:
- $ref: '#/components/parameters/LoadCaptureProfileId'
get:
operationId: GetLoadcapProfilePreview
summary: Preview a load capture profile
description: >
Returns file counts, total size, and an anonymized catalog summary for a
load capture profile without downloading the archive. For `query`-only
captures, `catalog_summary` is null.
This endpoint requires an admin token.
responses:
'200':
description: Load capture profile preview.
content:
application/json:
schema:
$ref: '#/components/schemas/LoadCapturePreview'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. An admin token is required.
'404':
description: >-
The profile does not exist, or load capture is unavailable because
this node does not use the performance upgrade preview with an
explicit `--mode` setting that includes `query`.
tags:
- Load capture
- Enterprise
x-enterprise-only: true
x-influxdb-introduced-in: v3.10.0
/api/v3/loadcap/profiles/{profile_id}/download:
parameters:
- $ref: '#/components/parameters/LoadCaptureProfileId'
get:
operationId: GetLoadcapProfileDownload
summary: Download a load capture profile
description: >
Downloads the load capture profile as a gzipped tar archive containing
the anonymized capture artifacts---`catalog.json` and `.pt` write-ahead
log files for `write` and `both` captures, and `queries.json.zst` for
`query` and `both` captures.
This endpoint requires an admin token.
responses:
'200':
description: >-
The profile archive. The response `Content-Type` is
`application/gzip` and `Content-Disposition` provides the
`{profile_id}.tar.gz` filename.
content:
application/gzip:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. An admin token is required.
'404':
description: >-
The profile does not exist, or load capture is unavailable because
this node does not use the performance upgrade preview with an
explicit `--mode` setting that includes `query`.
tags:
- Load capture
- Enterprise
x-enterprise-only: true
x-influxdb-introduced-in: v3.10.0
/api/v3/plugin_test/schedule:
post:
operationId: PostTestSchedulingPlugin
responses:
'200':
description: Success. The plugin test has been executed.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Plugin not enabled.
summary: Test scheduling plugin
description: Executes a test of a scheduling plugin.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulePluginTestRequest'
tags:
- Processing engine
/api/v3/plugin_test/wal:
post:
operationId: PostTestWALPlugin
responses:
'200':
description: Success. The plugin test has been executed.
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Plugin not enabled.
summary: Test WAL plugin
description: Executes a test of a write-ahead logging (WAL) plugin.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WALPluginTestRequest'
tags:
- Processing engine
/api/v3/plugins/directory:
put:
operationId: PutPluginDirectory
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginDirectoryRequest'
responses:
'200':
description: Success. The plugin directory has been updated.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. Admin token required.
'500':
description: >-
Plugin not found. The `plugin_name` does not match any registered
trigger.
summary: Update a multi-file plugin directory
description: |
Replaces all files in a multi-file plugin directory. The
`plugin_name` must match a registered trigger name. Each entry in
the `files` array specifies a `relative_path` and `content`—the
server writes them into the trigger's plugin directory.
Use this endpoint to update multi-file plugins (directories with
`__init__.py` and supporting modules). For single-file plugins,
use `PUT /api/v3/plugins/files` instead.
tags:
- Processing engine
x-security-note: Requires an admin token
/api/v3/plugins/files:
post:
operationId: PostPluginsFiles
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginFileRequest'
responses:
'200':
description: Success. The plugin file has been created.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. Admin token required.
summary: Create a plugin file
description: |
Creates a single plugin file in the plugin directory. Writes the
`content` to a file named after `plugin_name`. Does not require an
existing trigger—use this to upload plugin files before creating
triggers that reference them.
tags:
- Processing engine
x-security-note: Requires an admin token
put:
operationId: PutPluginFile
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginFileRequest'
responses:
'200':
description: Success. The plugin file has been updated.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden. Admin token required.
'500':
description: >-
Plugin not found. The `plugin_name` does not match any registered
trigger.
summary: Update a plugin file
description: |
Updates a single plugin file for an existing trigger. The
`plugin_name` must match a registered trigger name—the server
resolves the trigger's `plugin_filename` and overwrites that file
with the provided `content`.
To upload a new plugin file before creating a trigger, use
`POST /api/v3/plugins/files` instead. To update a multi-file
plugin directory, use `PUT /api/v3/plugins/directory`.
tags:
- Processing engine
x-security-note: Requires an admin token
/api/v3/query_influxql:
get:
operationId: GetExecuteInfluxQLQuery
parameters:
- $ref: '#/components/parameters/dbQueryParam'
- name: q
in: query
required: true
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/AcceptQueryHeader'
- name: params
in: query
required: false
schema:
type: string
description: >-
JSON-encoded query parameters. Use this to pass bind parameters to
parameterized queries.
description: JSON-encoded query parameters for parameterized queries.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: QueryRequest
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query
description: >
Executes an InfluxQL query to retrieve data from the specified database.
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).
tags:
- Query data
post:
operationId: PostExecuteQueryInfluxQL
parameters:
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
requestBody:
$ref: '#/components/requestBodies/queryRequestBody'
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query
description: >
Executes an InfluxQL query to retrieve data from the specified database.
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).
tags:
- Query data
/api/v3/query_sql:
get:
operationId: GetExecuteQuerySQL
parameters:
- $ref: '#/components/parameters/db'
- $ref: '#/components/parameters/querySqlParam'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
- name: params
in: query
required: false
schema:
type: string
description: >-
JSON-encoded query parameters. Use this to pass bind parameters to
parameterized queries.
description: JSON-encoded query parameters for parameterized queries.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: QueryRequest
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
example:
results:
- series:
- name: mytable
columns:
- time
- value
values:
- - '2024-02-02T12:00:00Z'
- 42
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute SQL query
description: >
Executes an SQL query to retrieve data from the specified database.
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` endpoint after executing
a query to retrieve detailed execution statistics.
tags:
- Query data
post:
operationId: PostExecuteQuerySQL
parameters:
- $ref: '#/components/parameters/AcceptQueryHeader'
- $ref: '#/components/parameters/ContentType'
requestBody:
$ref: '#/components/requestBodies/queryRequestBody'
responses:
'200':
description: Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
text/csv:
schema:
type: string
application/vnd.apache.parquet:
schema:
type: string
application/jsonl:
schema:
type: string
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute SQL query
description: >
Executes an SQL query to retrieve data from the specified database.
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` endpoint after executing
a query to retrieve detailed execution statistics.
tags:
- Query data
/api/v3/roles:
get:
operationId: GetRoles
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/roles/{id}/permissions:
get:
operationId: GetRolesByIdPermissions
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
- Enterprise
/api/v3/roles_by_name/{roleName}:
get:
operationId: GetRolesByNameByRoleName
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
- Enterprise
/api/v3/row_delete_requests:
get:
operationId: GetRowDeleteRequests
parameters:
- name: db
in: query
required: false
schema:
type: string
- name: table
in: query
required: false
schema:
type: string
- name: disposition
in: query
required: false
schema:
type: string
- name: min_sequence
in: query
required: false
schema:
type: integer
- name: max_sequence
in: query
required: false
schema:
type: integer
- name: include_progress
in: query
required: false
schema:
type: boolean
description: 'Default: (default)'
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
post:
operationId: PostRowDeleteRequests
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/row_delete_requests/{seq}/abort:
post:
operationId: PostRowDeleteRequestsBySeqAbort
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
- Enterprise
/api/v3/users:
get:
operationId: GetUsers
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
post:
operationId: PostUsers
requestBody:
required: true
content:
application/json:
schema:
type: object
description: InviteUserRequest
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/users/{id}:
get:
operationId: GetUsersById
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/api/v3/users/{id}/require-password-reset:
post:
operationId: PostUsersByIdRequirePasswordReset
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
- Enterprise
/api/v3/users/{id}/roles:
get:
operationId: GetUsersByIdRoles
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
- Enterprise
put:
operationId: PutUsersByIdRoles
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
- Enterprise
/api/v3/users_by_oauth_id/{oauth_id}:
get:
operationId: GetUsersByOauthIdByOauthId
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
- Enterprise
/api/v3/write_lp:
post:
operationId: PostWriteLP
parameters:
- name: db
in: query
required: true
schema:
type: string
- name: precision
in: query
required: false
schema:
type: string
- name: accept_partial
in: query
required: false
description: >
Whether to write the valid lines when some lines in the batch are
rejected.
Default is `true`: InfluxDB writes the valid lines and returns `400`
with
`"partial write of line protocol occurred"` and the rejected lines.
With `false`, InfluxDB rejects the whole batch and writes nothing.
schema:
type: boolean
default: true
- name: no_sync
in: query
required: false
schema:
type: boolean
responses:
'204':
description: >-
Success ("No Content"). All data in the batch is written and
queryable.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'400':
description: >
Bad request. Some or all lines were rejected; the body lists each
rejected line.
With `accept_partial=true` (the default), the valid lines are
written and
the error is `"partial write of line protocol occurred"`.
With `accept_partial=false`, nothing is written.
In a database that uses explicit schemas (`schema_mode: explicit`,
Enterprise only), a line that writes an
undeclared table or column is rejected with a message that names it
and points to `/api/v3/configure/table`.
content:
application/json:
examples:
partialWrite:
summary: Partial write (default); line 1 was written
value: |
{
"error": "partial write of line protocol occurred",
"data": [
{
"error_message": "No fields were provided",
"line_number": 2,
"original_line": "home,room=Kitchen te"
}
]
}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
'422':
description: >
Unprocessable entity. The write would exceed a schema limit: the
number of
databases, tables, columns, tag columns, or fields. A partial write
whose
rejected lines hit a limit also returns `422` instead of `400`.
summary: Write line protocol
description: >
Writes line protocol 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**: By default (`accept_partial=true`), InfluxDB
writes the valid lines when some lines in a
batch fail. Set `accept_partial=false` to reject the whole batch instead.
- **Asynchronous writes**: Use `no_sync=true` to skip waiting for WAL
synchronization, allowing faster response
times but sacrificing durability guarantees
- **Flexible precision**: Automatic timestamp precision detection with
`precision=auto` (default)
#### 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.
'403':
description: Forbidden. The token doesn't have permission to call this endpoint.
'500':
description: Service is unavailable.
summary: Health check
description: >
Checks the status of the service.
Returns `OK` if the service is running. This endpoint does not return
version information.
Use the [`/ping`](#operation/GetPing) endpoint to retrieve version
details.
> **Note**: This endpoint requires authentication by default in InfluxDB
3 Enterprise.
A database-scoped resource token (for example, `db:DATABASE_NAME:read`)
gets `403` from this endpoint. For
health checks, use a token with the `system:health:read` permission, or
an admin token.
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
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The InfluxDB version number.
example: 3.8.0
revision:
type: string
description: The git revision hash for the build.
example: 83b589b883
process_id:
type: string
description: A unique identifier for the server process.
example: b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7
'401':
description: Unauthorized. Authentication is required.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'403':
description: Forbidden. The token doesn't have permission to call this endpoint.
'404':
description: |
Not Found. Returned for HEAD requests.
Use a GET request to retrieve version information.
summary: Ping the server
description: >
Returns version information for the server.
**Important**: Use a GET request. HEAD requests return `404 Not Found`.
The response includes version information in both headers and the JSON
body:
- **Headers**: `x-influxdb-version`, `x-influxdb-build`, and
`cluster-uuid`
(`cluster-uuid` is also returned on a `401`)
- **Body**: JSON object with `version`, `revision`, and `process_id`
> **Note**: This endpoint requires authentication by default in InfluxDB
3 Enterprise.
A database-scoped resource token (for example, `db:DATABASE_NAME:read`)
gets `403` from this endpoint. For
health checks, use a token with the `system:ping:read` permission, or an
admin token.
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
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The InfluxDB version number.
example: 3.8.0
revision:
type: string
description: The git revision hash for the build.
example: 83b589b883
process_id:
type: string
description: A unique identifier for the server process.
example: b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7
'401':
description: Unauthorized. Authentication is required.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'403':
description: Forbidden. The token doesn't have permission to call this endpoint.
'404':
description: |
Not Found. Returned for HEAD requests.
Use a GET request to retrieve version information.
summary: Ping the server
description: >-
Returns version information for the server. Accepts POST in addition to
GET.
tags:
- Server information
/query:
get:
operationId: GetV1ExecuteQuery
responses:
'200':
description: |
Success. The response body contains query results.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResponse'
application/csv:
schema:
type: string
headers:
Content-Type:
description: >
The content type of the response.
Default is `application/json`.
If the `Accept` request header is `application/csv` or
`text/csv`, the `Content-type` response header is
`application/csv`
and the response is formatted as CSV.
schema:
type: string
default: application/json
enum:
- application/json
- application/csv
'400':
description: Bad request.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'404':
description: Database not found.
'405':
description: Method not allowed.
'422':
description: Unprocessable entity.
summary: Execute InfluxQL query (v1-compatible)
description: >
Executes an InfluxQL query to retrieve data from the specified database.
This endpoint is compatible with InfluxDB 1.x client libraries and
third-party integrations such as Grafana.
Use query parameters to specify the database and the InfluxQL query.
#### Related
- [Use the InfluxDB v1 HTTP query API and InfluxQL to query
data](https://docs.influxdata.com/influxdb3/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
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
/ready:
get:
operationId: ready
responses:
'200':
description: Success
x-enterprise-only: true
tags:
- Enterprise
/write:
post:
operationId: PostV1Write
responses:
'204':
description: >-
Success ("No Content"). All data in the batch is written and
queryable.
headers:
cluster-uuid:
$ref: '#/components/headers/ClusterUUID'
'400':
description: >
Bad request. InfluxDB rejected the whole batch and wrote nothing.
This endpoint doesn't support partial writes: if any line is
invalid, no
lines are written, and an `accept_partial` parameter is ignored.
The body describes the first rejected line.
To write the valid lines of a batch, use `/api/v3/write_lp`.
content:
application/json:
examples:
rejectedBatch:
summary: One invalid line rejects the batch
value: |
{
"error": "line protocol parsing error",
"data": {
"error_message": "No fields were provided",
"line_number": 2,
"original_line": "home,room=Kitchen te"
}
}
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Access denied.
'413':
description: Request entity too large.
summary: Write line protocol (v1-compatible)
description: >
Writes line protocol to the specified database.
This endpoint provides backward compatibility for InfluxDB 1.x write
workloads using tools such as InfluxDB 1.x client libraries, the
Telegraf `outputs.influxdb` output plugin, or third-party tools.
Use this endpoint to send data in [line
protocol](https://docs.influxdata.com/influxdb3/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
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.
LoadCaptureProfileId:
x-enterprise-only: true
name: profile_id
in: path
required: true
schema:
type: string
format: uuid
description: Identifier of the load capture profile.
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
schema_mode:
type: string
enum:
- implicit
- explicit
default: implicit
description: >-
How tables in the database get their schemas. Set at creation and
can't be changed.
- `implicit` (default): writes create tables and columns.
- `explicit`: tables and columns are created only through the
configuration API, and writes that reference an undeclared table or
column are rejected.
Enterprise only; InfluxDB 3 Core returns `400 Bad Request`.
required:
- db
CreateTableRequest:
type: object
properties:
db:
type: string
table:
type: string
tags:
type: array
items:
type: string
fields:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
enum:
- utf8
- int64
- uint64
- float64
- bool
required:
- name
- type
retention_period:
type: string
description: >-
The retention period for the table. Specifies how long data in this
table should be retained.
Use duration format (for example, "1d", "1h", "30m", "7d").
example: 30d
required:
- db
- table
- tags
- fields
DistinctCacheCreateRequest:
type: object
properties:
db:
type: string
table:
type: string
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
PatchTableRequest:
type: object
description: >-
Tags and fields to add to an existing table. At least one tag or field
is required.
properties:
db:
type: string
table:
type: string
tags:
type: array
items:
type: string
fields:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
enum:
- utf8
- int64
- uint64
- float64
- bool
required:
- name
- type
required:
- db
- table
AuthorizationScope:
type: object
properties:
scope:
type: string
enum:
- all
- identifier
identifier:
type: string
description: >-
Resource name. Required when `scope` is `identifier`; not allowed
when `scope` is `all`.
required:
- scope
AuthorizationCheck:
type: object
description: >
Exactly one action to check.
Scoped actions take an `AuthorizationScope`; boolean actions must be
`true`.
minProperties: 1
maxProperties: 1
additionalProperties: false
properties:
describeDatabase:
$ref: '#/components/schemas/AuthorizationScope'
readDatabase:
$ref: '#/components/schemas/AuthorizationScope'
writeDatabase:
$ref: '#/components/schemas/AuthorizationScope'
deleteDatabase:
$ref: '#/components/schemas/AuthorizationScope'
readSystem:
$ref: '#/components/schemas/AuthorizationScope'
createDatabase:
type: boolean
const: true
readToken:
type: boolean
const: true
createToken:
type: boolean
const: true
deleteToken:
type: boolean
const: true
readUser:
type: boolean
const: true
createUser:
type: boolean
const: true
updateUser:
type: boolean
const: true
deleteUser:
type: boolean
const: true
readRole:
type: boolean
const: true
createRole:
type: boolean
const: true
updateRole:
type: boolean
const: true
deleteRole:
type: boolean
const: true
createAdminToken:
type: boolean
const: true
deleteAdminToken:
type: boolean
const: true
x-enterprise-only: true
AuthorizationResult:
type: object
properties:
authorized:
type: boolean
required:
- authorized
x-enterprise-only: true
ProcessingEngineTriggerRequest:
type: object
properties:
db:
type: string
plugin_filename:
type: string
description: >
The path and filename of the plugin to execute--for example,
`schedule.py` or `endpoints/report.py`.
The path can be absolute or relative to the `--plugin-dir` directory
configured when starting InfluxDB 3.
The plugin file must implement the trigger interface associated with
the trigger's specification.
Prefix the path with `gh:` to fetch the plugin remotely from the
configured `--plugin-repo` instead of reading it from the local
`--plugin-dir`--for example, `gh:examples/wal_plugin/wal_plugin.py`.
Despite the name, `gh:` doesn't require GitHub--`--plugin-repo`
accepts any HTTP/HTTPS URL that serves raw plugin files.
For defaults, fetch behavior, and limitations, see [Use example
plugins](https://docs.influxdata.com/influxdb3/enterprise/plugins/#use-example-plugins).
node_spec:
$ref: '#/components/schemas/ApiNodeSpec'
trigger_name:
type: string
trigger_settings:
allOf:
- $ref: '#/components/schemas/TriggerSettings'
trigger_specification:
description: >
Specifies when and how the processing engine trigger should be
invoked.
## Supported trigger specifications:
### Cron-based scheduling
Format: `cron:CRON_EXPRESSION`
Uses extended (6-field) cron format (second minute hour day_of_month
month day_of_week):
```
┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31)
│ │ │ │ ┌───────────── month (1-12)
│ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │ │
* * * * * *
```
Examples:
- `cron:0 0 6 * * 1-5` - Every weekday at 6:00 AM
- `cron:0 30 14 * * 5` - Every Friday at 2:30 PM
- `cron:0 0 0 1 * *` - First day of every month at midnight
### Interval-based scheduling
Format: `every:DURATION`
Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d`
(days), `w` (weeks), `M` (months), `y` (years):
- `every:30s` - Every 30 seconds
- `every:5m` - Every 5 minutes
- `every:1h` - Every hour
- `every:1d` - Every day
- `every:1w` - Every week
- `every:1M` - Every month
- `every:1y` - Every year
**Maximum interval**: 1 year
### Table-based triggers
- `all_tables` - Triggers on write events to any table in the
database
- `table:TABLE_NAME` - Triggers on write events to a specific table
### On-demand triggers
Format: `request:REQUEST_PATH`
Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual
invocation:
- `request:hello-world` - Creates endpoint
`/api/v3/engine/hello-world`
- `request:data-export` - Creates endpoint
`/api/v3/engine/data-export`
pattern: >-
^(cron:[0-9
*,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|request:[a-zA-Z0-9_-]+)$
example: cron:0 0 6 * * 1-5
trigger_arguments:
type: object
additionalProperties:
type: string
description: >
Optional, plugin-specific arguments passed to the plugin entry point
as its `args` dictionary.
Provide string key-value pairs. Omit this field to pass `None` as
`args`.
Refer to the plugin documentation for supported argument names and
values.
example:
threshold: '90'
target_table: alerts
disabled:
type: boolean
default: false
description: Whether the trigger is disabled.
required:
- db
- plugin_filename
- trigger_name
- trigger_specification
TriggerSettings:
type: object
properties:
run_async:
type: boolean
default: false
description: >
Whether invocations of the trigger can run concurrently.
If `false`, invocations run serially--each invocation must finish
before the next one starts.
In a cluster with multiple process nodes, the trigger runs on one
process node at a time.
If `true`, invocations can run concurrently, up to the
`--async-trigger-concurrency-limit`
server option (default: `8`).
In a cluster with multiple process nodes, pending invocations are
distributed across all process nodes.
error_behavior:
type: string
default: log
enum:
- log
- retry
- disable
description: >
How the trigger responds when the plugin returns an error:
- `log`: Log the error and keep the trigger active.
- `retry`: Retry the failed invocation with exponential backoff (up
to 5 attempts), then log the failure. Errors identified as permanent
aren't retried.
- `disable`: Disable the trigger until you manually re-enable it.
ApiNodeSpec:
x-enterprise-only: true
description: |
Specifies which nodes in a multi-node InfluxDB 3 Enterprise cluster
handle the cache or trigger.
Accepts the string `all` or an object that lists specific node IDs.
If omitted, defaults to `all`.
default: all
example: all
oneOf:
- type: string
enum:
- all
description: |
Create the cache or trigger on all nodes in the cluster.
- type: object
description: |
Create the cache or trigger only on the specified nodes.
properties:
nodes:
type: array
items:
type: string
description: |
Node IDs (the `--node-id` value each node was started with).
Each node must exist and must run in `process` mode.
required:
- nodes
additionalProperties: false
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.
LoadCaptureStartRequest:
type: object
description: Request body for starting a timed load capture.
properties:
type:
type: string
description: The request types to capture.
enum:
- write
- query
- both
duration:
type: string
description: >-
Capture duration using seconds, minutes, or hours. The maximum
duration is one hour.
example: 5m
required:
- type
- duration
LoadCaptureStartResponse:
type: object
description: Response returned after a load capture starts.
properties:
profile_id:
type: string
format: uuid
description: Identifier of the new load capture profile.
required:
- profile_id
LoadCaptureProfile:
type: object
description: Metadata for a load capture profile.
properties:
profile_id:
type: string
format: uuid
description: Identifier of the load capture profile.
created_at:
type: string
format: date-time
description: Time when the capture started.
type:
type: string
enum:
- write
- query
- both
description: The request types captured by the profile.
duration:
type: string
description: Requested capture duration.
node_id:
type: integer
description: Identifier of the node that owns the profile.
status:
type: string
enum:
- running
- complete
- aborted
description: Current capture status.
wal_dropped:
type: integer
minimum: 0
description: Number of write-ahead log files that could not be captured.
query_dropped:
type: integer
minimum: 0
description: Number of queries that could not be captured.
unparseable_queries:
type: integer
minimum: 0
description: Number of queries replaced because they could not be parsed safely.
LoadCapturePreview:
type: object
description: >-
Contents summary for a load capture profile, including an anonymized
catalog summary. Returned by the profile details and preview endpoints.
properties:
profile_id:
type: string
format: uuid
description: Identifier of the load capture profile.
file_count:
type: integer
minimum: 0
description: Total number of files in the profile archive.
total_size_bytes:
type: integer
minimum: 0
description: Total size of the profile archive contents, in bytes.
wal_file_count:
type: integer
minimum: 0
description: Number of anonymized write-ahead log (`.pt`) files in the profile.
query_count:
type: integer
minimum: 0
description: Number of captured queries in the profile.
catalog_summary:
type: object
nullable: true
description: >-
Anonymized catalog snapshot taken when the capture started,
including databases, tables, columns, and node metadata. Null for
`query`-only captures.
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
RemoveNodeRequest:
type: object
description: Request body for permanently removing a stopped node from the cluster.
properties:
node_id:
type: string
description: The ID of the node to remove.
force_finalize:
type: boolean
description: >-
Force-finalize a node stuck in the `Stopping` state (for example,
after a crash that never acknowledged the stop). This can delete
unsnapshotted WAL data for that node — only use it when the node's
process is confirmed gone and you accept the data-loss risk.
default: false
required:
- node_id
example:
node_id: node-1
ParquetCleanupRequest:
type: object
description: |
Request body for `POST /api/v3/enterprise/upgrade/parquet_cleanup`.
An empty body is equivalent to the defaults (a real deletion).
properties:
dry_run:
type: boolean
description: >
When `true`, only count and size the Parquet-era data a real cleanup
would delete.
Delete nothing.
default: false
example:
dry_run: false
ParquetCleanupResponse:
type: object
description: Response body for `POST /api/v3/enterprise/upgrade/parquet_cleanup`.
properties:
state:
type: string
enum:
- started
- already_running
- already_completed
description: The outcome of this cleanup request.
status:
$ref: '#/components/schemas/ParquetCleanupStatusSnapshot'
required:
- state
- status
ParquetCleanupStatusSnapshot:
type: object
description: >
Point-in-time view of the durable Parquet cleanup state.
Returned by `GET /api/v3/enterprise/upgrade/parquet_cleanup` and
embedded in the POST response.
properties:
status:
type: string
enum:
- requested
- running
- completed
- failed
description: The cleanup's current status.
mode:
type: string
enum:
- delete
- dry_run
description: >-
Whether this cleanup deletes data or only reports what it would
delete.
requested_by:
type: string
nullable: true
description: The node that accepted the cleanup request, if recorded.
files_scanned:
type: integer
format: int64
description: Number of files the cleanup has scanned so far.
files_matched:
type: integer
format: int64
description: Number of files identified as Parquet-era data to delete.
bytes_matched:
type: integer
format: int64
description: Total size, in bytes, of the matched files.
files_deleted:
type: integer
format: int64
description: |
Number of files deleted so far.
Always `0` in `dry_run` mode.
bytes_deleted:
type: integer
format: int64
description: |
Total size, in bytes, of the deleted files.
Always `0` in `dry_run` mode.
files_failed:
type: integer
format: int64
description: Number of files the cleanup failed to delete.
requested_at_ns:
type: integer
format: int64
nullable: true
description: When the cleanup was requested, in nanoseconds since the Unix epoch.
started_at_ns:
type: integer
format: int64
nullable: true
description: >-
When the cleanup started running, in nanoseconds since the Unix
epoch.
completed_at_ns:
type: integer
format: int64
nullable: true
description: When the cleanup finished, in nanoseconds since the Unix epoch.
updated_at_ns:
type: integer
format: int64
nullable: true
description: >-
When this status was last updated, in nanoseconds since the Unix
epoch.
last_message:
type: string
nullable: true
description: The most recent human-readable status message, if any.
required:
- status
- mode
- files_scanned
- files_matched
- bytes_matched
- files_deleted
- bytes_deleted
- files_failed
example:
status: completed
mode: delete
requested_by: node-1
files_scanned: 1024
files_matched: 812
bytes_matched: 4294967296
files_deleted: 812
bytes_deleted: 4294967296
files_failed: 0
requested_at_ns: 1735689600000000000
started_at_ns: 1735689601000000000
completed_at_ns: 1735689900000000000
updated_at_ns: 1735689900000000000
last_message: null
UpgradeRetryResponse:
type: object
description: >-
Response body for `POST
/api/v3/enterprise/upgrade/retry_parquet_to_pacha_tree`.
properties:
entries_inspected:
type: integer
format: int64
description: >-
Terminal failures the retry re-checked against the catalog and
object store.
entries_skipped_source_missing:
type: integer
format: int64
description: Entries skipped because their source object no longer exists.
entries_skipped_table_dropped:
type: integer
format: int64
description: Entries skipped because their table was dropped.
entries_requeued:
type: integer
format: int64
description: >-
Entries returned to the queue because their source is still
readable.
entries_already_skipped:
type: integer
format: int64
description: Terminal failures that were already recorded as skips.
entries_already_converted:
type: integer
format: int64
description: |
Entries whose sequence already held converted data.
Recorded as imported instead of skipped.
entries_unresolved:
type: integer
format: int64
description: >
Entries left untouched because the object holding their sequence
couldn't be read back.
Run this endpoint again to re-attempt them.
upgrade_status:
type: string
description: The status the enterprise upgrade state was left in after the retry.
message:
type: string
description: What to do next.
required:
- entries_inspected
- entries_skipped_source_missing
- entries_skipped_table_dropped
- entries_requeued
- entries_already_skipped
- entries_already_converted
- entries_unresolved
- upgrade_status
- message
example:
entries_inspected: 3
entries_skipped_source_missing: 1
entries_skipped_table_dropped: 0
entries_requeued: 2
entries_already_skipped: 0
entries_already_converted: 0
entries_unresolved: 0
upgrade_status: upgrading
message: >-
Migration state reset. Restart the compactor node with
--upgrade-pacha-tree to resume the upgrade.
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.
BulkImportObjectStoreRequest:
type: object
description: >-
Request body for a bulk import that pulls Parquet files from object
storage.
properties:
database:
type: string
description: The target database name. The database must already exist.
table:
type: string
description: The target table name. The table must already exist.
source:
type: string
description: >-
Where to read Parquet files: a prefix in the cluster's own object
store (for example, `staging/exports/`), or an `s3://bucket/prefix`
URL. Every Parquet file under the prefix is imported.
column_metadata:
$ref: '#/components/schemas/ColumnMetadata'
required:
- database
- table
- source
BulkImportJobStatus:
type: string
enum:
- queued
- dispatched
- imported
- compacted
- failed
- terminal_failed
description: >-
The status of a bulk import job. A successful job moves through
`queued`, `imported`, and `compacted`; its rows become queryable once
it's `compacted`, not when it's `imported`.
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 the time
column's Parquet statistics. `0` when the file has no statistics the
server can read; the imported data isn't affected.
max_timestamp_ns:
type: integer
format: int64
description: >-
The maximum timestamp in the file (nanoseconds), from the time
column's Parquet statistics. `0` when the file has no statistics the
server can read; the imported data isn't affected.
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/GetV1ExecuteQuery) endpoints in InfluxDB 3.
When authenticating requests, InfluxDB 3 checks that the `password` part
of the decoded credential is an authorized token
and ignores the `username` part of the decoded credential.
### Syntax
```http
Authorization: Basic
```
### Example
```bash
curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \
--user "":"AUTH_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB 3 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/GetV1ExecuteQuery) endpoints.
When authenticating requests, InfluxDB 3 checks that the `p`
(_password_) query parameter is an authorized token
and ignores the `u` (_username_) query parameter.
### Syntax
```http
https://localhost:8181/query/?[u=any]&p=AUTH_TOKEN
https://localhost:8181/write/?[u=any]&p=AUTH_TOKEN
```
### Examples
```bash
curl
"http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=AUTH_TOKEN"
\
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
Replace the following:
- **`DATABASE_NAME`**: your InfluxDB 3 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