docs(influxdb3-cloud): add API reference spec scoped to CLI feature set#7552
Open
jstirnaman wants to merge 7 commits into
Open
docs(influxdb3-cloud): add API reference spec scoped to CLI feature set#7552jstirnaman wants to merge 7 commits into
jstirnaman wants to merge 7 commits into
Conversation
Derive an InfluxDB 3 Cloud OpenAPI spec from the Enterprise spec, limited to the endpoints that back the influxdb3 CLI reference documented for Cloud: - Write data (POST /api/v3/write_lp) - Query data, SQL and InfluxQL (GET|POST /api/v3/query_sql, /api/v3/query_influxql) - Databases (GET|POST|DELETE /api/v3/configure/database) - Tables (POST|DELETE /api/v3/configure/table) - Tokens: named admin (POST /api/v3/configure/token/named_admin), resource/permission (POST /api/v3/enterprise/configure/token), delete (DELETE /api/v3/configure/token) - Server information (GET /health, GET /ping) The spec is self-contained: only components referenced by these operations are included. Token operations are normalized to a single Token tag, and inherited Enterprise doc links are rewritten to the /influxdb/version/ placeholder so the pipeline maps them to /influxdb3/cloud/. Server-management and node-level endpoints are omitted because InfluxData runs the server. Register the product in the api-docs build pipeline (post-process-specs and generate-openapi-articles) so it renders under /influxdb3/cloud/api/. Cannot yet derive from source; the spec is maintained manually for now.
Contributor
📦 PR Preview — Preview Bot
Changed pages (2)Preview auto-deploys on push. Will be cleaned up when PR closes. |
Contributor
|
Contributor
Author
|
@ritwika314 I still need to clean up some links, remove Performance Preview mentions, and add some reference pages (line protocol). |
3 tasks
- Add /influxdb3/cloud/reference/syntax/line-protocol/ thin stub sourcing the shared v3-line-protocol.md page (resolves an inherited spec link). - Correct the API spec for InfluxDB 3 Cloud, which runs InfluxDB 3.10 with PachaTree: drop the Enterprise 'performance upgrade preview' framing, the --use-pacha-tree flag, and Parquet references. Present column families as a standard PachaTree feature. Rename remaining 'InfluxDB 3 Enterprise' prose to 'InfluxDB 3 Cloud'.
Contributor
Vale Style Check Results
✅ Check passed |
github-actions
Bot
added
the
product:v3-distributed
Contributor
🔗 Link Check Results — Link Check Bot✅ All links are valid
|
| Source File | URL | Issue |
|---|---|---|
content/influxdb3/cloud/reference/syntax/line-protocol/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
Full details: workflow run summary and artifact. Last updated: 2026-07-23 23:51:56 UTC
Reword the resource (fine-grained permissions) token note in the Cloud and Enterprise specs. Resource tokens are an Enterprise-tier capability, so state that they are available in InfluxDB 3 Enterprise and InfluxDB 3 Cloud and not in InfluxDB 3 Core, instead of naming only one edition.
Clarify that not every spec comes from influxdata/openapi. The InfluxDB 3 Core and Enterprise v3 specs come from the docs-tooling pipeline (getswagger.sh points at TO_BE_DECIDED), the InfluxDB 3 Cloud v3 spec is maintained by hand in this repo, and the v1 specs are only post-processed here. Add a 'Spec sources by product' table to the README and a pointer in the agent instructions so durable spec fixes land at the right source instead of being overwritten on the next fetch/port.
Contributor
Author
|
✅ |
jstirnaman
added
product:v3-cloud
github-actions
Bot
added
the
product:v3-distributed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Adds an InfluxDB 3 Cloud OpenAPI spec and wires it into the API docs build
pipeline so the reference renders under
/influxdb3/cloud/api/.New files under
api-docs/influxdb3/cloud/:influxdb3-cloud-openapi.yaml— the spec (self-contained)tags.yml,.config.yml,content/{info,servers,page}.yml— overlays/configPipeline registration:
post-process-specs.ts— addinfluxdb3/cloudtoPRODUCT_DIRSgenerate-openapi-articles.ts— add theinfluxdb3_cloudproduct configWhy
InfluxDB 3 Cloud needs an API reference. We can't derive it from source code
yet, so the spec is derived from the InfluxDB 3 Enterprise spec (Cloud is hosted
Enterprise) and limited to the same feature set as the
influxdb3CLI referencedocumented for Cloud in this branch. It is maintained manually for now.
Impact
Endpoints included (mapped to CLI commands):
writePOST /api/v3/write_lpquery(SQL/InfluxQL)GET/POST /api/v3/query_sql,/api/v3/query_influxqlcreate/delete/show databasePOST/DELETE/GET /api/v3/configure/databasecreate/delete tablePOST/DELETE /api/v3/configure/tablecreate token --adminPOST /api/v3/configure/token/named_admincreate token --permissionPOST /api/v3/enterprise/configure/tokendelete tokenDELETE /api/v3/configure/tokenGET /health,GET /pingDeliberately omitted: server-management and node-level endpoints (InfluxData
runs the server), plus backup/restore, users/roles, processing engine, caches,
and export — none are in the Cloud CLI feature set.
Derivation notes:
Tokentag;Authenticationis atrait tag; the Enterprise-only
Enterprisetag is dropped./influxdb/version/placeholder so the pipeline maps them to
/influxdb3/cloud/.Known follow-up: two inherited links point to Cloud pages that don't exist yet
(
/influxdb3/cloud/reference/syntax/line-protocol/and/influxdb3/cloud/performance-preview/). These are content gaps, not buildblockers.
Verification
npx @redocly/cli lint— passes ("API description is valid").sh api-docs/generate-api-docs.sh— generates the Cloud tag/article data andcontent pages; all products process successfully.
npx hugo— builds; the/influxdb3/cloud/api/section renders with tagsWrite data, Query data, Database, Table, Auth token, Server information, and
the Authentication + Quick start trait pages. No Enterprise branding or
spec-derived Enterprise links leak into the rendered Cloud pages.
PR preview URLs