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 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 `. 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:"` 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: ``` /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 ``. 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 ``. 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