Processing engine

Download InfluxDB 3 Core API Spec

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.

POST /api/v3/configure/plugin_environment/install_packages

Install plugin packages

Installs the specified Python packages into the processing engine plugin environment.

This endpoint is synchronous and blocks until the packages are installed.

Parameters

Header parameters
Content-Type string
The format of the data in the request body.
Allowed values: application/json

Request body required

Content-Type: application/json
packages required string[]
A list of Python package names to install. Can include version specifiers (for example, “scipy==1.9.0”).
Example: ["influxdb3-python","scipy","pandas==1.5.0","requests"]
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/configure/plugin_environment/install_packages" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "packages": [
    "influxdb3-python",
    "scipy",
    "pandas==1.5.0",
    "requests"
  ]
}'

Responses

200 Success. The packages are installed.
400 Bad request.
401 Unauthorized access.
data object
error string
POST /api/v3/configure/plugin_environment/install_requirements

Install plugin requirements

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.

Parameters

Header parameters
Content-Type string
The format of the data in the request body.
Allowed values: application/json

Request body required

Content-Type: application/json
requirements_location required string
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"
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/configure/plugin_environment/install_requirements" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "requirements_location": "requirements.txt"
}'

Responses

200 Success. The requirements have been installed.
400 Bad request.
401 Unauthorized access.
data object
error string
POST /api/v3/configure/processing_engine_trigger

Create processing engine trigger

Creates a processing engine trigger with the specified plugin file and trigger specification.

Request body required

Content-Type: application/json
db required string
disabled required boolean
Whether the trigger is disabled.
plugin_filename required string

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_arguments object
Optional arguments passed to the plugin.
trigger_name required string
trigger_settings required string
Configuration for trigger error handling and execution behavior.
trigger_specification required string

Specifies when and how the processing engine trigger should be invoked.

Supported trigger specifications:

Cron-based scheduling

Format: cron:CRON_EXPRESSION

Uses extended (6-field) cron format (second minute hour day_of_month month day_of_week):

┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31)
│ │ │ │ ┌───────────── month (1-12)
│ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │ │
* * * * * *

Examples:

  • cron:0 0 6 * * 1-5 - Every weekday at 6:00 AM
  • cron:0 30 14 * * 5 - Every Friday at 2:30 PM
  • cron:0 0 0 1 * * - First day of every month at midnight

Interval-based scheduling

Format: every:DURATION

Supported durations: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years):

  • every:30s - Every 30 seconds
  • every:5m - Every 5 minutes
  • every:1h - Every hour
  • every:1d - Every day
  • every:1w - Every week
  • every:1M - Every month
  • every:1y - Every year

Maximum interval: 1 year

Table-based triggers

  • all_tables - Triggers on write events to any table in the database
  • table:TABLE_NAME - Triggers on write events to a specific table

On-demand triggers

Format: request:REQUEST_PATH

Creates an HTTP endpoint /api/v3/engine/REQUEST_PATH for manual invocation:

  • request:hello-world - Creates endpoint /api/v3/engine/hello-world
  • request:data-export - Creates endpoint /api/v3/engine/data-export
Example: "cron:0 0 6 * * 1-5"
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/configure/processing_engine_trigger" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "db": "DB",
  "disabled": false,
  "plugin_filename": "PLUGIN_FILENAME",
  "trigger_arguments": {},
  "trigger_name": "TRIGGER_NAME",
  "trigger_settings": "TRIGGER_SETTINGS",
  "trigger_specification": "cron:0 0 6 * * 1-5"
}'

Responses

200 Success. Processing engine trigger created.
400 Bad request.
401 Unauthorized access.
data object
error string
404 Trigger not found.
DELETE /api/v3/configure/processing_engine_trigger

Delete processing engine trigger

Deletes a processing engine trigger.

Parameters

Query parameters
db required string
The name of the database.
trigger_name required string
force boolean
Force deletion of the trigger even if it has active executions. By default, deletion fails if the trigger is currently executing.
Example request Ask AI about this
curl --request DELETE \
  "https://localhost:8181/api/v3/configure/processing_engine_trigger?db=DB&trigger_name=TRIGGER_NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The processing engine trigger has been deleted.
400 Bad request.
401 Unauthorized access.
data object
error string
404 Trigger not found.
POST /api/v3/configure/processing_engine_trigger/disable

Disable processing engine trigger

Disables a processing engine trigger.

Parameters

Query parameters
db required string
The database name.
trigger_name required string
The name of the trigger.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/configure/processing_engine_trigger/disable?db=DB&trigger_name=TRIGGER_NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The processing engine trigger has been disabled.
400 Bad request.
401 Unauthorized access.
data object
error string
404 Trigger not found.
POST /api/v3/configure/processing_engine_trigger/enable

Enable processing engine trigger

Enables a processing engine trigger.

Parameters

Query parameters
db required string
The database name.
trigger_name required string
The name of the trigger.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/configure/processing_engine_trigger/enable?db=DB&trigger_name=TRIGGER_NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The processing engine trigger is enabled.
400 Bad request.
401 Unauthorized access.
data object
error string
404 Trigger not found.
GET /api/v3/engine/{request_path}

