fix(api-docs): restore full tag descriptions for API compatibility and Supported operations

Replace truncated "Overview of..." one-liners in tags.yml with proper descriptions: - API compatibility (Cloud Dedicated, Cloud Serverless, Clustered): restore multi-paragraph descriptions from origin/master specs covering write endpoints, query protocols, and v1/v2 compatibility. Move external doc links to x-related. - Supported operations (Cloud v2, OSS v2, Cloud Serverless): replace with reference-style descriptions and HTTP method convention table.
2026-03-15 22:15:43 -05:00 · 2026-03-15 22:15:43 -05:00 · 95a5a29625
parent 8f41704069
commit 95a5a29625
5 changed files with 133 additions and 18 deletions
--- a/api-docs/influxdb/cloud/tags.yml
+++ b/api-docs/influxdb/cloud/tags.yml
@ -187,9 +187,16 @@ tags:

  Supported operations:
    x-traitTag: true
-    description: >
-      Overview of the common CRUD operations supported by the InfluxDB Cloud
-      API.
+    description: |
+      The InfluxDB Cloud API supports create, read, update, and delete operations
+      on resources. Most endpoints follow standard HTTP method conventions:
+
+      | Operation | HTTP Method | Description |
+      |:----------|:------------|:------------|
+      | **Write** | `POST` | Send data or create a resource. |
+      | **Read** | `GET` | Retrieve a resource or list resources. |
+      | **Update** | `PUT`, `PATCH` | Replace or modify an existing resource. |
+      | **Delete** | `DELETE` | Remove a resource. |

  System information endpoints:
    description: >
--- a/api-docs/influxdb/v2/tags.yml
+++ b/api-docs/influxdb/v2/tags.yml
@ -225,9 +225,16 @@ tags:

  Supported operations:
    x-traitTag: true
-    description: >
-      Overview of the common CRUD operations supported by the InfluxDB OSS v2
-      API.
+    description: |
+      The InfluxDB OSS v2 API supports create, read, update, and delete operations
+      on resources. Most endpoints follow standard HTTP method conventions:
+
+      | Operation | HTTP Method | Description |
+      |:----------|:------------|:------------|
+      | **Write** | `POST` | Send data or create a resource. |
+      | **Read** | `GET` | Retrieve a resource or list resources. |
+      | **Update** | `PUT`, `PATCH` | Replace or modify an existing resource. |
+      | **Delete** | `DELETE` | Remove a resource. |

  System information endpoints:
    description: >
--- a/api-docs/influxdb3/cloud-dedicated/tags.yml
+++ b/api-docs/influxdb3/cloud-dedicated/tags.yml
@ -1,9 +1,40 @@
 tags:
  API compatibility:
    x-traitTag: true
