2076 lines
68 KiB
YAML
2076 lines
68 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: InfluxDB 3 Core API Service
|
|
description: |
|
|
The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for
|
|
interacting with InfluxDB 3 Core databases and resources.
|
|
Use this API to:
|
|
|
|
- Write data to InfluxDB 3 Core databases
|
|
- Query data using SQL or InfluxQL
|
|
- Process data using Processing engine plugins
|
|
- Manage databases, tables, and Processing engine triggers
|
|
- Perform administrative tasks and access system information
|
|
|
|
The API includes endpoints under the following paths:
|
|
- `/api/v3`: InfluxDB 3 Core native endpoints
|
|
- `/`: Compatibility endpoints for InfluxDB v1 workloads and clients
|
|
- `/api/v2/write`: Compatibility endpoint for InfluxDB v2 workloads and clients
|
|
|
|
<!-- TODO: verify where to host the spec that users can download.
|
|
This documentation is generated from the
|
|
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/).
|
|
-->
|
|
version: ''
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
contact:
|
|
name: InfluxData
|
|
url: https://www.influxdata.com
|
|
email: support@influxdata.com
|
|
servers:
|
|
- url: https://{baseurl}
|
|
description: InfluxDB 3 Core API URL
|
|
variables:
|
|
baseurl:
|
|
enum:
|
|
- localhost:8181
|
|
default: localhost:8181
|
|
description: InfluxDB 3 Core URL
|
|
security:
|
|
- BearerAuth: []
|
|
tags:
|
|
- name: Authentication
|
|
description: |
|
|
Authenticate to the InfluxDB 3 API using a bearer token.
|
|
|
|
The InfluxDB 3 API uses tokens for authentication.
|
|
To authenticate, include the `Authorization` header in your request with the value `Bearer <token>`.
|
|
The token must be a valid InfluxDB 3 admin token.
|
|
|
|
#### Related guides
|
|
|
|
- [Manage tokens](/influxdb3/core/admin/tokens/)
|
|
- [Authentication and authorization](/influxdb3/core/reference/internals/authentication/)
|
|
x-traitTag: true
|
|
- name: Cache data
|
|
description: |
|
|
Manage the in-memory cache.
|
|
|
|
#### Distinct Value Cache
|
|
|
|
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 an 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.
|
|
|
|
#### Last value cache
|
|
|
|
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.
|
|
|
|
#### Related guides
|
|
|
|
- [Manage the Distinct Value Cache](/influxdb3/core/admin/distinct-value-cache/)
|
|
- [Manage the Last Value Cache](/influxdb3/core/admin/last-value-cache/)
|
|
- name: Compatibility endpoints
|
|
description: |
|
|
InfluxDB 3 provides compatibility endpoints for InfluxDB 1.x and InfluxDB 2.x workloads and clients.
|
|
|
|
### Write data using v1- or v2-compatible endpoints
|
|
|
|
- [`/api/v2/write` endpoint](#operation/PostV2Write)
|
|
for InfluxDB v2 clients and when you bring existing InfluxDB v2 write workloads to InfluxDB 3.
|
|
- [`/write` endpoint](#operation/PostV1Write) for InfluxDB v1 clients and when you bring existing InfluxDB v1 write workloads to InfluxDB 3.
|
|
|
|
For new workloads, use the [`/api/v3/write_lp` endpoint](#operation/PostWriteLP).
|
|
|
|
All endpoints accept the same line protocol format.
|
|
|
|
### Query data
|
|
|
|
Use the HTTP [`/query`](#operation/GetV1ExecuteQuery) endpoint for InfluxDB v1 clients and v1 query workloads using InfluxQL.
|
|
|
|
For new workloads, use one of the following:
|
|
|
|
- HTTP [`/api/v3/query_sql` endpoint](#operation/GetExecuteQuerySQL) for new query workloads using SQL.
|
|
- HTTP [`/api/v3/query_influxql` endpoint](#operation/GetExecuteInfluxQLQuery) for new query workloads using InfluxQL.
|
|
- Flight SQL and InfluxDB 3 _Flight+gRPC_ APIs for querying with SQL or InfluxQL. For more information about using Flight APIs, see [InfluxDB 3 client libraries](https://github.com/InfluxCommunity?q=influxdb3&type=public&language=&sort=).
|
|
|
|
### Server information
|
|
|
|
Server information endpoints such as `/health` and `metrics` are compatible with InfluxDB 1.x and InfluxDB 2.x clients.
|
|
- name: Database
|
|
description: Manage databases
|
|
- description: |
|
|
Most InfluxDB API endpoints require parameters in the request--for example, specifying the database to use.
|
|
|
|
### Common parameters
|
|
|
|
The following table shows common parameters used by many InfluxDB API endpoints.
|
|
Many endpoints may require other parameters in the query string or in the
|
|
request body that perform functions specific to those endpoints.
|
|
|
|
| Query parameter | Value type | Description |
|
|
|:------------------------ |:--------------------- |:-------------------------------------------|
|
|
| `db` | string | The database name |
|
|
|
|
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
|
|
The following table shows common headers used by many InfluxDB API endpoints.
|
|
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
|
|
the write endpoints accept the `Content-Encoding` header to indicate that line protocol is compressed in the request body.
|
|
|
|
| Header | Value type | Description |
|
|
|:------------------------ |:--------------------- |:-------------------------------------------|
|
|
| `Accept` | string | The content type that the client can understand. |
|
|
| `Authorization` | string | The authorization scheme and credential. |
|
|
| `Content-Length` | integer | The size of the entity-body, in bytes. |
|
|
| `Content-Type` | string | The format of the data in the request body. |
|
|
name: Headers and parameters
|
|
x-traitTag: true
|
|
- name: Processing engine
|
|
description: |
|
|
Manage Processing engine triggers, test plugins, and send requests to trigger On Request plugins.
|
|
|
|
InfluxDB 3 Core provides the InfluxDB 3 processing engine, an embedded Python VM that can dynamically load and trigger Python plugins in response to events in your database.
|
|
Use Processing engine plugins and triggers to run code and perform tasks for different database events.
|
|
|
|
To get started with the processing engine, see the [Processing engine and Python plugins](/influxdb3/core/processing-engine/) guide.
|
|
- name: Query data
|
|
description: Query data using SQL or InfluxQL
|
|
- name: Quick start
|
|
description: |
|
|
1. [Create an admin token](#section/Authentication) to authorize API requests.
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8181/api/v3/configure/token/admin"
|
|
```
|
|
2. [Check the status](#section/Server-information) of the InfluxDB server.
|
|
|
|
```bash
|
|
curl "http://localhost:8181/health" \
|
|
--header "Authorization: Bearer ADMIN_TOKEN"
|
|
```
|
|
|
|
3. [Write data](#operation/PostWriteLP) 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](#operation/GetExecuteQuerySQL) from InfluxDB.
|
|
|
|
```bash
|
|
curl -G "http://localhost:8181/api/v3/query_sql" \
|
|
--header "Authorization: Bearer ADMIN_TOKEN" \
|
|
--data-urlencode "db=sensors" \
|
|
--data-urlencode "q=SELECT * FROM home WHERE room='Living room'" \
|
|
--data-urlencode "format=jsonl"
|
|
```
|
|
|
|
Output:
|
|
|
|
```jsonl
|
|
{"room":"Living room","temp":71.5,"time":"2025-02-25T20:19:34.984098"}
|
|
```
|
|
|
|
For more information about using InfluxDB 3 Core, see the [Get started](/influxdb3/core/get-started/) guide.
|
|
x-traitTag: true
|
|
- name: Server information
|
|
description: Retrieve server metrics, status, and version information
|
|
- name: Table
|
|
description: Manage table schemas and data
|
|
- name: Token
|
|
description: Manage tokens for authentication and authorization
|
|
- name: Write data
|
|
description: Write data to InfluxDB 3
|
|
paths:
|
|
/write:
|
|
post:
|
|
operationId: PostV1Write
|
|
summary: Write line protocol (v1-compatible)
|
|
description: |
|
|
Writes line protocol to the specified database.
|
|
|
|
This endpoint provides backward compatibility for InfluxDB 1.x write workloads using tools such as InfluxDB 1.x client libraries, the Telegraf `outputs.influxdb` output plugin, or third-party tools.
|
|
|
|
Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
|
|
Use query parameters to specify options for writing data.
|
|
parameters:
|
|
- $ref: '#/components/parameters/dbWriteParam'
|
|
- $ref: '#/components/parameters/compatibilityPrecisionParam'
|
|
- 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'
|
|
responses:
|
|
'204':
|
|
description: Success ("No Content"). All data in the batch is written and queryable.
|
|
'400':
|
|
description: |
|
|
Bad request. Some (a _partial write_) or all of the data from the batch was rejected and not written.
|
|
If a partial write occurred, then some points from the batch are written and queryable.
|
|
|
|
The response body:
|
|
- indicates if a partial write occurred or all data was rejected.
|
|
- contains details about the [rejected points](/influxdb3/core/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
|
|
content:
|
|
application/json:
|
|
examples:
|
|
rejectedAllPoints:
|
|
summary: Rejected all points in the batch
|
|
value: |
|
|
{
|
|
"error": "write of line protocol failed",
|
|
"data": [
|
|
{
|
|
"original_line": "dquote> home,room=Kitchen temp=hi",
|
|
"line_number": 2,
|
|
"error_message": "No fields were provided"
|
|
}
|
|
]
|
|
}
|
|
partialWriteErrorWithRejectedPoints:
|
|
summary: Partial write rejected some points in the batch
|
|
value: |
|
|
{
|
|
"error": "partial write of line protocol occurred",
|
|
"data": [
|
|
{
|
|
"original_line": "dquote> home,room=Kitchen temp=hi",
|
|
"line_number": 2,
|
|
"error_message": "No fields were provided"
|
|
}
|
|
]
|
|
}
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'413':
|
|
description: Request entity too large.
|
|
tags:
|
|
- Compatibility endpoints
|
|
- Write data
|
|
/api/v2/write:
|
|
post:
|
|
operationId: PostV2Write
|
|
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](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
|
|
Use query parameters to specify options for writing data.
|
|
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: db
|
|
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.
|
|
- name: accept_partial
|
|
in: query
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/AcceptPartial'
|
|
- $ref: '#/components/parameters/compatibilityPrecisionParam'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/lineProtocolRequestBody'
|
|
responses:
|
|
'204':
|
|
description: Success ("No Content"). All data in the batch is written and queryable.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'413':
|
|
description: Request entity too large.
|
|
tags:
|
|
- Compatibility endpoints
|
|
- Write data
|
|
/api/v3/write_lp:
|
|
post:
|
|
operationId: PostWriteLP
|
|
summary: Write line protocol
|
|
description: |
|
|
Writes line protocol to the specified database.
|
|
|
|
Use this endpoint to send data in [line protocol](/influxdb3/core/reference/syntax/line-protocol/) format to InfluxDB.
|
|
Use query parameters to specify options for writing data.
|
|
parameters:
|
|
- $ref: '#/components/parameters/dbWriteParam'
|
|
- $ref: '#/components/parameters/accept_partial'
|
|
- $ref: '#/components/parameters/precisionParam'
|
|
- name: no_sync
|
|
in: query
|
|
schema:
|
|
$ref: '#/components/schemas/NoSync'
|
|
- name: Content-Type
|
|
in: header
|
|
description: |
|
|
The content type of the request payload.
|
|
schema:
|
|
$ref: '#/components/schemas/LineProtocol'
|
|
required: false
|
|
- name: Accept
|
|
in: header
|
|
description: |
|
|
The content type that the client can understand.
|
|
Writes only return a response body if they fail (partially or completely)--for example,
|
|
due to a syntax problem or type mismatch.
|
|
schema:
|
|
type: string
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
required: false
|
|
- $ref: '#/components/parameters/ContentEncoding'
|
|
- $ref: '#/components/parameters/ContentLength'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/lineProtocolRequestBody'
|
|
responses:
|
|
'204':
|
|
description: Success ("No Content"). All data in the batch is written and queryable.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
description: Access denied.
|
|
'413':
|
|
description: Request entity too large.
|
|
'422':
|
|
description: Unprocessable entity.
|
|
tags:
|
|
- Write data
|
|
/api/v3/query_sql:
|
|
get:
|
|
operationId: GetExecuteQuerySQL
|
|
summary: Execute SQL query
|
|
description: Executes an SQL query to retrieve data from the specified database.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- $ref: '#/components/parameters/querySqlParam'
|
|
- $ref: '#/components/parameters/format'
|
|
- $ref: '#/components/parameters/AcceptQueryHeader'
|
|
- $ref: '#/components/parameters/ContentType'
|
|
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.
|
|
tags:
|
|
- Query data
|
|
post:
|
|
operationId: PostExecuteQuerySQL
|
|
summary: Execute SQL query
|
|
description: Executes an SQL query to retrieve data from the specified database.
|
|
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.
|
|
tags:
|
|
- Query data
|
|
/api/v3/query_influxql:
|
|
get:
|
|
operationId: GetExecuteInfluxQLQuery
|
|
summary: Execute InfluxQL query
|
|
description: Executes an InfluxQL query to retrieve data from the specified database.
|
|
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'
|
|
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.
|
|
tags:
|
|
- Query data
|
|
post:
|
|
operationId: PostExecuteQueryInfluxQL
|
|
summary: Execute InfluxQL query
|
|
description: Executes an InfluxQL query to retrieve data from the specified database.
|
|
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.
|
|
tags:
|
|
- Query data
|
|
/query:
|
|
get:
|
|
operationId: GetV1ExecuteQuery
|
|
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.
|
|
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](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision
|
|
instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
|
|
in: query
|
|
schema:
|
|
$ref: '#/components/schemas/EpochCompatibility'
|
|
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.
|
|
tags:
|
|
- Query data
|
|
- Compatibility endpoints
|
|
post:
|
|
operationId: PostExecuteV1Query
|
|
summary: Execute InfluxQL query (v1-compatible)
|
|
description: Executes an InfluxQL query to retrieve data from the specified database.
|
|
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](/influxdb3/core/reference/glossary/#unix-timestamp) with the specified precision
|
|
instead of [RFC3339 timestamps](/influxdb3/core/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
|
|
enum:
|
|
- ns
|
|
- u
|
|
- µ
|
|
- ms
|
|
- s
|
|
- m
|
|
- h
|
|
type: string
|
|
pretty:
|
|
description: |
|
|
If true, the JSON response is formatted in a human-readable format.
|
|
type: boolean
|
|
required:
|
|
- q
|
|
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.
|
|
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.
|
|
tags:
|
|
- Query data
|
|
- Compatibility endpoints
|
|
/health:
|
|
get:
|
|
operationId: GetHealth
|
|
summary: Health check
|
|
description: Checks the status of the service.
|
|
responses:
|
|
'200':
|
|
description: Service is running.
|
|
'500':
|
|
description: Service is unavailable.
|
|
tags:
|
|
- Server information
|
|
/api/v1/health:
|
|
get:
|
|
operationId: GetHealthV1
|
|
summary: Health check (v1)
|
|
description: Checks the status of the service.
|
|
responses:
|
|
'200':
|
|
description: Service is running.
|
|
'500':
|
|
description: Service is unavailable.
|
|
tags:
|
|
- Server information
|
|
- Compatibility endpoints
|
|
/ping:
|
|
get:
|
|
operationId: GetPing
|
|
tags:
|
|
- Server information
|
|
summary: Ping the server
|
|
description: Returns version information for the server.
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains server information.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
example:
|
|
version: 0.1.0
|
|
revision: f3d3d3d
|
|
/metrics:
|
|
get:
|
|
operationId: GetMetrics
|
|
summary: Metrics
|
|
description: Retrieves Prometheus-compatible server metrics.
|
|
responses:
|
|
'200':
|
|
description: Success. The response body contains Prometheus-compatible server metrics.
|
|
tags:
|
|
- Server information
|
|
/api/v3/configure/database:
|
|
get:
|
|
operationId: GetConfigureDatabase
|
|
summary: List databases
|
|
description: Retrieves a list of databases.
|
|
parameters:
|
|
- $ref: '#/components/parameters/formatRequired'
|
|
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.
|
|
tags:
|
|
- Database
|
|
post:
|
|
operationId: PostConfigureDatabase
|
|
summary: Create a database
|
|
description: Creates a new database in the system.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateDatabaseRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. Database created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'409':
|
|
description: Database already exists.
|
|
tags:
|
|
- Database
|
|
delete:
|
|
operationId: DeleteConfigureDatabase
|
|
summary: Delete a database
|
|
description: |
|
|
Soft deletes a database.
|
|
The database is scheduled for deletion and unavailable for querying.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
responses:
|
|
'200':
|
|
description: Success. Database deleted.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Database not found.
|
|
tags:
|
|
- Database
|
|
/api/v3/configure/table:
|
|
post:
|
|
operationId: PostConfigureTable
|
|
summary: Create a table
|
|
description: Creates a new table within a database.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateTableRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. The table has been created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Database not found.
|
|
tags:
|
|
- Table
|
|
delete:
|
|
operationId: DeleteConfigureTable
|
|
summary: Delete a table
|
|
description: |
|
|
Soft deletes a table.
|
|
The table is scheduled for deletion and unavailable for querying.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- name: table
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Success (no content). The table has been deleted.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Table not found.
|
|
tags:
|
|
- Table
|
|
/api/v3/configure/distinct_cache:
|
|
post:
|
|
operationId: PostConfigureDistinctCache
|
|
summary: Create distinct cache
|
|
description: Creates a distinct cache for a table.
|
|
tags:
|
|
- Cache data
|
|
- Table
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DistinctCacheCreateRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. The distinct cache has been created.
|
|
'204':
|
|
description: Not created. A distinct cache with this configuration already exists.
|
|
'400':
|
|
description: |
|
|
Bad request.
|
|
|
|
The server responds with status `400` if the request would overwrite an existing cache with a different configuration.
|
|
/api/v3/configure/last_cache:
|
|
post:
|
|
operationId: PostConfigureLastCache
|
|
summary: Create last cache
|
|
description: Creates a last cache for a table.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LastCacheCreateRequest'
|
|
responses:
|
|
'201':
|
|
description: Success. Last cache created.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Cache not found.
|
|
'409':
|
|
description: Cache already exists.
|
|
tags:
|
|
- Cache data
|
|
- Table
|
|
delete:
|
|
operationId: DeleteConfigureLastCache
|
|
summary: Delete last cache
|
|
description: Deletes a last cache.
|
|
parameters:
|
|
- $ref: '#/components/parameters/db'
|
|
- name: table
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: name
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Success. The last cache has been deleted.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Cache not found.
|
|
tags:
|
|
- Cache data
|
|
- Table
|
|
/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.
|
|
|
|
### Related guides
|
|
|
|
- [Processing engine and Python plugins](/influxdb3/core/plugins/)
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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: path:hello-world
|
|
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
|
|
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 * *
|
|
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
|
|
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:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProcessingEngineTriggerRequest'
|
|
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:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProcessingEngineTriggerRequest'
|
|
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/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.
|
|
|
|
### Related guides
|
|
|
|
- [Processing engine and Python plugins](/influxdb3/core/plugins/)
|
|
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 (e.g., "scipy==1.9.0").
|
|
example:
|
|
- influxdb3-python
|
|
- scipy
|
|
- pandas==1.5.0
|
|
- requests
|
|
required:
|
|
- packages
|
|
example:
|
|
packages:
|
|
- influxdb3-python
|
|
- scipy
|
|
- pandas==1.5.0
|
|
- requests
|
|
responses:
|
|
'200':
|
|
description: Success. The packages are installed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/configure/plugin_environment/install_requirements:
|
|
post:
|
|
operationId: PostInstallPluginRequirements
|
|
summary: Install plugin requirements
|
|
description: |
|
|
Installs requirements from a requirements file (also known as a "pip requirements file") into the processing engine plugin environment.
|
|
|
|
This endpoint is synchronous and blocks until the requirements are installed.
|
|
|
|
### Related
|
|
|
|
- [Processing engine and Python plugins](/influxdb3/core/plugins/)
|
|
- [Python requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/)
|
|
parameters:
|
|
- $ref: '#/components/parameters/ContentType'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
requirements_location:
|
|
type: string
|
|
description: |
|
|
The path to the requirements file containing Python packages to install.
|
|
Can be a relative path (relative to the plugin directory) or an absolute path.
|
|
example: requirements.txt
|
|
required:
|
|
- requirements_location
|
|
example:
|
|
requirements_location: requirements.txt
|
|
responses:
|
|
'200':
|
|
description: Success. The requirements have been installed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/plugin_test/wal:
|
|
post:
|
|
operationId: PostTestWALPlugin
|
|
summary: Test WAL plugin
|
|
description: Executes a test of a write-ahead logging (WAL) plugin.
|
|
responses:
|
|
'200':
|
|
description: Success. The plugin test has been executed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Plugin not enabled.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/plugin_test/schedule:
|
|
post:
|
|
operationId: PostTestSchedulingPlugin
|
|
summary: Test scheduling plugin
|
|
description: Executes a test of a scheduling plugin.
|
|
responses:
|
|
'200':
|
|
description: Success. The plugin test has been executed.
|
|
'400':
|
|
description: Bad request.
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: Plugin not enabled.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/engine/{plugin_path}:
|
|
parameters:
|
|
- name: plugin_path
|
|
description: |
|
|
The path configured in the request trigger specification "path:<plugin_path>"` for the plugin.
|
|
|
|
For example, if you define a trigger with the following:
|
|
|
|
```json
|
|
trigger-spec: "path:hello-world"
|
|
```
|
|
|
|
then, the HTTP API exposes the following plugin endpoint:
|
|
|
|
```
|
|
<INFLUXDB3_HOST>/api/v3/engine/hello-world
|
|
```
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
get:
|
|
operationId: GetProcessingEnginePluginRequest
|
|
summary: On Request processing engine plugin request
|
|
description: |
|
|
Executes the On Request processing engine plugin specified in `<plugin_path>`.
|
|
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.
|
|
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.
|
|
tags:
|
|
- Processing engine
|
|
post:
|
|
operationId: PostProcessingEnginePluginRequest
|
|
summary: On Request processing engine plugin request
|
|
description: |
|
|
Executes the On Request processing engine plugin specified in `<plugin_path>`.
|
|
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
|
|
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.
|
|
tags:
|
|
- Processing engine
|
|
/api/v3/configure/token/admin:
|
|
post:
|
|
operationId: PostCreateAdminToken
|
|
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.
|
|
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'
|
|
tags:
|
|
- Authentication
|
|
- 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
|
|
- Token
|
|
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: true
|
|
schema:
|
|
$ref: '#/components/schemas/PrecisionWriteCompatibility'
|
|
description: The precision for unix timestamps in the line protocol batch.
|
|
precisionParam:
|
|
name: precision
|
|
in: query
|
|
required: true
|
|
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'
|
|
requestBodies:
|
|
lineProtocolRequestBody:
|
|
required: true
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
examples:
|
|
line:
|
|
summary: Example line protocol
|
|
value: measurement,tag=value field=1 1234567890
|
|
multiline:
|
|
summary: Example line protocol with UTF-8 characters
|
|
value: |
|
|
measurement,tag=value field=1 1234567890
|
|
measurement,tag=value field=2 1234567900
|
|
measurement,tag=value field=3 1234568000
|
|
queryRequestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryRequestObject'
|
|
schemas:
|
|
AdminTokenObject:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
token:
|
|
type: string
|
|
hash:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
expiry:
|
|
format: date-time
|
|
example:
|
|
id: 0
|
|
name: _admin
|
|
token: apiv3_00xx0Xx0xx00XX0x0
|
|
hash: 00xx0Xx0xx00XX0x0
|
|
created_at: '2025-04-18T14:02:45.331Z'
|
|
expiry: null
|
|
ContentEncoding:
|
|
type: string
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
description: |
|
|
Content coding.
|
|
Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.
|
|
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
|
|
- jsonl
|
|
description: |
|
|
The format of data in the response body.
|
|
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](/influxdb3/core/write-data/api-client-libraries/)
|
|
- [Data durability](/influxdb3/core/reference/internals/durability/)
|
|
PrecisionWriteCompatibility:
|
|
enum:
|
|
- ms
|
|
- s
|
|
- us
|
|
- ns
|
|
type: string
|
|
description: |
|
|
The precision for unix timestamps in the line protocol batch.
|
|
Use `ms` for milliseconds, `s` for seconds, `us` for microseconds, or `ns` for nanoseconds.
|
|
PrecisionWrite:
|
|
enum:
|
|
- auto
|
|
- millisecond
|
|
- second
|
|
- microsecond
|
|
- nanosecond
|
|
type: string
|
|
description: |
|
|
The precision for unix timestamps in the line protocol batch.
|
|
QueryRequestObject:
|
|
type: object
|
|
properties:
|
|
database:
|
|
description: |
|
|
The name of the database to query.
|
|
Required if the query (`query_str`) doesn't specify the database.
|
|
type: string
|
|
query_str:
|
|
description: The query to execute.
|
|
type: string
|
|
format:
|
|
description: The format of the query results.
|
|
type: string
|
|
enum:
|
|
- json
|
|
- csv
|
|
- parquet
|
|
- jsonl
|
|
- pretty
|
|
params:
|
|
description: |
|
|
Additional parameters for the query.
|
|
Use this field to pass query parameters.
|
|
type: object
|
|
additionalProperties: true
|
|
required:
|
|
- database
|
|
- query_str
|
|
example:
|
|
database: mydb
|
|
query_str: SELECT * FROM mytable
|
|
format: json
|
|
params: {}
|
|
CreateDatabaseRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
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
|
|
required:
|
|
- db
|
|
- table
|
|
- tags
|
|
DistinctCacheCreateRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
table:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description: Optional cache name.
|
|
columns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
max_cardinality:
|
|
type: integer
|
|
description: Optional maximum cardinality.
|
|
max_age:
|
|
type: integer
|
|
description: Optional maximum age in seconds.
|
|
required:
|
|
- db
|
|
- table
|
|
- columns
|
|
example:
|
|
db: mydb
|
|
table: mytable
|
|
columns:
|
|
- tag1
|
|
- tag2
|
|
max_cardinality: 1000
|
|
max_age: 3600
|
|
LastCacheCreateRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
table:
|
|
type: string
|
|
name:
|
|
type: string
|
|
description: Optional cache name.
|
|
key_columns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Optional list of key columns.
|
|
value_columns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Optional list of value columns.
|
|
count:
|
|
type: integer
|
|
description: Optional count.
|
|
ttl:
|
|
type: integer
|
|
description: Optional time-to-live in seconds.
|
|
required:
|
|
- db
|
|
- table
|
|
example:
|
|
db: mydb
|
|
table: mytable
|
|
key_columns:
|
|
- tag1
|
|
value_columns:
|
|
- field1
|
|
count: 100
|
|
ttl: 3600
|
|
ProcessingEngineTriggerRequest:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
plugin_filename:
|
|
type: string
|
|
description: |
|
|
The path and filename of the plugin to execute--for example,
|
|
`schedule.py` or `endpoints/report.py`.
|
|
The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3.
|
|
|
|
The plugin file must implement the trigger interface associated with the trigger's specification (`trigger_spec`).
|
|
trigger_name:
|
|
type: string
|
|
trigger_specification:
|
|
type: string
|
|
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):
|
|
- `every:30s` - Every 30 seconds
|
|
- `every:5m` - Every 5 minutes
|
|
- `every:1h` - Every hour
|
|
- `every:1d` - Every day
|
|
|
|
### 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: `path:ENDPOINT_NAME`
|
|
|
|
Creates an HTTP endpoint `/api/v3/engine/ENDPOINT_NAME` for manual invocation:
|
|
- `path:hello-world` - Creates endpoint `/api/v3/engine/hello-world`
|
|
- `path: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_]*|path:[a-zA-Z0-9_-]+)$
|
|
example: cron:0 0 6 * * 1-5
|
|
trigger_arguments:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Optional arguments passed to the plugin.
|
|
disabled:
|
|
type: boolean
|
|
default: false
|
|
description: Whether the trigger is disabled.
|
|
required:
|
|
- db
|
|
- plugin_filename
|
|
- trigger_name
|
|
- trigger_specification
|
|
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
|
|
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'
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
A Bearer token for authentication.
|
|
|
|
Provide the scheme and the API token in the `Authorization` header--for example:
|
|
|
|
```bash
|
|
curl http://localhost:8181/api/v3/query_influxql \
|
|
--header "Authorization: Bearer API_TOKEN"
|
|
```
|
|
x-tagGroups:
|
|
- name: Using the InfluxDB HTTP API
|
|
tags:
|
|
- Quick start
|
|
- Authentication
|
|
- Cache data
|
|
- Common parameters
|
|
- Response codes
|
|
- Compatibility endpoints
|
|
- Database
|
|
- Processing engine
|
|
- Server information
|
|
- Table
|
|
- Token
|
|
- Query data
|
|
- Write data
|