On Request processing engine plugin request

Executes the On Request processing engine plugin specified in the trigger’s plugin_filename. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.

An On Request plugin implements the following signature:

def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)

The response depends on the plugin implementation.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/engine/{request_path}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The plugin request has been executed.
400 Malformed request.
401 Unauthorized access.
data object
error string
404 Plugin not found.
500 Processing failure.
POST /api/v3/engine/{request_path}

On Request processing engine plugin request

Executes the On Request processing engine plugin specified in the trigger’s plugin_filename. The request can include request headers, query string parameters, and a request body, which InfluxDB passes to the plugin.

An On Request plugin implements the following signature:

def process_request(influxdb3_local, query_parameters, request_headers, request_body, args=None)

The response depends on the plugin implementation.

Parameters

Header parameters
Content-Type string
The format of the data in the request body.
Allowed values: application/json

Request body

Content-Type: application/json
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/engine/{request_path}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"

Responses

200 Success. The plugin request has been executed.
400 Malformed request.
401 Unauthorized access.
data object
error string
404 Plugin not found.
500 Processing failure.
POST /api/v3/plugin_test/schedule

Test scheduling plugin

Executes a test of a scheduling plugin.

Request body required

Content-Type: application/json
cache_name string
Optional name of the cache to use in the test.
database required string
The database name to use for the test.
filename required string
The path and filename of the plugin to test.
input_arguments object
Optional key-value pairs of arguments to pass to the plugin.
schedule string
Optional schedule specification in cron or interval format.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/plugin_test/schedule" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "cache_name": "CACHE_NAME",
  "database": "DATABASE",
  "filename": "FILENAME",
  "input_arguments": {},
  "schedule": "SCHEDULE"
}'

Responses

200 Success. The plugin test has been executed.
400 Bad request.
401 Unauthorized access.
data object
error string
404 Plugin not enabled.
POST /api/v3/plugin_test/wal

Test WAL plugin

Executes a test of a write-ahead logging (WAL) plugin.

Request body required

Content-Type: application/json
cache_name string
Optional name of the cache to use in the test.
database required string
The database name to use for the test.
filename required string
The path and filename of the plugin to test.
input_arguments object
Optional key-value pairs of arguments to pass to the plugin.
input_lp required string
Line protocol data to use as input for the test.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/plugin_test/wal" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "cache_name": "CACHE_NAME",
  "database": "DATABASE",
  "filename": "FILENAME",
  "input_arguments": {},
  "input_lp": "INPUT_LP"
}'

Responses

200 Success. The plugin test has been executed.
400 Bad request.
401 Unauthorized access.
data object
error string
404 Plugin not enabled.
PUT /api/v3/plugins/directory

Update a multi-file plugin directory

Replaces all files in a multi-file plugin directory. The plugin_name must match a registered trigger name. Each entry in the files array specifies a relative_path and content—the server writes them into the trigger’s plugin directory.

Use this endpoint to update multi-file plugins (directories with __init__.py and supporting modules). For single-file plugins, use PUT /api/v3/plugins/files instead.

Request body required

Content-Type: application/json
files required object[]
List of plugin files to include in the directory.
plugin_name required string
The name of the plugin directory to update.
Example request Ask AI about this
curl --request PUT \
  "https://localhost:8181/api/v3/plugins/directory" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "files": [],
  "plugin_name": "PLUGIN_NAME"
}'

Responses

200 Success. The plugin directory has been updated.
401 Unauthorized access.
data object
error string
403 Forbidden. Admin token required.
500 Plugin not found. The plugin_name does not match any registered trigger.
POST /api/v3/plugins/files

Create a plugin file

Creates a single plugin file in the plugin directory. Writes the content to a file named after plugin_name. Does not require an existing trigger—use this to upload plugin files before creating triggers that reference them.

Request body required

Content-Type: application/json
content required string
The content of the plugin file.
plugin_name required string
The name of the plugin file to update.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/plugins/files" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "content": "CONTENT",
  "plugin_name": "PLUGIN_NAME"
}'

Responses

200 Success. The plugin file has been created.
401 Unauthorized access.
data object
error string
403 Forbidden. Admin token required.
PUT /api/v3/plugins/files

Update a plugin file

Updates a single plugin file for an existing trigger. The plugin_name must match a registered trigger name—the server resolves the trigger’s plugin_filename and overwrites that file with the provided content.

To upload a new plugin file before creating a trigger, use POST /api/v3/plugins/files instead. To update a multi-file plugin directory, use PUT /api/v3/plugins/directory.

Request body required

Content-Type: application/json
content required string
The content of the plugin file.
plugin_name required string
The name of the plugin file to update.
Example request Ask AI about this
curl --request PUT \
  "https://localhost:8181/api/v3/plugins/files" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "content": "CONTENT",
  "plugin_name": "PLUGIN_NAME"
}'

Responses

200 Success. The plugin file has been updated.
401 Unauthorized access.
data object
error string
403 Forbidden. Admin token required.
500 Plugin not found. The plugin_name does not match any registered trigger.

Was this page helpful?

Thank you for your feedback!