-    description: >
-      Overview of the InfluxDB v1 and v2 compatible write and query endpoints
-      available in InfluxDB 3 Cloud Dedicated.
+    description: |
+      ### Write data
+
+      InfluxDB 3 Cloud Dedicated provides the following HTTP API endpoints for writing data:
+
+      - **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite) for new write workloads or for bringing existing InfluxDB v2 write workloads to InfluxDB 3.
+      - [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to InfluxDB 3.
+
+      Both endpoints accept the same line protocol format and process data in the same way.
+
+      ### Query data
+
+      InfluxDB 3 Cloud Dedicated provides the following protocols for executing a query:
+
+      - **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query.
+      - HTTP API [`/query` request](#operation/GetLegacyQuery) that contains an InfluxQL query.
+        Use this protocol when bringing existing InfluxDB v1 query workloads to InfluxDB 3.
+
+      ### InfluxDB v2 compatibility
+
+      The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Bearer`](#section/Authentication/BearerAuthentication) and [`Token`](#section/Authentication/TokenAuthentication) authentication schemes and existing InfluxDB 2.x tools and code.
+
+      ### InfluxDB v1 compatibility
+
+      The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
+    x-related:
+      - title: Get started querying InfluxDB
+        href: /influxdb3/cloud-dedicated/get-started/query/
+      - title: Write data
+        href: /influxdb3/cloud-dedicated/write-data/
+      - title: Use the v2 HTTP API with Cloud Dedicated
+        href: /influxdb3/cloud-dedicated/guides/api-compatibility/v2/
+      - title: Use the v1 HTTP API with Cloud Dedicated
+        href: /influxdb3/cloud-dedicated/guides/api-compatibility/v1/

  Authentication:
    x-traitTag: true
--- a/api-docs/influxdb3/cloud-serverless/tags.yml
+++ b/api-docs/influxdb3/cloud-serverless/tags.yml
@ -1,9 +1,41 @@
 tags:
  API compatibility:
    x-traitTag: true
-    description: >
-      Overview of the InfluxDB v1 and v2 compatible write and query endpoints
-      available in InfluxDB 3 Cloud Serverless.
+    description: |
+      ### Write data
+
+      InfluxDB 3 Cloud Serverless provides the following HTTP API endpoints for writing data:
+
+      - **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite)
+        for new write workloads or for bringing existing InfluxDB v2 write workloads to InfluxDB 3.
+      - [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to InfluxDB 3.
+
+      Both endpoints accept the same line protocol format and process data in the same way.
+
+      ### Query data
+
+      InfluxDB 3 Cloud Serverless provides the following protocols for executing a query:
+
+      - **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query.
+      - HTTP API [`/query` request](#operation/GetLegacyQuery) that contains an InfluxQL query.
+        Use this protocol when bringing existing InfluxDB v1 query workloads to InfluxDB 3.
+
+      ### InfluxDB v2 compatibility
+
+      The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Token` authentication scheme](#section/Authentication/TokenAuthentication) and existing InfluxDB 2.x tools and code.
+
+      ### InfluxDB v1 compatibility
+
+      The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
+    x-related:
+      - title: Get started querying InfluxDB
+        href: /influxdb3/cloud-serverless/get-started/query/
+      - title: Write data
+        href: /influxdb3/cloud-serverless/write-data/
+      - title: Use the v2 HTTP API with Cloud Serverless
+        href: /influxdb3/cloud-serverless/guides/api-compatibility/v2/
+      - title: Use the v1 HTTP API with Cloud Serverless
+        href: /influxdb3/cloud-serverless/guides/api-compatibility/v1/

  Authentication:
    x-traitTag: true
@ -190,9 +222,16 @@ tags:

  Supported operations:
    x-traitTag: true
-    description: >
-      Overview of the common CRUD operations supported by the InfluxDB 3 Cloud
-      Serverless API.
+    description: |
+      The InfluxDB 3 Cloud Serverless API supports create, read, update, and delete
+      operations on resources. Most endpoints follow standard HTTP method conventions:
+
+      | Operation | HTTP Method | Description |
+      |:----------|:------------|:------------|
+      | **Write** | `POST` | Send data or create a resource. |
+      | **Read** | `GET` | Retrieve a resource or list resources. |
+      | **Update** | `PUT`, `PATCH` | Replace or modify an existing resource. |
+      | **Delete** | `DELETE` | Remove a resource. |

  System information endpoints:
    description: >
--- a/api-docs/influxdb3/clustered/tags.yml
+++ b/api-docs/influxdb3/clustered/tags.yml
@ -1,9 +1,40 @@
 tags:
  API compatibility:
    x-traitTag: true
-    description: >
-      Overview of the InfluxDB v1 and v2 compatible write and query endpoints
-      available in InfluxDB 3 Clustered.
+    description: |
+      ### Write data
+
+      InfluxDB 3 Clustered provides the following HTTP API endpoints for writing data:
+
+      - **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite) for new write workloads or for bringing existing InfluxDB v2 write workloads to InfluxDB 3.
+      - [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to InfluxDB 3.
+
+      Both endpoints accept the same line protocol format and process data in the same way.
+
+      ### Query data
+
+      InfluxDB 3 Clustered provides the following protocols for executing a query:
+
+      - **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query.
+      - HTTP API [`/query` request](#operation/GetLegacyQuery) that contains an InfluxQL query.
+        Use this protocol when bringing existing InfluxDB v1 query workloads to InfluxDB 3.
+
+      ### InfluxDB v2 compatibility
+
+      The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Bearer`](#section/Authentication/BearerAuthentication) and [`Token`](#section/Authentication/TokenAuthentication) authentication schemes and existing InfluxDB 2.x tools and code.
+
+      ### InfluxDB v1 compatibility
+
+      The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
+    x-related:
+      - title: Get started querying InfluxDB
+        href: /influxdb3/clustered/get-started/query/
+      - title: Write data
+        href: /influxdb3/clustered/write-data/
+      - title: Use the v2 HTTP API with Clustered
+        href: /influxdb3/clustered/guides/api-compatibility/v2/
+      - title: Use the v1 HTTP API with Clustered
+        href: /influxdb3/clustered/guides/api-compatibility/v1/

  Authentication:
    x-traitTag: true