openapi: 3.0.3 info: title: Migrate from InfluxDB v1 or v2 description: > Migrate your existing InfluxDB v1 or v2 workloads to InfluxDB 3. InfluxDB 3 provides compatibility endpoints that work with InfluxDB 1.x and 2.x client libraries and tools. Operations marked with v1 or v2 badges are compatible with the respective InfluxDB version. ### Migration guides - [Migrate from InfluxDB v1](/influxdb3/enterprise/guides/migrate/influxdb-1x/) - For users migrating from InfluxDB 1.x - [Migrate from InfluxDB v2](/influxdb3/enterprise/guides/migrate/influxdb-2x/) - For users migrating from InfluxDB 2.x or Cloud - [Use compatibility APIs to write data](/influxdb3/enterprise/write-data/http-api/compatibility-apis/) - v1 and v2 write endpoints - [Use the v1 HTTP query API](/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/) - InfluxQL queries via HTTP version: 3.7.0 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 Enterprise API URL variables: baseurl: enum: - localhost:8181 default: localhost:8181 description: InfluxDB 3 Enterprise URL security: - BearerAuthentication: [] tags: - name: Migrate from InfluxDB v1 or v2 x-traitTag: true description: > Migrate your existing InfluxDB v1 or v2 workloads to InfluxDB 3. InfluxDB 3 provides compatibility endpoints that work with InfluxDB 1.x and 2.x client libraries and tools. Operations marked with v1 or v2 badges are compatible with the respective InfluxDB version. ### Migration guides - [Migrate from InfluxDB v1](/influxdb3/enterprise/guides/migrate/influxdb-1x/) - For users migrating from InfluxDB 1.x - [Migrate from InfluxDB v2](/influxdb3/enterprise/guides/migrate/influxdb-2x/) - For users migrating from InfluxDB 2.x or Cloud - [Use compatibility APIs to write data](/influxdb3/enterprise/write-data/http-api/compatibility-apis/) - v1 and v2 write endpoints - [Use the v1 HTTP query API](/influxdb3/enterprise/query-data/execute-queries/influxdb-v1-api/) - InfluxQL queries via HTTP paths: {} 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' v1UsernameParam: name: u in: query required: false schema: type: string description: > Username for v1 compatibility authentication. When using Basic authentication or query string authentication, InfluxDB 3 ignores this parameter but allows any arbitrary string for compatibility with InfluxDB 1.x clients. v1PasswordParam: name: p in: query required: false schema: type: string description: > Password for v1 compatibility authentication. For query string authentication, pass a database token with write permissions as this parameter. InfluxDB 3 checks that the `p` value is an authorized token. requestBodies: lineProtocolRequestBody: required: true content: text/plain: schema: type: string description: > Line protocol data. Each line represents a point with a measurement name, optional tag set, field set, and optional timestamp. Format: `[,=...] =[,=...] []` examples: single-point: summary: Write a single point description: Write one point with tags and fields to a table. value: cpu,host=server01 usage=85.2,load=0.75 1638360000000000000 multiple-tables: summary: Write to multiple tables description: >- Write points to different tables (measurements) in a single request. value: > cpu,host=server01,region=us-west usage=85.2,load=0.75 1638360000000000000 memory,host=server01,region=us-west used=4096,free=12288 1638360000000000000 disk,host=server01,region=us-west,device=/dev/sda1 used=50.5,free=49.5 1638360000000000000 queryRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryRequestObject' schemas: AdminTokenObject: type: object properties: id: type: integer name: type: string token: type: string hash: type: string created_at: type: string format: date-time expiry: format: date-time example: id: 0 name: _admin token: apiv3_00xx0Xx0xx00XX0x0 hash: 00xx0Xx0xx00XX0x0 created_at: '2025-04-18T14:02:45.331Z' expiry: null ResourceTokenObject: type: object properties: token_name: type: string permissions: type: array items: type: object properties: resource_type: type: string enum: - system - db resource_identifier: type: array items: type: string actions: type: array items: type: string enum: - read - write expiry_secs: type: integer description: The expiration time in seconds. example: token_name: All system information permissions: - resource_type: system resource_identifier: - '*' actions: - read expiry_secs: 300000 ContentEncoding: type: string enum: - gzip - identity description: > Content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. #### Multi-member gzip support InfluxDB 3 supports multi-member gzip payloads (concatenated gzip files per [RFC 1952](https://www.rfc-editor.org/rfc/rfc1952)). This allows you to: - Concatenate multiple gzip files and send them in a single request - Maintain compatibility with InfluxDB v1 and v2 write endpoints - Simplify batch operations using standard compression tools default: identity LineProtocol: type: string enum: - text/plain - text/plain; charset=utf-8 description: > `text/plain` is the content type for line protocol. `UTF-8` is the default character set. default: text/plain; charset=utf-8 ContentLength: type: integer description: The length in decimal number of octets. Database: type: string AcceptPartial: type: boolean default: true description: Accept partial writes. Format: type: string enum: - json - csv - parquet - 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/enterprise/write-data/api-client-libraries/) - [Data durability](/influxdb3/enterprise/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 - nanosecond - microsecond - millisecond - second type: string description: > The precision for unix timestamps in the line protocol batch. Supported values: - `auto` (default): Automatically detects precision based on timestamp magnitude - `nanosecond`: Nanoseconds - `microsecond`: Microseconds - `millisecond`: Milliseconds - `second`: Seconds QueryRequestObject: type: object properties: db: description: | The name of the database to query. Required if the query (`q`) doesn't specify the database. type: string q: description: The query to execute. type: string format: description: The format of the query results. type: string enum: - json - csv - parquet - jsonl - pretty params: description: | Additional parameters for the query. Use this field to pass query parameters. type: object additionalProperties: true required: - db - q example: db: mydb q: SELECT * FROM mytable format: json params: {} CreateDatabaseRequest: type: object properties: db: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$ description: >- The database name. Database names cannot contain underscores (_). Names must start and end with alphanumeric characters and can contain hyphens (-) in the middle. retention_period: type: string description: >- The retention period for the database. Specifies how long data should be retained. Use duration format (for example, "1d", "1h", "30m", "7d"). example: 7d required: - db CreateTableRequest: type: object properties: db: type: string table: type: string tags: type: array items: type: string fields: type: array items: type: object properties: name: type: string type: type: string enum: - utf8 - int64 - uint64 - float64 - bool required: - name - type retention_period: type: string description: >- The retention period for the table. Specifies how long data in this table should be retained. Use duration format (for example, "1d", "1h", "30m", "7d"). example: 30d required: - db - table - tags DistinctCacheCreateRequest: type: object properties: db: type: string table: type: string node_spec: $ref: '#/components/schemas/ApiNodeSpec' name: type: string description: Optional cache name. columns: type: array items: type: string max_cardinality: type: integer description: Optional maximum cardinality. max_age: type: integer description: Optional maximum age in seconds. required: - db - table - columns example: db: mydb table: mytable columns: - tag1 - tag2 max_cardinality: 1000 max_age: 3600 LastCacheCreateRequest: type: object properties: db: type: string table: type: string node_spec: $ref: '#/components/schemas/ApiNodeSpec' name: type: string description: Optional cache name. key_columns: type: array items: type: string description: Optional list of key columns. value_columns: type: array items: type: string description: Optional list of value columns. count: type: integer description: Optional count. ttl: type: integer description: Optional time-to-live in seconds. required: - db - table example: db: mydb table: mytable key_columns: - tag1 value_columns: - field1 count: 100 ttl: 3600 ProcessingEngineTriggerRequest: type: object properties: db: type: string plugin_filename: type: string description: > The path and filename of the plugin to execute--for example, `schedule.py` or `endpoints/report.py`. The path can be absolute or relative to the `--plugins-dir` directory configured when starting InfluxDB 3. The plugin file must implement the trigger interface associated with the trigger's specification. node_spec: $ref: '#/components/schemas/ApiNodeSpec' trigger_name: type: string trigger_settings: description: | Configuration for trigger error handling and execution behavior. allOf: - $ref: '#/components/schemas/TriggerSettings' trigger_specification: description: > Specifies when and how the processing engine trigger should be invoked. ## Supported trigger specifications: ### Cron-based scheduling Format: `cron:CRON_EXPRESSION` Uses extended (6-field) cron format (second minute hour day_of_month month day_of_week): ``` ┌───────────── second (0-59) │ ┌───────────── minute (0-59) │ │ ┌───────────── hour (0-23) │ │ │ ┌───────────── day of month (1-31) │ │ │ │ ┌───────────── month (1-12) │ │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ │ * * * * * * ``` Examples: - `cron:0 0 6 * * 1-5` - Every weekday at 6:00 AM - `cron:0 30 14 * * 5` - Every Friday at 2:30 PM - `cron:0 0 0 1 * *` - First day of every month at midnight ### Interval-based scheduling Format: `every:DURATION` Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years): - `every:30s` - Every 30 seconds - `every:5m` - Every 5 minutes - `every:1h` - Every hour - `every:1d` - Every day - `every:1w` - Every week - `every:1M` - Every month - `every:1y` - Every year **Maximum interval**: 1 year ### Table-based triggers - `all_tables` - Triggers on write events to any table in the database - `table:TABLE_NAME` - Triggers on write events to a specific table ### On-demand triggers Format: `request:REQUEST_PATH` Creates an HTTP endpoint `/api/v3/engine/REQUEST_PATH` for manual invocation: - `request:hello-world` - Creates endpoint `/api/v3/engine/hello-world` - `request:data-export` - Creates endpoint `/api/v3/engine/data-export` pattern: >- ^(cron:[0-9 *,/-]+|every:[0-9]+[smhd]|all_tables|table:[a-zA-Z_][a-zA-Z0-9_]*|request:[a-zA-Z0-9_-]+)$ example: cron:0 0 6 * * 1-5 trigger_arguments: type: object additionalProperties: true description: Optional arguments passed to the plugin. disabled: type: boolean default: false description: Whether the trigger is disabled. required: - db - plugin_filename - trigger_name - trigger_settings - trigger_specification TriggerSettings: type: object description: > Configuration settings for processing engine trigger error handling and execution behavior. properties: run_async: type: boolean default: false description: > Whether to run the trigger asynchronously. When `true`, the trigger executes in the background without blocking. When `false`, the trigger executes synchronously. error_behavior: type: string enum: - Log - Retry - Disable description: | Specifies how to handle errors that occur during trigger execution: - `Log`: Log the error and continue (default) - `Retry`: Retry the trigger execution - `Disable`: Disable the trigger after an error default: Log required: - run_async - error_behavior ApiNodeSpec: type: object description: > Optional specification for targeting specific nodes in a multi-node InfluxDB 3 Enterprise cluster. Use this to control which node(s) should handle the cache or trigger. properties: node_id: type: string description: > The ID of a specific node in the cluster. If specified, the cache or trigger will only be created on this node. node_group: type: string description: > The name of a node group in the cluster. If specified, the cache or trigger will be created on all nodes in this group. WALPluginTestRequest: type: object description: | Request body for testing a write-ahead logging (WAL) plugin. properties: filename: type: string description: | The path and filename of the plugin to test. database: type: string description: | The database name to use for the test. input_lp: type: string description: | Line protocol data to use as input for the test. cache_name: type: string description: | Optional name of the cache to use in the test. input_arguments: type: object additionalProperties: type: string description: | Optional key-value pairs of arguments to pass to the plugin. required: - filename - database - input_lp SchedulePluginTestRequest: type: object description: | Request body for testing a scheduling plugin. properties: filename: type: string description: | The path and filename of the plugin to test. database: type: string description: | The database name to use for the test. schedule: type: string description: | Optional schedule specification in cron or interval format. cache_name: type: string description: | Optional name of the cache to use in the test. input_arguments: type: object additionalProperties: type: string description: | Optional key-value pairs of arguments to pass to the plugin. required: - filename - database PluginFileRequest: type: object description: | Request body for updating a plugin file. properties: plugin_name: type: string description: | The name of the plugin file to update. content: type: string description: | The content of the plugin file. required: - plugin_name - content PluginDirectoryRequest: type: object description: | Request body for updating plugin directory with multiple files. properties: plugin_name: type: string description: | The name of the plugin directory to update. files: type: array items: $ref: '#/components/schemas/PluginFileEntry' description: | List of plugin files to include in the directory. required: - plugin_name - files PluginFileEntry: type: object description: | Represents a single file in a plugin directory. properties: filename: type: string description: | The name of the file within the plugin directory. content: type: string description: | The content of the file. required: - filename - content ShowDatabasesResponse: type: object properties: databases: type: array items: type: string QueryResponse: type: object properties: results: type: array items: type: object example: results: - series: - name: mytable columns: - time - value values: - - '2024-02-02T12:00:00Z' - 42 ErrorMessage: type: object properties: error: type: string data: type: object nullable: true LineProtocolError: properties: code: description: Code is the machine-readable error code. enum: - internal error - not found - conflict - invalid - empty value - unavailable readOnly: true type: string err: description: >- Stack of errors that occurred during processing of the request. Useful for debugging. readOnly: true type: string line: description: First line in the request body that contains malformed data. format: int32 readOnly: true type: integer message: description: Human-readable message. readOnly: true type: string op: description: >- Describes the logical code operation when the error occurred. Useful for debugging. readOnly: true type: string required: - code EpochCompatibility: description: | A unix timestamp precision. - `h` for hours - `m` for minutes - `s` for seconds - `ms` for milliseconds - `u` or `µ` for microseconds - `ns` for nanoseconds enum: - ns - u - µ - ms - s - m - h type: string UpdateDatabaseRequest: type: object properties: retention_period: type: string description: > The retention period for the database. Specifies how long data should be retained. Use duration format (for example, "1d", "1h", "30m", "7d"). example: 7d description: Request schema for updating database configuration. UpdateTableRequest: type: object properties: db: type: string description: The name of the database containing the table. table: type: string description: The name of the table to update. retention_period: type: string description: > The retention period for the table. Specifies how long data in this table should be retained. Use duration format (for example, "1d", "1h", "30m", "7d"). example: 30d required: - db - table description: Request schema for updating table configuration. LicenseResponse: type: object properties: license_type: type: string description: The type of license (for example, "enterprise", "trial"). example: enterprise expires_at: type: string format: date-time description: The expiration date of the license in ISO 8601 format. example: '2025-12-31T23:59:59Z' features: type: array items: type: string description: List of features enabled by the license. example: - clustering - processing_engine - advanced_auth status: type: string enum: - active - expired - invalid description: The current status of the license. example: active description: Response schema for license information. responses: Unauthorized: description: Unauthorized access. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' BadRequest: description: | Request failed. Possible reasons: - Invalid database name - Malformed request body - Invalid timestamp precision content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' Forbidden: description: Access denied. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: ClusterUUID: description: | The catalog UUID of the InfluxDB instance. This header is included in all HTTP API responses and enables you to: - Identify which cluster instance handled the request - Monitor deployments across multiple InfluxDB instances - Debug and troubleshoot distributed systems schema: type: string format: uuid example: 01234567-89ab-cdef-0123-456789abcdef securitySchemes: BasicAuthentication: type: http scheme: basic description: > Use the `Authorization` header with the `Basic` scheme to authenticate v1 API requests. Works with v1 compatibility [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints in InfluxDB 3. When authenticating requests, InfluxDB 3 checks that the `password` part of the decoded credential is an authorized token and ignores the `username` part of the decoded credential. ### Syntax ```http Authorization: Basic ``` ### Example ```bash curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s" \ --user "":"AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: - **`DATABASE_NAME`**: your InfluxDB 3 Enterprise database - **`AUTH_TOKEN`**: an admin token or database token authorized for the database #### Related guides - [Authenticate v1 API requests](/influxdb3/enterprise/guides/api-compatibility/v1/) - [Manage tokens](/influxdb3/enterprise/admin/tokens/) QuerystringAuthentication: type: apiKey in: query name: u=&p= description: > Use InfluxDB 1.x API parameters to provide credentials through the query string for v1 API requests. Querystring authentication works with v1-compatible [`/write`](#operation/PostV1Write) and [`/query`](#operation/GetV1Query) endpoints. When authenticating requests, InfluxDB 3 checks that the `p` (_password_) query parameter is an authorized token and ignores the `u` (_username_) query parameter. ### Syntax ```http https://localhost:8181/query/?[u=any]&p=AUTH_TOKEN https://localhost:8181/write/?[u=any]&p=AUTH_TOKEN ``` ### Examples ```bash curl "http://localhost:8181/write?db=DATABASE_NAME&precision=s&p=AUTH_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: - **`DATABASE_NAME`**: your InfluxDB 3 Enterprise database - **`AUTH_TOKEN`**: an admin token or database token authorized for the database ```bash ####################################### # Use an InfluxDB 1.x compatible username and password # to query the InfluxDB v1 HTTP API ####################################### # Use authentication query parameters: # ?p=AUTH_TOKEN ####################################### curl --get "http://localhost:8181/query" \ --data-urlencode "p=AUTH_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` Replace the following: - **`DATABASE_NAME`**: the database to query - **`AUTH_TOKEN`**: a database token with sufficient permissions to the database #### Related guides - [Authenticate v1 API requests](/influxdb3/enterprise/guides/api-compatibility/v1/) - [Manage tokens](/influxdb3/enterprise/admin/tokens/) BearerAuthentication: type: http scheme: bearer bearerFormat: JWT description: > Use the OAuth Bearer authentication scheme to provide an authorization token to InfluxDB 3. Bearer authentication works with all endpoints. In your API requests, send an `Authorization` header. For the header value, provide the word `Bearer` followed by a space and a database token. ### Syntax ```http Authorization: Bearer AUTH_TOKEN ``` ### Example ```bash curl http://localhost:8181/api/v3/query_influxql \ --header "Authorization: Bearer AUTH_TOKEN" ``` TokenAuthentication: description: > Use InfluxDB v2 Token authentication to provide an authorization token to InfluxDB 3. The v2 Token scheme works with v1 and v2 compatibility endpoints in InfluxDB 3. In your API requests, send an `Authorization` header. For the header value, provide the word `Token` followed by a space and a database token. The word `Token` is case-sensitive. ### Syntax ```http Authorization: Token AUTH_TOKEN ``` ### Example ```sh ######################################################## # Use the Token authentication scheme with /api/v2/write # to write data. ######################################################## curl --request post "http://localhost:8181/api/v2/write?bucket=DATABASE_NAME&precision=s" \ --header "Authorization: Token AUTH_TOKEN" \ --data-binary 'home,room=kitchen temp=72 1463683075' ``` ### Related guides - [Manage tokens](/influxdb3/enterprise/admin/tokens/) in: header name: Authorization type: apiKey x-tagGroup: Migrate from InfluxDB v1 or v2