feat(api): InfluxDB3 Core API reference, API fixes, and e2e tests

- Adds InfluxDB 3 Core API reference
- Updates scripts
- Removes non-valid info.summary field from specs, replaces with description in metadata
- Simplifies frontmatter generation for HTML template
- Reorg of file structure to mirror the content structure.
- Moves OSS v2 into v2/v2/ref.yml to follow the same pattern as others
- Replaces isDefault API config field with specific aliases.
- Misc. fixes.
- Remove generated HTML files.

.gitignore

@@ -8,7 +8,7 @@ node_modules
 *.log
 /resources
 .hugo_build.lock
-/content/influxdb*/*/api/**/*.html
+/content/influxdb*/**/api/**/*.html
 /api-docs/redoc-static.html*
 .vscode/*
 .idea

api-docs/generate-api-docs.sh

@@ -41,7 +41,6 @@ function generateHtml {
   local productName="$3"
   local api="$4"
   local configPath="$5"
-  local isDefault=$6
 
   # Use the product name to define the menu for the Hugo template
   local menu="$(echo $productVersion | sed 's/\./_/g;s/-/_/g;s/\//_/g;')"
@@ -55,12 +54,25 @@ function generateHtml {
   # Use the title and summary defined in the product API's info.yml file.
   local title=$(yq '.title' $productVersion/$apiName/content/info.yml)
   local menuTitle=$(yq '.x-influxdata-short-title' $productVersion/$apiName/content/info.yml)
-  local description=$(yq '.summary' $productVersion/$apiName/content/info.yml)
+  # Get the first paragraph of the description for the meta description.
+
+  # Get the description with whitespace and newlines preserved.
+  local description=$(yq e -r '.description // ""' $productVersion/$apiName/content/info.yml | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/"/\\"/g')
+  # Get the aliases array from the configuration file.
+  local aliases=$(yq e ".apis | .$api | .x-influxdata-docs-aliases" "$configPath")
+  # If aliases is null, set it to an empty YAML array. 
+  if [[ "$aliases" == "null" ]]; then
+    aliases='[]'
+  fi
+  local weight=102
+  if [[ $apiName == "v1-compatibility" ]]; then
+    weight=304
+  fi
   # Define the file name for the Redoc HTML output.
   local specbundle=redoc-static_index.html
   # Define the temporary file for the Hugo template and Redoc HTML.
   local tmpfile="${productVersion}-${api}_index.tmp"
-
+  
   echo "Bundling $specPath"
 
   # Use npx to install and run the specified version of redoc-cli.
@@ -77,68 +89,24 @@ function generateHtml {
   --options.hideHostname \
   --options.noAutoAuth \
   --output=$specbundle \
-  --templateOptions.description=$description \
+  --templateOptions.description= $(echo "$description" | sed 's/\n//g') \
   --templateOptions.product="$productVersion" \
   --templateOptions.productName="$productName"
 
-  if [[ $apiName == "v1-compatibility" ]]; then
+  local frontmatter=$(yq eval -n \
-    frontmatter="---
+      ".title = \"$title\" |
-title: $title
+       .description = \"$description\" |
-description: $description
+       .layout = \"api\" |
-layout: api
+       .weight = $weight |
-menu:
+       .menu.[\"$menu\"].parent = \"InfluxDB HTTP API\" |
-  $menu:
+       .menu.[\"$menu\"].name = \"$menuTitle\" |
-    parent: InfluxDB HTTP API
+       .menu.[\"$menu\"].identifier = \"api-reference-$apiName\" |
-    name: $menuTitle
+      .aliases = \"$aliases\"")
-    identifier: api-reference-$apiName
+
-weight: 304
+  frontmatter="---
-aliases:
+$frontmatter
-  - /influxdb/$versionDir/api/v1/
 ---
 "
-  elif [[ $apiVersion == "0" ]]; then
-  echo $productName $apiName
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-weight: 102
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
----
-"
-  elif [[ $isDefault == true ]]; then
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 102
-aliases:
-  - /influxdb/$versionDir/api/
----
-"
-  else
-    frontmatter="---
-title: $title
-description: $description
-layout: api
-menu:
-  $menu:
-    parent: InfluxDB HTTP API
-    name: $menuTitle
-    identifier: api-reference-$apiName
-weight: 102
----
-"
-  fi
 
   # Create the Hugo template file with the frontmatter and Redoc HTML
   echo "$frontmatter" >> $tmpfile
@@ -199,13 +167,7 @@ function build {
       if [ -d "$specPath" ] || [ ! -f "$specPath" ]; then
         echo "OpenAPI spec $specPath doesn't exist."
       fi
-      # Get default status from the configuration.
+
-      local isDefault=false
-      local defaultStatus
-      defaultStatus=$(yq e ".apis | .$api | .x-influxdata-default" "$configPath")
-      if [[ $defaultStatus == "true" ]]; then
-        isDefault=true
-      fi
 
       # If the spec file differs from master, regenerate the HTML.
       local update=0
@@ -219,9 +181,9 @@ function build {
 
       if [[ $update -eq 0 ]]; then
         echo "Regenerating $version $api"
-        generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath" "$isDefault"
+        generateHtml "$specPath" "$version" "$versionName" "$api" "$configPath"
       fi
-      echo "========Done with $version $api========"
+      echo -e "========Finished $version $api========\n\n"
     done <<< "$apis"
   done
 }

api-docs/getswagger.sh

@@ -223,14 +223,14 @@ function updateEnterpriseV3 {
 }
 
 function updateOSSV2 {
-  outFile="influxdb/v2/ref.yml"
+  outFile="influxdb/v2/v2/ref.yml"
   if [[ -z "$baseUrlOSS" ]];
   then
     echo "Using existing $outFile"
   else
     curl $UPDATE_OPTIONS ${baseUrlOSS}/contracts/ref/oss.yml -o $outFile
   fi
-  postProcess $outFile 'influxdb/v2/.config.yml' '@2'
+  postProcess $outFile 'influxdb/v2/.config.yml' 'v2@2'
 }
 
 function updateV1Compat {

api-docs/influxdb/cloud/.config.yml

@@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB v2 Cloud
 apis:
   v2@2:
     root: v2/ref.yml
-    x-influxdata-default: true
+    x-influxdata-docs-aliases:
+      - /influxdb/cloud/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb/cloud/api/v1/

api-docs/influxdb/cloud/v2/ref.yml

@@ -12212,7 +12212,7 @@ paths:
             type: string
         - description: |
             A unix timestamp precision.
-            Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) the specified precision
+            Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) with the specified precision
             instead of [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
           in: query
           name: epoch

api-docs/influxdb/v2/.config.yml

@@ -6,8 +6,11 @@ extends:
 x-influxdata-product-name: InfluxDB v2 OSS
 
 apis:
-  '@2':
+  v2@2:
-    root: ref.yml
+    root: v2/ref.yml
-    x-influxdata-default: true
+    x-influxdata-docs-aliases:
+      - /influxdb/v2/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb/v2/api/v1/

api-docs/influxdb/v2/content/info.yml

@@ -1,16 +0,0 @@
-title: InfluxDB OSS API Service
-x-influxdata-short-title: v2 API
-summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
-description: |
-    The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
-
-    This documentation is generated from the
-    [InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.7.0/contracts/ref/oss.yml).
-version: 2.x
-license:
-  name: MIT
-  url: 'https://opensource.org/licenses/MIT'
-contact:
-  name: InfluxData
-  url: https://www.influxdata.com
-  email: support@influxdata.com

api-docs/influxdb/v2/v1-compatibility/swaggerV1Compat.yml

@@ -467,19 +467,3 @@ components:
 
 
         For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
-x-tagGroups:
-  - name: Using the InfluxDB HTTP API
-    tags:
-      - Quick start
-      - Authentication
-      - Supported operations
-      - Headers
-      - Pagination
-      - Response codes
-      - Data I/O endpoints
-      - Security and access endpoints
-      - System information endpoints
-  - name: All endpoints
-    tags:
-      - Query
-      - Write

api-docs/influxdb/v2/v2/content/info.yml

@@ -0,0 +1,17 @@
+title: InfluxDB OSS API Service
+x-influxdata-short-title: v2 API
+description: |
+  The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
+
+  The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
+
+  This documentation is generated from the
+  [InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.7.0/contracts/ref/oss.yml).
+version: 2.x
+license:
+  name: MIT
+  url: 'https://opensource.org/licenses/MIT'
+contact:
+  name: InfluxData
+  url: https://www.influxdata.com
+  email: support@influxdata.com

api-docs/influxdb/v2/v2/ref.yml

@@ -3,6 +3,8 @@ info:
   title: InfluxDB OSS API Service
   version: 2.x
   description: |
+    The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
+
     The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
 
     This documentation is generated from the
@@ -10,7 +12,10 @@ info:
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-  summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
+  contact:
+    name: InfluxData
+    url: https://www.influxdata.com
+    email: support@influxdata.com
 servers:
   - url: /
 security:
@@ -13103,7 +13108,7 @@ paths:
             type: string
         - description: |
             A unix timestamp precision.
-            Formats timestamps as [unix (epoch) timestamps](/influxdb/v2.7/reference/glossary/#unix-timestamp) the specified precision
+            Formats timestamps as [unix (epoch) timestamps](/influxdb/v2.7/reference/glossary/#unix-timestamp) with the specified precision
             instead of [RFC3339 timestamps](/influxdb/v2.7/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
           in: query
           name: epoch
@@ -15515,9 +15520,9 @@ components:
       properties:
         results:
           description: |
-              A resultset object that contains the `statement_id` and the `series` array.
+            A resultset object that contains the `statement_id` and the `series` array.
 
-              Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
+            Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
           items:
             properties:
               error:
@@ -15566,12 +15571,12 @@ components:
                 type: integer
             type: object
           oneOf:
-          - required:
+            - required:
-            - statement_id
+                - statement_id
-            - error
+                - error
-          - required:
+            - required:
-            - statement_id
+                - statement_id
-            - series
+                - series
           type: array
       type: object
     IntegerLiteral:

api-docs/influxdb3/cloud-dedicated/.config.yml

@@ -10,6 +10,9 @@ apis:
     root: management/openapi.yml
   v2@2:
     root: v2/ref.yml
-    x-influxdata-default: true
+    x-influxdata-docs-aliases:
+      - /influxdb3/cloud-dedicated/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb3/cloud-dedicated/api/v1/

api-docs/influxdb3/cloud-dedicated/v1-compatibility/content/info.yml

@@ -2,6 +2,7 @@ title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Dedicated
 x-influxdata-short-title: v1 Compatibility API
 description: |
   The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints.
+
   The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
 
   This documentation is generated from the

api-docs/influxdb3/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml

@@ -4,6 +4,7 @@ info:
   version: ''
   description: |
     The v1-compatibility HTTP API provides compatibility for writing and querying data in an InfluxDB 3 Cloud Dedicated database using InfluxDB v1 endpoints.
+
     The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
 
     This documentation is generated from the

api-docs/influxdb3/cloud-dedicated/v2/ref.yml

@@ -2,9 +2,9 @@ openapi: 3.0.0
 info:
   title: InfluxDB v2 HTTP API for InfluxDB 3 Cloud Dedicated
   description: |
-    The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Cloud Dedicated database.
+    The InfluxDB v2 HTTP API provides a v2-compatible programmatic interface for writing and managing data stored in an InfluxDB 3 Cloud Dedicated database.
 
-    The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
+    Use the InfluxDB v2 HTTP API `/api/v2` endpoints to manage retention policy mappings and write data to an InfluxDB 3 instance.
 
     This documentation is generated from the
     [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml).
@@ -504,7 +504,7 @@ paths:
             type: string
         - description: |
             A unix timestamp precision.
-            Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-dedicated/reference/glossary/#unix-timestamp) the specified precision
+            Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-dedicated/reference/glossary/#unix-timestamp) with the specified precision
             instead of [RFC3339 timestamps](/influxdb3/cloud-dedicated/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
           in: query
           name: epoch

api-docs/influxdb3/cloud-serverless/.config.yml

@@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB 3 Serverless
 apis:
   v2@2:
     root: v2/ref.yml
-    x-influxdata-default: true
+    x-influxdata-docs-aliases:
+      - /influxdb3/cloud-serverless/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb3/cloud-serverless/api/v1/

api-docs/influxdb3/cloud-serverless/v1-compatibility/content/info.yml

@@ -1,7 +1,8 @@
 title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Serverless
 x-influxdata-short-title: v1 Compatibility API
-summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
 description: |
+  The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
+
   The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
 
   This documentation is generated from the

api-docs/influxdb3/cloud-serverless/v1-compatibility/swaggerV1Compat.yml

@@ -3,6 +3,8 @@ info:
   title: InfluxDB v1 HTTP API for InfluxDB 3 Cloud Serverless
   version: ''
   description: |
+    The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
+
     The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
 
     This documentation is generated from the
@@ -14,7 +16,6 @@ info:
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-  summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Cloud Serverless bucket.
   contact:
     name: InfluxData
     url: https://www.influxdata.com

api-docs/influxdb3/cloud-serverless/v2/content/info.yml

@@ -1,8 +1,8 @@
 title: InfluxDB 3 Cloud Serverless API Service
 x-influxdata-short-title: v2 API
-summary: |
-  The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
 description: |
+  The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
+
   The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
 
   This documentation is generated from the

api-docs/influxdb3/cloud-serverless/v2/ref.yml

@@ -2,6 +2,8 @@ openapi: 3.0.0
 info:
   title: InfluxDB 3 Cloud Serverless API Service
   description: |
+    The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
+
     The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
 
     This documentation is generated from the
@@ -9,8 +11,6 @@ info:
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-  summary: |
-    The InfluxDB v2 HTTP API for InfluxDB 3 Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB 3 Cloud Serverless bucket.
   version: ''
   contact:
     name: InfluxData
@@ -7827,7 +7827,7 @@ paths:
             type: string
         - description: |
             A unix timestamp precision.
-            Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-serverless/reference/glossary/#unix-timestamp) the specified precision
+            Formats timestamps as [unix (epoch) timestamps](/influxdb3/cloud-serverless/reference/glossary/#unix-timestamp) with the specified precision
             instead of [RFC3339 timestamps](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
           in: query
           name: epoch

api-docs/influxdb3/clustered/.config.yml

@@ -8,6 +8,9 @@ x-influxdata-product-name: InfluxDB 3 Clustered
 apis:
   v2@2:
     root: v2/ref.yml
-    x-influxdata-default: true
+    x-influxdata-docs-aliases:
+      - /influxdb3/clustered/api/
   v1-compatibility@2:
     root: v1-compatibility/swaggerV1Compat.yml
+    x-influxdata-docs-aliases:
+      - /influxdb3/clustered/api/v1/

api-docs/influxdb3/clustered/v1-compatibility/content/info.yml

@@ -1,7 +1,8 @@
 title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered
 x-influxdata-short-title: v1 Compatibility API
-summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
 description: |
+  The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
+
   The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
 
   This documentation is generated from the

api-docs/influxdb3/clustered/v1-compatibility/swaggerV1Compat.yml

@@ -3,6 +3,8 @@ info:
   title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered
   version: ''
   description: |
+    The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
+
     The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
 
     This documentation is generated from the
@@ -14,7 +16,6 @@ info:
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-  summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
   contact:
     name: InfluxData
     url: https://www.influxdata.com

api-docs/influxdb3/clustered/v2/content/info.yml

@@ -1,7 +1,8 @@
 title: InfluxDB 3 Clustered API Service
 x-influxdata-short-title: v2 API
-summary: The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
 description: |
+  The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
+
   The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
 
   This documentation is generated from the

api-docs/influxdb3/clustered/v2/ref.yml

@@ -3,6 +3,8 @@ info:
   title: InfluxDB 3 Clustered API Service
   version: ''
   description: |
+    The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
+
     The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB 3 instance.
 
     This documentation is generated from the
@@ -10,7 +12,6 @@ info:
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-  summary: The InfluxDB v2 HTTP API for InfluxDB 3 Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB 3 Clustered database.
   contact:
     name: InfluxData
     url: https://www.influxdata.com
@@ -521,7 +522,7 @@ paths:
             type: string
         - description: |
             A unix timestamp precision.
-            Formats timestamps as [unix (epoch) timestamps](/influxdb3/clustered/reference/glossary/#unix-timestamp) the specified precision
+            Formats timestamps as [unix (epoch) timestamps](/influxdb3/clustered/reference/glossary/#unix-timestamp) with the specified precision
             instead of [RFC3339 timestamps](/influxdb3/clustered/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
           in: query
           name: epoch

api-docs/influxdb3/core/v3/content/info.yml

@@ -4,8 +4,9 @@ x-influxdata-version-matrix:
   v1: Compatibility layer for InfluxDB 1.x clients (supported)
   v2: Compatibility layer for InfluxDB 2.x clients (supported) 
   v3: Native API for InfluxDB 3.x (current)
-summary: The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
 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:

api-docs/influxdb3/core/v3/ref.yml

@@ -1,35 +1,58 @@
 openapi: 3.0.3
 info:
-  title: InfluxDB 3 Core HTTP API
+  title: InfluxDB 3 Core API Service
-  description: HTTP API service for managing, writing to, and querying from InfluxDB 3 Core.
+  description: |
-  version: 1.0.2
+    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/).
+    -->
+  version: ''
   license:
     name: MIT
-    url: 'https://opensource.org/licenses/MIT'
+    url: https://opensource.org/licenses/MIT
   contact:
     name: InfluxData
     url: https://www.influxdata.com
     email: support@influxdata.com
 servers:
-  - url: http://localhost:8080
+  - url: https://{baseurl}
-    description: Local development server
+    description: InfluxDB 3 Core API URL
+    variables:
+      baseurl:
+        enum:
+          - localhost:8181
+        default: localhost:8181
+        description: InfluxDB 3 Core URL
+security: 
+  - BearerAuth: []
 tags:
-  - name: Databases
-    description: Create, read, update, and delete database and cache resources
-  - name: Tables
-    description: Manage table schemas and data
-  - name: Data operations
-    description: Write, query, and process data
   - name: Backward compatibility
     description: Endpoints compatible with v1.x and v2.x clients
+  - name: Data operations (write and query) 
+    description: Write, query, and process data
+  - name: Databases
+    description: Create, read, update, and delete database and cache resources
+  - name: Processing engine
+    description: Manage processing engine triggers and plugins
   - name: Server information
     description: Retrieve server metrics, status, and version information
+  - name: Tables
+    description: Manage table schemas and data
 paths:
   /write:
     post:
       operationId: PostV1Write
       summary: Write line protocol (v1-compatible)
-      description: >
+      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.
@@ -38,19 +61,34 @@ paths:
         Use query parameters to specify options for writing data.
       parameters:
         - $ref: '#/components/parameters/dbWriteParam'
-        - name: precision
+        - $ref: '#/components/parameters/compatibilityPrecisionParam'
-          in: query
+        - name: Content-Type
-          required: true
+          in: header
+          description: |
+            The content type of the request payload.
           schema:
-            $ref: '#/components/schemas/PrecisionWrite'
+            $ref: '#/components/schemas/LineProtocol'
-          description: Precision of timestamps.
+          required: false
-        - $ref: '#/components/parameters/ContentTypeLineProtocol'
+        - 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":
+        '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.
@@ -93,8 +131,6 @@ paths:
           description: Access denied.
         "413":
           description: Request entity too large.
-      security:
-        - BearerAuth: []
       tags:
         - Backward compatibility
         - Data operations
@@ -102,7 +138,7 @@ paths:
     post:
       operationId: PostV2Write
       summary: Write line protocol (v2-compatible)
-      description: >
+      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.
@@ -111,6 +147,13 @@ paths:
         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.
@@ -125,7 +168,6 @@ paths:
               - gzip
               - identity
             type: string
-        - $ref: "#/components/parameters/ContentTypeLineProtocol" 
         - description: |
             The size of the entity-body, in bytes, sent to InfluxDB.
           in: header
@@ -159,13 +201,7 @@ paths:
           required: false
           schema:
             $ref: '#/components/schemas/AcceptPartial'
-        - name: precision
+        - $ref: '#/components/parameters/compatibilityPrecisionParam'
-          in: query
-          required: true
-          schema:
-            $ref: '#/components/schemas/PrecisionWrite' 
-          description: The precision for unix timestamps in the line protocol batch.
-        - $ref: '#/components/parameters/ContentType'
       requestBody:
         $ref: '#/components/requestBodies/lineProtocolRequestBody'
       responses:
@@ -179,8 +215,6 @@ paths:
           description: Access denied.
         "413":
           description: Request entity too large.
-      security:
-        - BearerAuth: []
       tags:
         - Backward compatibility
         - Data operations
@@ -188,7 +222,7 @@ paths:
     post:
       operationId: PostWriteLP
       summary: Write line protocol
-      description: >
+      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.
@@ -206,7 +240,27 @@ paths:
           in: query
           schema:
             $ref: '#/components/schemas/NoSync'
-        - $ref: '#/components/parameters/ContentTypeLineProtocol'
+        - 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:
@@ -222,8 +276,6 @@ paths:
           description: Request entity too large.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations
   /api/v3/query_sql:
@@ -279,8 +331,6 @@ paths:
           description: Method not allowed.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations 
     post:
@@ -320,8 +370,6 @@ paths:
           description: Method not allowed.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations
   /api/v3/query_influxql:
@@ -370,8 +418,6 @@ paths:
           description: Method not allowed.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations
     post:
@@ -411,8 +457,6 @@ paths:
           description: Method not allowed.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations
   /query:
@@ -463,14 +507,6 @@ paths:
           schema:
             type: string
             format: InfluxQL
-        - in: query
-          name: epoch
-          description: |
-            Map timestamps to UNIX epoch time, with the given precision.
-            The default is `ns`.
-          schema:
-            type: string
-            enum: [h, m, s, ms, u, ns]
         - in: query
           name: pretty
           description: |
@@ -484,6 +520,13 @@ paths:
           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: |
@@ -521,8 +564,6 @@ paths:
           description: Method not allowed.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations
         - Backward compatibility
@@ -555,10 +596,26 @@ paths:
                   default: 10000
                 epoch:
                   description: |
-                    Map timestamps to UNIX epoch time, with the given precision.
+                    A unix timestamp precision.
-                    The default is `ns`.
+
+                    - `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
-                  enum: [h, m, s, ms, u, ns]
                 pretty:
                   description: |
                     If true, the JSON response is formatted in a human-readable format.
@@ -619,8 +676,6 @@ paths:
           description: Method not allowed.
         "422":
           description: Unprocessable entity.
-      security:
-        - BearerAuth: []
       tags:
         - Data operations
         - Backward compatibility
@@ -696,8 +751,6 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Database not found.
-      security:
-        - BearerAuth: []
       tags:
         - Databases
     post:
@@ -719,8 +772,6 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "409":
           description: Database already exists.
-      security:
-        - BearerAuth: []
       tags:
         - Databases
     delete:
@@ -738,8 +789,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Database not found.
-      security:
+
-        - BearerAuth: []
       tags:
         - Databases
   /api/v3/configure/table:
@@ -763,8 +813,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Database not found.
-      security:
+
-        - BearerAuth: []
       tags:
         - Tables
     delete:
@@ -787,8 +836,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Table not found.
-      security:
+
-        - BearerAuth: []
       tags:
         - Tables
   /api/v3/configure/distinct_cache:
@@ -796,6 +844,8 @@ paths:
       operationId: PostConfigureDistinctCache
       summary: Create distinct cache
       description: Creates a distinct cache for a table.
+      tags: 
+        -  Tables
       requestBody:
         required: true
         content:
@@ -834,8 +884,7 @@ paths:
           description: Cache not found.
         "409":
           description: Cache already exists.
-      security:
+
-        - BearerAuth: []
       tags:
         - Tables 
     delete:
@@ -863,8 +912,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Cache not found.
-      security:
+
-        - BearerAuth: []
       tags:
         - Tables
   /api/v3/configure/processing_engine_trigger:
@@ -887,10 +935,9 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Trigger not found.
-      security:
+
-        - BearerAuth: []
       tags:
-        - Data operations 
+        - Processing engine 
     delete:
       operationId: DeleteConfigureProcessingEngineTrigger
       summary: Delete processing engine trigger
@@ -917,10 +964,9 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Trigger not found.
-      security:
+
-        - BearerAuth: []
       tags:
-        - Data operations 
+        - Processing engine 
   /api/v3/configure/processing_engine_trigger/disable:
     post:
       operationId: PostDisableProcessingEngineTrigger
@@ -943,10 +989,9 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Trigger not found.
-      security:
+
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
   /api/v3/configure/processing_engine_trigger/enable:
     post:
       operationId: PostEnableProcessingEngineTrigger
@@ -969,10 +1014,9 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Trigger not found.
-      security:
+
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
   /api/v3/configure/plugin_environment/install_packages:
     post:
       operationId: PostInstallPluginPackages
@@ -994,10 +1038,8 @@ paths:
           description: Bad request.
         "401":
           $ref: '#/components/responses/Unauthorized'
-      security:
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
   /api/v3/configure/plugin_environment/install_requirements:
     post:
       operationId: PostInstallPluginRequirements
@@ -1019,10 +1061,8 @@ paths:
           description: Bad request.
         "401":
           $ref: '#/components/responses/Unauthorized'
-      security:
-        - BearerAuth: []
       tags:
-        - Data operations 
+        - Processing engine 
   /api/v3/plugin_test/wal:
     post:
       operationId: PostTestWALPlugin
@@ -1037,10 +1077,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Plugin not enabled.
-      security:
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
   /api/v3/plugin_test/schedule:
     post:
       operationId: PostTestSchedulingPlugin
@@ -1055,10 +1093,8 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         "404":
           description: Plugin not enabled.
-      security:
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
   /api/v3/engine/{plugin_path}:
     parameters:
       - name: plugin_path
@@ -1105,10 +1141,8 @@ paths:
           description: Plugin not found.
         "500":
           description: Processing failure.
-      security:
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
     post:
       operationId: PostProcessingEnginePluginRequest
       summary: On-request processing engine plugin request
@@ -1133,10 +1167,9 @@ paths:
           description: Plugin not found.
         "500":
           description: Processing failure.
-      security:
-        - BearerAuth: []
       tags:
-        - Data operations
+        - Processing engine 
+
 components:
   parameters:
     AcceptQueryHeader:
@@ -1168,25 +1201,17 @@ components:
       description: |
         The size of the entity-body, in bytes, sent to InfluxDB.
       schema:
-        $ref: '#/components/schemas/ContentLength' 
+        $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
-    ContentTypeLineProtocol:
-      name: Content-Type
-      in: header
-      description: |
-        The format of the data in the request body.
-
-        To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`.
-      schema:
-          $ref: '#/components/schemas/LineProtocol'
-      required: false
     db:
       name: db
       in: query
@@ -1202,6 +1227,7 @@ components:
       schema:
         type: string
       description: |
+        The name of the database.
         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.
@@ -1256,6 +1282,7 @@ components:
       required: true
       schema:
         $ref: '#/components/schemas/Format'
+
   requestBodies:
     lineProtocolRequestBody:
       required: true
@@ -1266,7 +1293,7 @@ components:
           examples:
             line:
               summary: Example line protocol
-              value: "measurement,tag=value field=1 1234567890"
+              value: measurement,tag=value field=1 1234567890
             multiline:
               summary: Example line protocol with UTF-8 characters
               value: |
@@ -1282,14 +1309,18 @@ components:
   schemas:
     ContentEncoding:
       type: string
-      enum: [gzip, identity]
+      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] 
+      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
@@ -1361,9 +1392,9 @@ components:
         - database
         - query_str
       example:
-        database: "mydb"
+        database: mydb
-        query_str: "SELECT * FROM mytable"
+        query_str: SELECT * FROM mytable
-        format: "json"
+        format: json
         params: {}
     CreateDatabaseRequest:
       type: object
@@ -1398,7 +1429,6 @@ components:
       required:
         - db
         - table
-        - fields
         - tags
     DistinctCacheCreateRequest:
       type: object
@@ -1425,9 +1455,11 @@ components:
         - table
         - columns
       example:
-        db: "mydb"
+        db: mydb
-        table: "mytable"
+        table: mytable
-        columns: ["tag1", "tag2"]
+        columns:
+          - tag1
+          - tag2
         max_cardinality: 1000
         max_age: 3600
     LastCacheCreateRequest:
@@ -1460,10 +1492,12 @@ components:
         - db
         - table
       example:
-        db: "mydb"
+        db: mydb
-        table: "mytable"
+        table: mytable
-        key_columns: ["tag1"]
+        key_columns:
-        value_columns: ["field1"]
+          - tag1
+        value_columns:
+          - field1
         count: 100
         ttl: 3600
     ProcessingEngineTriggerRequest:
@@ -1504,9 +1538,13 @@ components:
       example:
         results:
           - series:
-              - name: "mytable"
+              - name: mytable
-                columns: ["time", "value"]
+                columns:
-                values: [["2024-02-02T12:00:00Z", 42]]
+                  - time
+                  - value
+                values:
+                  - - '2024-02-02T12:00:00Z'
+                    - 42
     ErrorMessage:
       type: object
       properties:
@@ -1547,6 +1585,24 @@ components:
           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:
   # // Source https://github.com/influxdata/influxdb/blob/main/influxdb3_server/src/http.rs
     Unauthorized:
@@ -1555,7 +1611,7 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorMessage'
-    Bad request:
+    BadRequest:
       description: |
         Request failed. Possible reasons:
 

api-docs/influxdb3/enterprise/v3/content/info.yml

@@ -4,8 +4,9 @@ x-influxdata-version-matrix:
   v1: Compatibility layer for InfluxDB 1.x clients (supported)
   v2: Compatibility layer for InfluxDB 2.x clients (supported) 
   v3: Native API for InfluxDB 3.x (current)
-summary: The InfluxDB HTTP API for InfluxDB 3 Core provides a programmatic interface for writing data stored in an InfluxDB 3 Core database.
 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:

api-docs/template.hbs

@@ -12,7 +12,7 @@
 
   <meta charset="utf8" />
   <title>{{title}}</title>
-  <meta name="description" content="{{templateOptions.description}}.">
+  <meta name="description" content="{{templateOptions.description}}">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <link rel="shortcut icon" href="/img/favicon.png" type="image/png" sizes="32x32">
 

cypress/e2e/content/api-reference.cy.js

@@ -32,8 +32,8 @@ describe('API reference content', () => {
     '/influxdb3/clustered/api/v1/',
     '/influxdb3/clustered/api/v1-compatibility/',
     '/influxdb3/clustered/api/v2/',
-    '/influxdb3/core/api/',
 
+    '/influxdb3/core/api/',
     '/influxdb3/enterprise/api/',
   ];