openapi: 3.0.3
info:
  title: InfluxDB 3 Enterprise API Service
  description: |
    The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.

    Write and query data, and perform administrative tasks, such as managing databases and processing engine plugins.

    The InfluxDB HTTP API for InfluxDB 3 Core includes endpoints for the following:
      - InfluxDB v1: Compatibility layer for InfluxDB 1.x clients (supported)
      - `/api/v2`: Compatibility layer for InfluxDB 2.x clients (supported)
      - `/api/v3`: Native API for InfluxDB 3.x (current)

    <!-- 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/openapi/master/contracts/ref/cloud.yml).
    -->
  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 Enterprise API URL
    variables:
      baseurl:
        enum:
          - localhost:8181
        default: localhost:8181
        description: InfluxDB 3 Enterprise URL
tags:
  - name: Cache
    description: Endpoints for creating and deleting caches.
  - name: Create
    description: Endpoints for creating resources.
  - name: Database
    description: Endpoints for creating, deleting, and listing databases.
  - name: Delete
    description: Endpoints for deleting resources.
  - name: InfluxQL query
    description: Endpoints for executing InfluxQL queries.
  - name: Legacy v1-compatible
    description: Endpoints compatible with InfluxDB 1.x client libraries and third-party integrations.
  - name: Legacy v2-compatible
    description: Endpoints compatible with InfluxDB 2.x client libraries and third-party integrations.
  - name: List
    description: Endpoints for listing databases, tables, and other resources.
  - name: Processing engine
    description: Endpoints for creating, deleting, and testing processing engine plugins and triggers.
  - name: Query data
    description: Endpoints for querying data from InfluxDB.
  - name: Server
    description: Endpoints for checking the status and health of the service and retrieving service metrics.
  - name: SQL query
    description: Endpoints for executing SQL queries.
  - name: Table
    description: Endpoints for creating, deleting, and listing tables.
  - name: Write data
    description: Endpoints for writing data to InfluxDB.
paths:
  /write: {}
  /api/v2/write: {}
  /api/v3/write_lp: {}
  /api/v3/query_sql: {}
  /api/v3/query_influxql: {}
  /query: {}
  /health: {}
  /api/v1/health: {}
  /ping: {}
  /metrics: {}
  /api/v3/configure/database: {}
  /api/v3/configure/table: {}
  /api/v3/configure/distinct_cache: {}
  /api/v3/configure/last_cache: {}
  /api/v3/configure/processing_engine_trigger: {}
  /api/v3/configure/processing_engine_trigger/disable: {}
  /api/v3/configure/processing_engine_trigger/enable: {}
  /api/v3/configure/plugin_environment/install_packages: {}
  /api/v3/configure/plugin_environment/install_requirements: {}
  /api/v3/plugin_test/wal: {}
  /api/v3/plugin_test/schedule: {}
  /api/v3/engine/{plugin_path}:
    parameters:
      - name: plugin_path
        in: path
        required: true
        schema:
          type: string
components:
  parameters:
    ContentEncoding:
      name: Content-Encoding
      in: header
      schema:
        type: string
        enum:
          - gzip
          - identity
      required: false
      description: Optional encoding of the request body.
    Accept:
      name: Accept
      in: header
      schema:
        type: string
        enum:
          - application/json
          - application/vnd.apache.parquet
          - application/jsonl
      required: false
      description: Acceptable response content type.
    ContentType:
      name: Content-Type
      in: header
      schema:
        type: string
        enum:
          - text/plain
          - application/json
          - text/csv
      required: false
      description: Request content type.
  schemas:
    WriteParams:
      type: object
      properties:
        db:
          type: string
        accept_partial:
          type: boolean
          default: true
        precision:
          type: string
          enum:
            - ns
            - us
            - ms
            - s
          default: ns
        no_sync:
          type: boolean
          default: false
      required:
        - db
        - precision
      example:
        db: mydb
        accept_partial: true
        precision: ns
        no_sync: false
    QueryRequest:
      type: object
      properties:
        database:
          type: string
        query_str:
          type: string
        format:
          type: string
        params:
          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
            required:
              - name
              - type
      required:
        - db
        - table
        - fields
    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
        trigger_name:
          type: string
        trigger_specification:
          type: string
        trigger_arguments:
          type: object
          additionalProperties: true
        disabled:
          type: boolean
      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
    PingResponse:
      type: object
      properties:
        version:
          type: string
        revision:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized access.
      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: Bearer token for authentication. The API token must be provided in the Authorization header.
x-tagGroups:
  - name: Using the InfluxDB HTTP API
    tags:
      - Quick start
      - Authentication
      - Headers
      - Pagination
      - Response codes
      - System information endpoints
  - name: All endpoints
    tags:
      - Ping
      - Query
      - Write