diff --git a/api-docs/influxdb3/cloud-serverless/.config.yml b/api-docs/influxdb3/cloud-serverless/.config.yml index 597516cd9..964a1e977 100644 --- a/api-docs/influxdb3/cloud-serverless/.config.yml +++ b/api-docs/influxdb3/cloud-serverless/.config.yml @@ -3,7 +3,7 @@ plugins: extends: - recommended - docs/all -x-influxdata-product-name: InfluxDB 3 Serverless +x-influxdata-product-name: InfluxDB Cloud Serverless apis: data@2: diff --git a/api-docs/influxdb3/cloud-serverless/content/info.yml b/api-docs/influxdb3/cloud-serverless/content/info.yml index 4a23ed31d..c2deeeb17 100644 --- a/api-docs/influxdb3/cloud-serverless/content/info.yml +++ b/api-docs/influxdb3/cloud-serverless/content/info.yml @@ -1,13 +1,34 @@ -title: InfluxDB 3 Cloud Serverless API Service -x-influxdata-short-title: v2 API -x-influxdata-short-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. +title: InfluxDB Cloud Serverless HTTP API +x-influxdata-short-title: HTTP API +x-influxdata-short-description: The InfluxDB HTTP API provides a programmatic interface for writing, querying, and managing data stored in InfluxDB Cloud Serverless (powered by the InfluxDB 3 storage engine). 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 HTTP API provides a programmatic interface for writing, querying, and managing data stored in InfluxDB Cloud Serverless (powered by the InfluxDB 3 storage engine). - 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. + Access the InfluxDB HTTP API using the `/api/v2/` or InfluxDB v1 endpoints. - This documentation is generated from the - [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml). + ### InfluxDB v2-compatible endpoints + + InfluxDB v2-compatible endpoints work with InfluxDB Cloud Serverless and with InfluxDB 2.x client libraries and third-party integrations. + + The following v2-compatible endpoints are supported for Cloud Serverless: + + - `/api/v2/write` — write data + - `/api/v2/authorizations` — manage API tokens + - `/api/v2/buckets` — manage buckets + - `/api/v2/orgs` — manage organizations + + ### InfluxDB v1-compatible endpoints + + InfluxDB v1-compatible endpoints work with InfluxDB Cloud Serverless and with InfluxDB 1.x client libraries and third-party integrations. + + - `/write` — write data + - `/query` — query data with InfluxQL + + ### Other endpoints + + Other endpoints in this reference are for the InfluxDB Cloud (TSM) API. + These endpoints may be accessible but are not supported or recommended for use with InfluxDB Cloud Serverless, which is powered by the InfluxDB 3 storage engine. + For Cloud Serverless-specific functionality, see the [InfluxDB Cloud Serverless documentation](https://docs.influxdata.com/influxdb3/cloud-serverless/). license: name: MIT url: 'https://opensource.org/licenses/MIT' diff --git a/api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml b/api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml index fe81f3576..36291f88c 100644 --- a/api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml +++ b/api-docs/influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml @@ -36,8 +36,8 @@ tags: - description: |- Use one of the following schemes to authenticate to the InfluxDB 3 Cloud Serverless API: - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) + - Token authentication + - Basic authentication name: Authentication x-traitTag: true @@ -160,6 +160,11 @@ paths: description: | Retrieves all the top level routes for the InfluxDB API. + The response includes routes for all InfluxDB v2 API resources, + including resources that are not supported for InfluxDB Cloud + Serverless (powered by the InfluxDB 3 storage engine). + For supported endpoints, see API compatibility. + #### Limitations - Only returns top level routes--for example, the response contains @@ -181,7 +186,6 @@ paths: summary: List all top level routes tags: - Routes - - System information endpoints /api/v2/authorizations: get: description: | @@ -351,7 +355,7 @@ paths: Use the endpoint to delete an API token. If you want to disable an API token instead of delete it, - [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). + update the authorization's status to `inactive`. operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -1066,7 +1070,7 @@ paths: #### Related guides - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - Use the `/api/v2/labels` InfluxDB API endpoint to retrieve and manage labels. - [Manage buckets](/influxdb3/cloud-serverless/admin/buckets/) operationId: GetBucketsIDLabels parameters: @@ -1126,11 +1130,11 @@ paths: - Before adding a label to a bucket, you must create the label if you haven't already. To create a label with the InfluxDB API, send a `POST` - request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). + request to the `/api/v2/labels` endpoint. #### Related guides - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - Use the `/api/v2/labels` InfluxDB API endpoint to retrieve and manage labels. - [Manage labels in the InfluxDB UI](/influxdb3/cloud-serverless/visualize-data/labels/) operationId: PostBucketsIDLabels parameters: @@ -1463,7 +1467,7 @@ paths: Bucket owners have permission to delete buckets and remove user and member permissions from the bucket. - InfluxDB 3 Cloud Serverless uses [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign resource permissions; doesn't use `owner` and `member` roles. + InfluxDB 3 Cloud Serverless uses `/api/v2/authorizations` to assign resource permissions; doesn't use `owner` and `member` roles. #### Limitations @@ -1480,7 +1484,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - Authorizations (API tokens) operationId: GetBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -1538,7 +1542,7 @@ paths: Bucket owners have permission to delete buckets and remove user and member permissions from the bucket. - InfluxDB 3 Cloud Serverless uses [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign resource permissions; doesn't use `owner` and `member` roles. + InfluxDB 3 Cloud Serverless uses `/api/v2/authorizations` to assign resource permissions; doesn't use `owner` and `member` roles. #### Limitations @@ -1553,7 +1557,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - Authorizations (API tokens) #### Related guides @@ -1636,7 +1640,7 @@ paths: Use this endpoint to remove a user's `owner` role for a bucket. - InfluxDB 3 Cloud Serverless uses [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign resource permissions; doesn't use `owner` and `member` roles. + InfluxDB 3 Cloud Serverless uses `/api/v2/authorizations` to assign resource permissions; doesn't use `owner` and `member` roles. #### Limitations @@ -1652,7 +1656,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - Authorizations (API tokens) #### Related guides @@ -2078,586 +2082,587 @@ paths: ] }' summary: Bucket Schema - /api/v2/checks: {} - /api/v2/checks/{checkID}: {} - /api/v2/checks/{checkID}/labels: {} - /api/v2/checks/{checkID}/labels/{labelID}: {} - /api/v2/checks/{checkID}/query: {} - /api/v2/dashboards: {} - /api/v2/dashboards/{dashboardID}: {} - /api/v2/dashboards/{dashboardID}/cells: {} - /api/v2/dashboards/{dashboardID}/cells/{cellID}: {} - /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: {} - /api/v2/dashboards/{dashboardID}/labels: {} - /api/v2/dashboards/{dashboardID}/labels/{labelID}: {} - /api/v2/dashboards/{dashboardID}/members: {} - /api/v2/dashboards/{dashboardID}/members/{userID}: {} - /api/v2/dashboards/{dashboardID}/owners: {} - /api/v2/dashboards/{dashboardID}/owners/{userID}: {} - /api/v2/dbrps: - get: - description: | - Lists database retention policy (DBRP) mappings. + # InfluxDB Cloud (TSM) endpoints — not supported for Cloud Serverless (InfluxDB 3 storage engine): + # /api/v2/checks: {} + # /api/v2/checks/{checkID}: {} + # /api/v2/checks/{checkID}/labels: {} + # /api/v2/checks/{checkID}/labels/{labelID}: {} + # /api/v2/checks/{checkID}/query: {} + # /api/v2/dashboards: {} + # /api/v2/dashboards/{dashboardID}: {} + # /api/v2/dashboards/{dashboardID}/cells: {} + # /api/v2/dashboards/{dashboardID}/cells/{cellID}: {} + # /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: {} + # /api/v2/dashboards/{dashboardID}/labels: {} + # /api/v2/dashboards/{dashboardID}/labels/{labelID}: {} + # /api/v2/dashboards/{dashboardID}/members: {} + # /api/v2/dashboards/{dashboardID}/members/{userID}: {} + # /api/v2/dashboards/{dashboardID}/owners: {} + # /api/v2/dashboards/{dashboardID}/owners/{userID}: {} + # /api/v2/dbrps: + # get: + # description: | + # Lists database retention policy (DBRP) mappings. - #### Related guide + # #### Related guide - - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) - operationId: GetDBRPs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Only returns DBRP mappings for the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns DBRP mappings for the specified organization. - in: query - name: org - schema: - type: string - - description: | - A DBPR mapping ID. - Only returns the specified DBRP mapping. - in: query - name: id - schema: - type: string - - description: | - A bucket ID. - Only returns DBRP mappings that belong to the specified bucket. - in: query - name: bucketID - schema: - type: string - - description: Specifies filtering on default - in: query - name: default - schema: - type: boolean - - description: | - A database. - Only returns DBRP mappings that belong to the 1.x database. - in: query - name: db - schema: - type: string - - description: | - A [retention policy](/influxdb3/cloud-serverless/reference/glossary/#retention-policy-rp). - Specifies the 1.x retention policy to filter on. - in: query - name: rp - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - - bucketID: 4d4d9d5b61dee751 - database: example_database_1 - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - - bucketID: 4d4d9d5b61dee751 - database: example_database_2 - default: false - id: 0a3cbcde20e38000 - orgID: bea7ea952287f70d - retention_policy: example_retention_policy - schema: - $ref: '#/components/schemas/DBRPs' - description: Success. The response body contains a list of database retention policy mappings. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The request has one or more invalid parameters. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List database retention policy mappings - tags: - - DBRPs - post: - description: | - Creates a database retention policy (DBRP) mapping and returns the mapping. + # - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) + # operationId: GetDBRPs + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # An organization ID. + # Only returns DBRP mappings for the specified organization. + # in: query + # name: orgID + # schema: + # type: string + # - description: | + # An organization name. + # Only returns DBRP mappings for the specified organization. + # in: query + # name: org + # schema: + # type: string + # - description: | + # A DBPR mapping ID. + # Only returns the specified DBRP mapping. + # in: query + # name: id + # schema: + # type: string + # - description: | + # A bucket ID. + # Only returns DBRP mappings that belong to the specified bucket. + # in: query + # name: bucketID + # schema: + # type: string + # - description: Specifies filtering on default + # in: query + # name: default + # schema: + # type: boolean + # - description: | + # A database. + # Only returns DBRP mappings that belong to the 1.x database. + # in: query + # name: db + # schema: + # type: string + # - description: | + # A [retention policy](/influxdb3/cloud-serverless/reference/glossary/#retention-policy-rp). + # Specifies the 1.x retention policy to filter on. + # in: query + # name: rp + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # content: + # - bucketID: 4d4d9d5b61dee751 + # database: example_database_1 + # default: true + # id: 0a3cbb5dd526a000 + # orgID: bea7ea952287f70d + # retention_policy: autogen + # - bucketID: 4d4d9d5b61dee751 + # database: example_database_2 + # default: false + # id: 0a3cbcde20e38000 + # orgID: bea7ea952287f70d + # retention_policy: example_retention_policy + # schema: + # $ref: '#/components/schemas/DBRPs' + # description: Success. The response body contains a list of database retention policy mappings. + # '400': + # content: + # application/json: + # examples: + # invalidRequest: + # description: | + # The query parameters contain invalid values. + # value: + # code: invalid + # message: invalid ID + # schema: + # $ref: '#/components/schemas/Error' + # description: Bad request. The request has one or more invalid parameters. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List database retention policy mappings + # tags: + # - DBRPs + # post: + # description: | + # Creates a database retention policy (DBRP) mapping and returns the mapping. - Use this endpoint to add InfluxDB 1.x API compatibility to your - InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a - DBRP mapping in order to query and write using the InfluxDB 1.x API. - object. + # Use this endpoint to add InfluxDB 1.x API compatibility to your + # InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a + # DBRP mapping in order to query and write using the InfluxDB 1.x API. + # object. - #### Related guide + # #### Related guide - - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) - operationId: PostDBRP - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPCreate' - description: | - The database retention policy mapping to add. + # - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) + # operationId: PostDBRP + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/DBRPCreate' + # description: | + # The database retention policy mapping to add. - Note that _`retention_policy`_ is a required parameter in the request body. - The value of _`retention_policy`_ can be any arbitrary `string` name or - value, with the default value commonly set as `autogen`. - The value of _`retention_policy`_ isn't a [retention_policy](/influxdb3/cloud-serverless/reference/glossary/#retention-policy-rp) - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - bucketID: 4d4d9d5b61dee751 - database: example_database - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - schema: - $ref: '#/components/schemas/DBRP' - description: Created. The response body contains the database retention policy mapping. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The mapping in the request has one or more invalid IDs. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a database retention policy mapping - tags: - - DBRPs - x-codeSamples: - - label: 'cURL: create a database retention policy mapping' - lang: Shell - source: | - curl --request POST \ - "http://localhost:8086/api/v2/dbrp/" \ - --header 'Content-type: application/json' \ - --header "Authorization: Token INFLUXDB_TOKEN" \ - --data-binary @- << EOF - { \ - "bucketID": "INFLUXDB_BUCKET_ID", \ - "orgID": "INFLUXDB_ORG_ID", \ - "database": "database_name", \ - "default": true, \ - "retention_policy": "example_retention_policy_name" \ - } - EOF - /api/v2/dbrps/{dbrpID}: - delete: - description: | - Deletes the specified database retention policy (DBRP) mapping. + # Note that _`retention_policy`_ is a required parameter in the request body. + # The value of _`retention_policy`_ can be any arbitrary `string` name or + # value, with the default value commonly set as `autogen`. + # The value of _`retention_policy`_ isn't a [retention_policy](/influxdb3/cloud-serverless/reference/glossary/#retention-policy-rp) + # required: true + # responses: + # '201': + # content: + # application/json: + # examples: + # successResponse: + # value: + # bucketID: 4d4d9d5b61dee751 + # database: example_database + # default: true + # id: 0a3cbb5dd526a000 + # orgID: bea7ea952287f70d + # retention_policy: autogen + # schema: + # $ref: '#/components/schemas/DBRP' + # description: Created. The response body contains the database retention policy mapping. + # '400': + # content: + # application/json: + # examples: + # invalidRequest: + # description: | + # The query parameters contain invalid values. + # value: + # code: invalid + # message: invalid ID + # schema: + # $ref: '#/components/schemas/Error' + # description: Bad request. The mapping in the request has one or more invalid IDs. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add a database retention policy mapping + # tags: + # - DBRPs + # x-codeSamples: + # - label: 'cURL: create a database retention policy mapping' + # lang: Shell + # source: | + # curl --request POST \ + # "http://localhost:8086/api/v2/dbrp/" \ + # --header 'Content-type: application/json' \ + # --header "Authorization: Token INFLUXDB_TOKEN" \ + # --data-binary @- << EOF + # { \ + # "bucketID": "INFLUXDB_BUCKET_ID", \ + # "orgID": "INFLUXDB_ORG_ID", \ + # "database": "database_name", \ + # "default": true, \ + # "retention_policy": "example_retention_policy_name" \ + # } + # EOF + # /api/v2/dbrps/{dbrpID}: + # delete: + # description: | + # Deletes the specified database retention policy (DBRP) mapping. - #### Related guide + # #### Related guide - - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) - operationId: DeleteDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Only returns the specified DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '204': - description: Success. The delete is accepted. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a database retention policy - tags: - - DBRPs - get: - description: | - Retrieves the specified retention policy (DBRP) mapping. + # - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) + # operationId: DeleteDBRPID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # An organization ID. + # Specifies the organization that owns the DBRP mapping. + # in: query + # name: orgID + # schema: + # type: string + # - description: | + # An organization name. + # Specifies the organization that owns the DBRP mapping. + # in: query + # name: org + # schema: + # type: string + # - description: | + # A DBRP mapping ID. + # Only returns the specified DBRP mapping. + # in: path + # name: dbrpID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Success. The delete is accepted. + # '400': + # content: + # application/json: + # examples: + # invalidRequest: + # description: | + # The query parameters contain invalid values. + # value: + # code: invalid + # message: invalid ID + # schema: + # $ref: '#/components/schemas/Error' + # description: Bad Request. Query parameters contain invalid values. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Delete a database retention policy + # tags: + # - DBRPs + # get: + # description: | + # Retrieves the specified retention policy (DBRP) mapping. - #### Related guide + # #### Related guide - - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) - operationId: GetDBRPsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Specifies the DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - bucketID: 4d4d9d5b61dee751 - database: example_database_1 - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - schema: - $ref: '#/components/schemas/DBRPGet' - description: Success. The response body contains the DBRP mapping. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a database retention policy mapping - tags: - - DBRPs - patch: - operationId: PatchDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Specifies the DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPUpdate' - description: | - Updates the database retention policy (DBRP) mapping and returns the mapping. + # - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) + # operationId: GetDBRPsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # An organization ID. + # Specifies the organization that owns the DBRP mapping. + # in: query + # name: orgID + # schema: + # type: string + # - description: | + # An organization name. + # Specifies the organization that owns the DBRP mapping. + # in: query + # name: org + # schema: + # type: string + # - description: | + # A DBRP mapping ID. + # Specifies the DBRP mapping. + # in: path + # name: dbrpID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # content: + # bucketID: 4d4d9d5b61dee751 + # database: example_database_1 + # default: true + # id: 0a3cbb5dd526a000 + # orgID: bea7ea952287f70d + # retention_policy: autogen + # schema: + # $ref: '#/components/schemas/DBRPGet' + # description: Success. The response body contains the DBRP mapping. + # '400': + # content: + # application/json: + # examples: + # invalidRequest: + # description: | + # The query parameters contain invalid values. + # value: + # code: invalid + # message: invalid ID + # schema: + # $ref: '#/components/schemas/Error' + # description: Bad Request. Query parameters contain invalid values. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Retrieve a database retention policy mapping + # tags: + # - DBRPs + # patch: + # operationId: PatchDBRPID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # An organization ID. + # Specifies the organization that owns the DBRP mapping. + # in: query + # name: orgID + # schema: + # type: string + # - description: | + # An organization name. + # Specifies the organization that owns the DBRP mapping. + # in: query + # name: org + # schema: + # type: string + # - description: | + # A DBRP mapping ID. + # Specifies the DBRP mapping. + # in: path + # name: dbrpID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/DBRPUpdate' + # description: | + # Updates the database retention policy (DBRP) mapping and returns the mapping. - Use this endpoint to modify the _retention policy_ (`retention_policy` property) of a DBRP mapping. + # Use this endpoint to modify the _retention policy_ (`retention_policy` property) of a DBRP mapping. - #### Related guide + # #### Related guide - - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - bucketID: 4d4d9d5b61dee751 - database: example_database - default: false - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: example_retention_policy - schema: - $ref: '#/components/schemas/DBRPGet' - description: An updated mapping - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a database retention policy mapping - tags: - - DBRPs - x-codeSamples: - - label: 'cURL: Update a DBRP mapping' - lang: Shell - source: | - curl --request PATCH \ - "http://localhost:8086/api/v2/dbrp/DBRP_ID" \ - --header 'Content-type: application/json' \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data-binary @- << EOF - { - "default": true, - "retention_policy": "example_retention_policy_name" - } - EOF - /api/v2/delete: - post: - description: | - Deletes data from a bucket. + # - [Database and retention policy mapping](/influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/) + # required: true + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # content: + # bucketID: 4d4d9d5b61dee751 + # database: example_database + # default: false + # id: 0a3cbb5dd526a000 + # orgID: bea7ea952287f70d + # retention_policy: example_retention_policy + # schema: + # $ref: '#/components/schemas/DBRPGet' + # description: An updated mapping + # '400': + # content: + # application/json: + # examples: + # invalidRequest: + # description: | + # The query parameters contain invalid values. + # value: + # code: invalid + # message: invalid ID + # schema: + # $ref: '#/components/schemas/Error' + # description: Bad Request. Query parameters contain invalid values. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Update a database retention policy mapping + # tags: + # - DBRPs + # x-codeSamples: + # - label: 'cURL: Update a DBRP mapping' + # lang: Shell + # source: | + # curl --request PATCH \ + # "http://localhost:8086/api/v2/dbrp/DBRP_ID" \ + # --header 'Content-type: application/json' \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --data-binary @- << EOF + # { + # "default": true, + # "retention_policy": "example_retention_policy_name" + # } + # EOF + # /api/v2/delete: + # post: + # description: | + # Deletes data from a bucket. - **NOTE**: This endpoint has been **disabled** for InfluxDB 3 Cloud Serverless organizations. - See how to [**delete data**](/influxdb3/cloud-serverless/write-data/delete-data/). + # **NOTE**: This endpoint has been **disabled** for InfluxDB 3 Cloud Serverless organizations. + # See how to [**delete data**](/influxdb3/cloud-serverless/write-data/delete-data/). - #### Related guides + # #### Related guides - - [Delete data](/influxdb3/cloud-serverless/write-data/delete-data/) - operationId: PostDelete - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization name or ID. + # - [Delete data](/influxdb3/cloud-serverless/write-data/delete-data/) + # operationId: PostDelete + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # An organization name or ID. - #### InfluxDB 3 Cloud Serverless + # #### InfluxDB 3 Cloud Serverless - - Doesn't use the `org` parameter or `orgID` parameter. - in: query - name: org - schema: - description: The organization name or ID. - type: string - - description: | - A bucket name or ID. - Specifies the bucket to delete data from. - If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. - in: query - name: bucket - schema: - description: The bucket name or ID. - type: string - - description: | - An organization ID. + # - Doesn't use the `org` parameter or `orgID` parameter. + # in: query + # name: org + # schema: + # description: The organization name or ID. + # type: string + # - description: | + # A bucket name or ID. + # Specifies the bucket to delete data from. + # If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. + # in: query + # name: bucket + # schema: + # description: The bucket name or ID. + # type: string + # - description: | + # An organization ID. - #### InfluxDB 3 Cloud Serverless + # #### InfluxDB 3 Cloud Serverless - - Doesn't use the `org` parameter or `orgID` parameter. - in: query - name: orgID - schema: - description: The organization ID. - type: string - - description: | - A bucket ID. - Specifies the bucket to delete data from. - If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. - in: query - name: bucketID - schema: - description: The bucket ID. - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DeletePredicateRequest' - description: | - Time range parameters and an optional **delete predicate expression**. + # - Doesn't use the `org` parameter or `orgID` parameter. + # in: query + # name: orgID + # schema: + # description: The organization ID. + # type: string + # - description: | + # A bucket ID. + # Specifies the bucket to delete data from. + # If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. + # in: query + # name: bucketID + # schema: + # description: The bucket ID. + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/DeletePredicateRequest' + # description: | + # Time range parameters and an optional **delete predicate expression**. - To select points to delete within the specified time range, pass a - **delete predicate expression** in the `predicate` property of the request body. - If you don't pass a `predicate`, InfluxDB deletes all data with timestamps - in the specified time range. - required: true - responses: - '204': - description: | - **NOTE**: This endpoint has been **disabled** for InfluxDB 3 Cloud Serverless organizations. - See how to [**delete data**](/influxdb3/cloud-serverless/write-data/delete-data/). - '400': - content: - application/json: - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete data - tags: - - Delete - /api/v2/flags: {} - /api/v2/labels: {} - /api/v2/labels/{labelID}: {} - /api/v2/maps/mapToken: - get: - operationId: getMapboxToken - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Token' - description: Temporary token for Mapbox. - '401': - $ref: '#/components/responses/ServerError' - '500': - $ref: '#/components/responses/ServerError' - default: - $ref: '#/components/responses/ServerError' - summary: Get a mapbox token - /api/v2/me: {} - /api/v2/me/password: {} - /api/v2/notificationEndpoints: {} - /api/v2/notificationEndpoints/{endpointID}: {} - /api/v2/notificationEndpoints/{endpointID}/labels: {} - /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: {} - /api/v2/notificationRules: {} - /api/v2/notificationRules/{ruleID}: {} - /api/v2/notificationRules/{ruleID}/labels: {} - /api/v2/notificationRules/{ruleID}/labels/{labelID}: {} - /api/v2/notificationRules/{ruleID}/query: {} + # To select points to delete within the specified time range, pass a + # **delete predicate expression** in the `predicate` property of the request body. + # If you don't pass a `predicate`, InfluxDB deletes all data with timestamps + # in the specified time range. + # required: true + # responses: + # '204': + # description: | + # **NOTE**: This endpoint has been **disabled** for InfluxDB 3 Cloud Serverless organizations. + # See how to [**delete data**](/influxdb3/cloud-serverless/write-data/delete-data/). + # '400': + # content: + # application/json: + # examples: + # orgNotFound: + # summary: Organization not found + # value: + # code: invalid + # message: 'failed to decode request body: organization not found' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # The response body contains detail about the error. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Delete data + # tags: + # - Delete + # /api/v2/flags: {} + # /api/v2/labels: {} + # /api/v2/labels/{labelID}: {} + # /api/v2/maps/mapToken: + # get: + # operationId: getMapboxToken + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Token' + # description: Temporary token for Mapbox. + # '401': + # $ref: '#/components/responses/ServerError' + # '500': + # $ref: '#/components/responses/ServerError' + # default: + # $ref: '#/components/responses/ServerError' + # summary: Get a mapbox token + # /api/v2/me: {} + # /api/v2/me/password: {} + # /api/v2/notificationEndpoints: {} + # /api/v2/notificationEndpoints/{endpointID}: {} + # /api/v2/notificationEndpoints/{endpointID}/labels: {} + # /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: {} + # /api/v2/notificationRules: {} + # /api/v2/notificationRules/{ruleID}: {} + # /api/v2/notificationRules/{ruleID}/labels: {} + # /api/v2/notificationRules/{ruleID}/labels/{labelID}: {} + # /api/v2/notificationRules/{ruleID}/query: {} /api/v2/orgs: get: description: | @@ -3040,7 +3045,7 @@ paths: Lists all users that belong to an organization. InfluxDB 3 Cloud Serverless doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to manage resource permissions. + Use `/api/v2/authorizations` to manage resource permissions. operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3113,7 +3118,7 @@ paths: Add a user to an organization. InfluxDB 3 Cloud Serverless doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to manage resource permissions. + Use `/api/v2/authorizations` to manage resource permissions. operationId: PostOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3190,7 +3195,7 @@ paths: Removes a member from an organization. InfluxDB 3 Cloud Serverless doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to manage resource permissions. + Use `/api/v2/authorizations` to manage resource permissions. operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3232,7 +3237,7 @@ paths: Lists all owners of an organization. InfluxDB 3 Cloud Serverless doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to manage resource permissions. + Use `/api/v2/authorizations` to manage resource permissions. operationId: GetOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3282,7 +3287,7 @@ paths: Adds an owner to an organization. InfluxDB 3 Cloud Serverless doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to manage resource permissions. + Use `/api/v2/authorizations` to manage resource permissions. operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3352,7 +3357,7 @@ paths: the organization. InfluxDB 3 Cloud Serverless doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to manage resource permissions. + Use `/api/v2/authorizations` to manage resource permissions. operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -3560,3665 +3565,3666 @@ paths: summary: Retrieve usage for an organization tags: - Usage - /ping: {} - /api/v2/query: - post: - deprecated: true - description: | - Retrieves data from buckets. - - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - - See how to [query data](/influxdb3/cloud-serverless/query-data/). - operationId: PostQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The content encoding (usually a compression algorithm) that the client can understand. - in: header - name: Accept-Encoding - schema: - default: identity - description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - enum: - - application/json - - application/vnd.flux - type: string - - description: | - An organization name or ID. - - #### InfluxDB 3 Cloud Serverless - - - Doesn't use the `org` parameter or `orgID` parameter. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - - #### InfluxDB 3 Cloud Serverless - - - Doesn't use the `org` parameter or `orgID` parameter. - in: query - name: orgID - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - schema: - type: string - description: Flux query or specification to execute - responses: - '200': - content: - application/csv: - schema: - type: string - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - headers: - Content-Encoding: - description: Lists encodings (usually compression algorithms) that have been applied to the response payload. - schema: - default: identity - description: | - The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - Trace-Id: - description: The trace ID, if generated, of the request. - schema: - description: Trace ID of a request. - type: string - '400': - content: - application/json: - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '429': - description: | - #### InfluxDB 3 Cloud Serverless: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb3/cloud-serverless/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](/influxdb3/cloud-serverless/account-management/limits/#global-limits). - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Query data - tags: - - Query data - /api/v2/query/analyze: - post: - deprecated: true - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - operationId: PostQueryAnalyze - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - description: Flux query to analyze - responses: - '200': - content: - application/json: - examples: - missingQueryPropertyKey: - description: | - Returns an error object if the Flux query is missing a property key. - - The following sample query is missing the _`bucket`_ property key: - - ```json - { - "query": "from(: \"iot_center\")\ - ... - } - ``` - summary: Missing property key error - value: - errors: - - character: 0 - column: 6 - line: 1 - message: missing property key - schema: - $ref: '#/components/schemas/AnalyzeQueryResponse' - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - '400': - content: - application/json: - examples: - invalidJSONStringValue: - description: If the request body contains invalid JSON, returns `invalid` and problem detail. - summary: Invalid JSON - value: - code: invalid - message: 'invalid json: invalid character ''\'''' looking for beginning of value' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the problem. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - default: - content: - application/json: - examples: - emptyJSONObject: - description: | - If the request body contains an empty JSON object, returns `internal error`. - summary: Empty JSON object in request body - value: - code: internal error - message: An internal error has occurred - check server logs - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - headers: - X-Influx-Error: - description: A string that describes the problem. - schema: - type: string - X-Influx-Reference: - description: The numeric reference code for the error type. - schema: - type: integer - X-Platform-Error-Code: - description: The reason for the error. - schema: - example: internal error - type: string - summary: Analyze a Flux query - tags: - - Query data - /api/v2/query/ast: - post: - deprecated: true - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - operationId: PostQueryAst - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LanguageRequest' - description: The Flux query to analyze. - responses: - '200': - content: - schema: - $ref: '#/components/schemas/ASTResponse' - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - '400': - content: - application/json: - examples: - invalidASTValue: - description: | - If the request body contains a missing property key in `from()`, - returns `invalid` and problem detail. - summary: Invalid AST - value: - code: invalid - message: 'invalid AST: loc 1:6-1:19: missing property key' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the problem. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - summary: Generate a query Abstract Syntax Tree (AST) - tags: - - Query data - /api/v2/query/suggestions: - get: - deprecated: true - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - operationId: GetQuerySuggestions - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - '301': - content: - text/html: - examples: - movedPermanently: - description: | - The URL has been permanently moved. Use `/api/v2/query/suggestions`. - summary: Invalid URL - value: | - Moved Permanently - schema: - properties: - body: - description: Response message with URL of requested resource. - readOnly: true - type: string - description: | - Moved Permanently. - InfluxData has moved the URL of the endpoint. - Use `/api/v2/query/suggestions` (without a trailing slash). - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - summary: List Flux query suggestions - tags: - - Query data - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "INFLUX_URL/api/v2/query/suggestions" \ - --header "Accept: application/json" \ - --header "Authorization: Token INFLUX_API_TOKEN" - /api/v2/query/suggestions/{name}: - get: - deprecated: true - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - operationId: GetQuerySuggestionsName - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name. - in: path - name: name - required: true - schema: - type: string - responses: - '200': - description: | - This endpoint isn't supported in InfluxDB 3 Cloud Serverless. - See how to [query data](/influxdb3/cloud-serverless/query-data/). - '500': - content: - application/json: - examples: - internalError: - description: | - The requested function doesn't exist. - summary: Invalid function - value: - code: internal error - message: An internal error has occurred - schema: - $ref: '#/components/schemas/Error' - description: | - Internal server error. - The value passed for _`name`_ may have been misspelled. - summary: Retrieve a query suggestion for a branching suggestion - tags: - - Query data - /api/v2/resources: - get: - operationId: GetResources - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - items: - type: string - type: array - description: All resources targets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: List all known resources - tags: - - Resources - - System information endpoints - /api/v2/scripts: - get: - description: | - Lists scripts. - - - operationId: GetScripts - parameters: - - description: | - The offset for pagination. - The number of records to skip. - - For more information about pagination parameters, see [Pagination](/influxdb3/cloud-serverless/api/#tag/Pagination). - in: query - name: offset - required: false - schema: - minimum: 0 - type: integer - - description: | - The maximum number of scripts to return. Default is `100`. - in: query - name: limit - required: false - schema: - default: 100 - maximum: 500 - minimum: 0 - type: integer - - description: The script name. Lists scripts with the specified name. - in: query - name: name - required: false - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - scripts: - - createdAt: '2022-07-17T23:49:45.731237Z' - description: find the last point from Sample Bucket - id: 09afa3b220fe4000 - language: flux - name: getLastPointFromSampleBucket - orgID: bea7ea952287f70d - script: 'from(bucket: SampleBucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:49:45.731237Z' - - createdAt: '2022-07-17T23:43:26.660308Z' - description: getLastPoint finds the last point in a bucket - id: 09afa23ff13e4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:43:26.660308Z' - schema: - $ref: '#/components/schemas/Scripts' - description: | - Success. - The response body contains the list of scripts. - '400': - content: - application/json: - examples: - invalidSyntaxError: - summary: Query parameter contains invalid syntax. - value: - code: 3 - details: [] - message: 'parsing field "limit": strconv.ParseUint: parsing "-1": invalid syntax' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the error. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: List scripts - tags: - - Invokable Scripts - x-codeSamples: - - label: 'cURL: retrieves the first 100 scripts.' - lang: Shell - source: | - curl --request GET "INFLUX_URL/api/v2/scripts?limit=100&offset=0" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" - post: - description: | - Creates an invokable script - and returns the script. - - - operationId: PostScripts - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScriptCreateRequest' - description: The script to create. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-07-17T23:43:26.660308Z' - description: getLastPoint finds the last point in a bucket - id: 09afa23ff13e4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:43:26.660308Z' - schema: - $ref: '#/components/schemas/Script' - description: | - Success. - The response body contains the script and its metadata. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '422': - content: - application/json: - examples: - uniquenessError: - description: | - A script with the same `name` exists. - value: - code: conflict - message: uniqueness violation - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Create a script - tags: - - Invokable Scripts - /api/v2/scripts/{scriptID}: - delete: - description: | - Deletes a script and all associated records. - - #### Limitations - - - You can delete only one script per request. - - If the script ID you provide doesn't exist for the organization, InfluxDB - responds with an HTTP `204` status code. - - - operationId: DeleteScriptsID - parameters: - - description: | - A script ID. - Deletes the specified script. - in: path - name: scriptID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The script is queued for deletion. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a script - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl -X 'DELETE' \ - "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header 'Accept: application/json' - get: - description: | - Retrieves a script. - - - operationId: GetScriptsID - parameters: - - description: | - A script ID. - Retrieves the specified script. - in: path - name: scriptID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-07-17T23:49:45.731237Z' - description: getLastPoint finds the last point in a bucket - id: 09afa3b220fe4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:49:45.731237Z' - schema: - $ref: '#/components/schemas/Script' - description: Success. The response body contains the script. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested script was not found. - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/ServerError' - description: Internal server error. - summary: Retrieve a script - tags: - - Invokable Scripts - patch: - description: | - Updates an invokable script. - - Use this endpoint to modify values for script properties (`description` and `script`). - - To update a script, pass an object that contains the updated key-value pairs. - - #### Limitations - - - If you send an empty request body, the script will neither update nor - store an empty script, but InfluxDB will respond with an HTTP `200` status - code. - - - operationId: PatchScriptsID - parameters: - - description: | - A script ID. - Updates the specified script. - in: path - name: scriptID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScriptUpdateRequest' - description: | - An object that contains the updated script properties to apply. - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-07-17T23:49:45.731237Z' - description: get last point from new bucket - id: 09afa3b220fe4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-19T22:27:23.185436Z' - schema: - $ref: '#/components/schemas/Script' - description: Success. The response body contains the updated script. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested script wasn't found. - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Update a script - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl -X 'PATCH' \ - "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" - --header "Content-Type: application/json" - --data '{ - "description": "get last point from new bucket", - "script": "from(bucket: updatedBucket) |> range(start: -7d) |> limit(n:1)", "language": "flux" - }' - /api/v2/scripts/{scriptID}/invoke: - post: - description: | - Runs a script and returns the result. - When the script runs, InfluxDB replaces `params` keys referenced in the script with - `params` key-values passed in the request body--for example: - - The following sample script contains a _`mybucket`_ parameter : - - ```json - "script": "from(bucket: params.mybucket) - |> range(start: -7d) - |> limit(n:1)" - ``` - - The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request body - passes a value for the _`mybucket`_ parameter: - - ```json - { - "params": { - "mybucket": "air_sensor" - } - } - ``` - - - operationId: PostScriptsIDInvoke - parameters: - - description: | - A script ID. - Runs the specified script. - in: path - name: scriptID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScriptInvocationParams' - responses: - '200': - content: - text/csv: - examples: - successResponse: - value: | - ,result,table,_start,_stop,_time,_value,_field,_measurement,host - ,_result,0,2019-10-30T01:28:02.52716421Z,2022-07-26T01:28:02.52716421Z,2020-01-01T00:00:00Z,72.01,used_percent,mem,host2 - schema: - $ref: '#/components/schemas/ScriptHTTPResponseData' - description: | - Success. - The response body contains the result of the script execution. - '400': - content: - application/json: - examples: - invalidParameters: - summary: The parameters passed to the script are invalid. - value: - code: invalid - message: invalid parameters provided - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the error. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - bucketNotFound: - description: InfluxDB can't find the requested bucket. - summary: | - Bucket not found - value: - code: not found - message: 'failed to initialize execute state: could not find bucket "test-bucket"' - scriptNotFound: - description: InfluxDB can't find the requested script. - summary: | - Script not found - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: not found - type: string - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Invoke a script - tags: - - Invokable Scripts - /api/v2/scripts/{scriptID}/params: - get: - description: | - Analyzes a script and determines required parameters. - Find all `params` keys referenced in a script and return a list - of keys. If it is possible to determine the type of the value - from the context then the type is also returned -- for example: - - The following sample script contains a _`mybucket`_ parameter : - - ```json - "script": "from(bucket: params.mybucket) - |> range(start: -7d) - |> limit(n:1)" - ``` - - Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params` - returns the following: - - ```json - { - "params": { - "mybucket": "string" - } - } - ``` - - The type name returned for a parameter will be one of: - - - `any` - - `bool` - - `duration` - - `float` - - `int` - - `string` - - `time` - - `uint` - - The type name `any` is used when the type of a parameter cannot - be determined from the context, or the type is determined to - be a structured type such as an array or record. - - - operationId: GetScriptsIDParams - parameters: - - description: | - A script ID. - The script to analyze for params. - in: path - name: scriptID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - params: - mybucket: string - schema: - $ref: '#/components/schemas/Params' - description: | - Success. - The response body contains the parameters found, along with their types. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - scriptNotFound: - description: InfluxDB can't find the requested script. - summary: | - Script not found - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: not found - type: string - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Find script parameters. - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \ - --header "Authorization: Token INFLUX_TOKEN" - /api/v2/setup: {} - /api/v2/setup/user: {} - /api/v2/signin: {} - /api/v2/signout: {} - /api/v2/stacks: - get: - description: | - Lists installed InfluxDB stacks. - - To limit stacks in the response, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all installed stacks - for the organization. - - - operationId: ListStacks - parameters: - - description: | - An organization ID. - Only returns stacks owned by the specified [organization](/influxdb3/cloud-serverless/reference/glossary/#organization). - - #### InfluxDB Cloud - - - Doesn't require this parameter; - InfluxDB only returns resources allowed by the API token. - in: query - name: orgID - required: true - schema: - type: string - - description: | - A stack name. - Finds stack `events` with this name and returns the stacks. - - Repeatable. - To filter for more than one stack name, - repeat this parameter with each name--for example: - - - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` - examples: - findStackByName: - summary: Find stacks with the event name - value: project-stack-0 - in: query - name: name - schema: - type: string - - description: | - A stack ID. - Only returns the specified stack. - - Repeatable. - To filter for more than one stack ID, - repeat this parameter with each ID--for example: - - - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` - examples: - findStackByID: - summary: Find a stack with the ID - value: 09bd87cd33be3000 - in: query - name: stackID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - properties: - stacks: - items: - $ref: '#/components/schemas/Stack' - type: array - type: object - description: Success. The response body contains the list of stacks. - '400': - content: - application/json: - examples: - orgIdMissing: - summary: The orgID query parameter is missing - value: - code: invalid - message: 'organization id[""] is invalid: id must have a length of 16 bytes' - orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in the header - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List installed stacks - tags: - - Templates - post: - description: | - Creates or initializes a stack. - - Use this endpoint to _manually_ initialize a new stack with the following - optional information: - - - Stack name - - Stack description - - URLs for template manifest files - - To automatically create a stack when applying templates, - use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). - - #### Required permissions - - - `write` permission for the organization - - - operationId: CreateStack - requestBody: - content: - application/json: - schema: - properties: - description: - type: string - name: - type: string - orgID: - type: string - urls: - items: - type: string - type: array - title: PostStackRequest - type: object - description: The stack to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Success. Returns the newly created stack. - '401': - $ref: '#/components/responses/AuthorizationError' - '422': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - - You passed a parameter combination that InfluxDB doesn't support. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a stack - tags: - - Templates - /api/v2/stacks/{stack_id}: - delete: - operationId: DeleteStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - - description: The identifier of the organization. - in: query - name: orgID - required: true - schema: - type: string - responses: - '204': - description: The stack and its associated resources were deleted. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a stack and associated resources - tags: - - Templates - get: - operationId: ReadStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a stack - tags: - - Templates - patch: - operationId: UpdateStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - additionalResources: - items: - properties: - kind: - type: string - resourceID: - type: string - templateMetaName: - type: string - required: - - kind - - resourceID - type: object - type: array - description: - nullable: true - type: string - name: - nullable: true - type: string - templateURLs: - items: - type: string - nullable: true - type: array - title: PatchStackRequest - type: object - description: The stack to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the updated stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a stack - tags: - - Templates - /api/v2/stacks/{stack_id}/uninstall: - post: - operationId: UninstallStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the uninstalled stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Uninstall a stack - tags: - - Templates - /api/v2/tasks: - get: - description: | - Retrieves a list of [tasks](/influxdb3/cloud-serverless/reference/glossary/#task). - - To limit which tasks are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. - operationId: GetTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) name. - Only returns tasks with the specified name. - Different tasks may have the same name. - in: query - name: name - schema: - type: string - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. - Only returns tasks created after the specified task. - in: query - name: after - schema: - type: string - - description: | - A [user](/influxdb3/cloud-serverless/reference/glossary/#user) ID. - Only returns tasks owned by the specified user. - in: query - name: user - schema: - type: string - - description: | - An [organization](/influxdb3/cloud-serverless/reference/glossary/#organization) name. - Only returns tasks owned by the specified organization. - in: query - name: org - schema: - type: string - - description: | - An [organization](/influxdb3/cloud-serverless/reference/glossary/#organization) ID. - Only returns tasks owned by the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) status. - Only returns tasks that have the specified status (`active` or `inactive`). - in: query - name: status - schema: - enum: - - active - - inactive - type: string - - description: | - The maximum number of [tasks](/influxdb3/cloud-serverless/reference/glossary/#task) to return. - Default is `100`. - The minimum is `1` and the maximum is `500`. - - To reduce the payload size, combine _`type=basic`_ and _`limit`_ (see _Request samples_). - For more information about the `basic` response, see the _`type`_ parameter. - examples: - all: - summary: Return all tasks, without pagination. - value: '-1' - minPaginated: - summary: Return a maximum of 50 tasks. - value: '50' - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: -1 - type: integer - - description: The number of records to skip. - in: query - name: offset - required: false - schema: - default: 0 - minimum: 0 - type: integer - - description: | - The sort field. Only `name` is supported. - Specifies the field used to sort records in the list. - in: query - name: sortBy - required: false - schema: - enum: - - name - type: string - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) type (`basic` or `system`). - Default is `system`. - Specifies the level of detail for tasks in the response. - The default (`system`) response contains all the metadata properties for tasks. - To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). - in: query - name: type - required: false - schema: - default: '' - enum: - - basic - - system - type: string - - description: | - A [script](#tag/Invokable-Scripts) ID. - Only returns tasks that use the specified invokable script. - in: query - name: scriptID - schema: - type: string - responses: - '200': - content: - application/json: - examples: - basicTypeTaskOutput: - description: | - A sample response body for the `?type=basic` parameter. - `type=basic` omits some task fields (`createdAt` and `updatedAt`) - and field values (`org`, `flux`) in the response. - summary: Basic output - value: - links: - self: /api/v2/tasks?limit=100 - tasks: - - every: 30m - flux: '' - id: 09956cbb6d378000 - labels: [] - lastRunStatus: success - latestCompleted: '2022-06-30T15:00:00Z' - links: - labels: /api/v2/tasks/09956cbb6d378000/labels - logs: /api/v2/tasks/09956cbb6d378000/logs - members: /api/v2/tasks/09956cbb6d378000/members - owners: /api/v2/tasks/09956cbb6d378000/owners - runs: /api/v2/tasks/09956cbb6d378000/runs - self: /api/v2/tasks/09956cbb6d378000 - name: task1 - org: '' - orgID: 48c88459ee424a04 - ownerID: 0772396d1f411000 - status: active - systemTypeTaskOutput: - description: | - A sample response body for the `?type=system` parameter. - `type=system` returns all task fields. - summary: System output - value: - links: - self: /api/v2/tasks?limit=100 - tasks: - - createdAt: '2022-06-27T15:09:06Z' - description: IoT Center 90-day environment average. - every: 30m - flux: |- - option task = {name: "task1", every: 30m} - - from(bucket: "iot_center") - |> range(start: -90d) - |> filter(fn: (r) => r._measurement == "environment") - |> aggregateWindow(every: 1h, fn: mean) - id: 09956cbb6d378000 - labels: [] - lastRunStatus: success - latestCompleted: '2022-06-30T15:00:00Z' - links: - labels: /api/v2/tasks/09956cbb6d378000/labels - logs: /api/v2/tasks/09956cbb6d378000/logs - members: /api/v2/tasks/09956cbb6d378000/members - owners: /api/v2/tasks/09956cbb6d378000/owners - runs: /api/v2/tasks/09956cbb6d378000/runs - self: /api/v2/tasks/09956cbb6d378000 - name: task1 - org: my-iot-center - orgID: 48c88459ee424a04 - ownerID: 0772396d1f411000 - status: active - updatedAt: '2022-06-28T18:10:15Z' - schema: - $ref: '#/components/schemas/Tasks' - description: | - Success. - The response body contains the list of tasks. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List all tasks - tags: - - Tasks - x-codeSamples: - - label: 'cURL: all tasks, basic output' - lang: Shell - source: | - curl INFLUX_URL/api/v2/tasks/?limit=-1&type=basic \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Token INFLUX_API_TOKEN' - post: - description: | - Creates a [task](/influxdb3/cloud-serverless/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a Flux script. - - #### InfluxDB Cloud - - - You can use either `flux` or `scriptID` to provide the task script. - - - `flux`: a string of "raw" Flux that contains task options and the script--for example: - - ```json - { - "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ - from(bucket: \"telegraf\") - |> range(start: -1h) - |> filter(fn: (r) => (r._measurement == \"cpu\")) - |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) - |> filter(fn: (r) => (r.cpu == \"cpu-total\")) - |> aggregateWindow(every: 1h, fn: max) - |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", - "status": "active", - "description": "This task downsamples CPU data every hour" - } - ``` - - - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) - for the task to run. - To pass task options when using `scriptID`, pass the options as - properties in the request body--for example: - - ```json - { - "name": "CPU Total 1 Hour New", - "description": "This task downsamples CPU data every hour", - "every": "1h", - "scriptID": "SCRIPT_ID", - "scriptParameters": - { - "rangeStart": "-1h", - "bucket": "telegraf", - "filterField": "cpu-total" - } - } - ``` - - #### Limitations: - - - You can't use `flux` and `scriptID` for the same task. - - - operationId: PostTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TaskCreateRequest' - description: The task to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains a `tasks` list with the new task. - '400': - content: - application/json: - examples: - fluxAndScriptError: - summary: The request body can't contain both flux and scriptID - value: - code: invalid - message: 'failed to decode request: can not provide both scriptID and flux' - missingFluxError: - summary: The request body requires either a flux parameter or scriptID parameter - value: - code: invalid - message: 'failed to decode request: flux required' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB Cloud - - - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_. - - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a task - tags: - - Tasks - x-codeSamples: - - label: 'cURL: create a Flux script task' - lang: Shell - source: | - curl INFLUX_URL/api/v2/tasks \ - --header "Content-type: application/json" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data-binary @- << EOF - { - "orgID": "INFLUX_ORG_ID", - "description": "IoT Center 30d environment average.", - "flux": "option task = {name: \"iot-center-task-1\", every: 30m}\ - from(bucket: \"iot_center\")\ - |> range(start: -30d)\ - |> filter(fn: (r) => r._measurement == \"environment\")\ - |> aggregateWindow(every: 1h, fn: mean)" - } - EOF - - label: 'cURL: create a Flux script reference task' - lang: Shell - source: | - curl INFLUX_URL/api/v2/tasks \ - --header "Content-type: application/json" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data-binary @- << EOF - { - "orgID": "INFLUX_ORG_ID", - "description": "IoT Center 30d environment average.", - "scriptID": "085138a111448000", - "scriptParameters": - { - "rangeStart": "-30d", - "bucket": "air_sensor", - "filterField": "temperature", - "groupColumn": "_time" - } - } - EOF - /api/v2/tasks/{taskID}: - delete: - description: | - Deletes a [task](/influxdb3/cloud-serverless/reference/glossary/#task) and associated records. - - Use this endpoint to delete a task and all associated records (task runs, logs, and labels). - Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - - If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). - operationId: DeleteTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. Specifies the task to delete. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The task and task runs are deleted. Scheduled runs are canceled. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a task - tags: - - Tasks - get: - description: | - Retrieves a [task](/influxdb3/cloud-serverless/reference/glossary/#task). - operationId: GetTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. - Specifies the task to retrieve. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a task - tags: - - Tasks - patch: - description: | - Updates a [task](/influxdb3/cloud-serverless/reference/glossary/#task), - and then cancels all scheduled runs of the task. - - Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. - Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - - To update a task, pass an object that contains the updated key-value pairs. - To activate or inactivate a task, set the `status` property. - _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. - - #### InfluxDB Cloud - - - Use either `flux` or `scriptID` to provide the task script. - - - `flux`: a string of "raw" Flux that contains task options and the script--for example: - - ```json - { - "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ - from(bucket: \"telegraf\") - |> range(start: -1h) - |> filter(fn: (r) => (r._measurement == \"cpu\")) - |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) - |> filter(fn: (r) => (r.cpu == \"cpu-total\")) - |> aggregateWindow(every: 1h, fn: max) - |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", - "status": "active", - "description": "This task downsamples CPU data every hour" - } - ``` - - - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) - for the task to run. - To pass task options when using `scriptID`, pass the options as - properties in the request body--for example: - - ```json - { - "name": "CPU Total 1 Hour New", - "description": "This task downsamples CPU data every hour", - "every": "1h", - "scriptID": "SCRIPT_ID", - "scriptParameters": - { - "rangeStart": "-1h", - "bucket": "telegraf", - "filterField": "cpu-total" - } - } - ``` - - #### Limitations: - - - You can't use `flux` and `scriptID` for the same task. - operationId: PatchTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. - Specifies the task to update. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TaskUpdateRequest' - description: An task update to apply. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains the updated task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels: - get: - description: | - Retrieves a list of all labels for a task. - - Labels may be used for grouping and filtering tasks. - operationId: GetTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve labels for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: Success. The response body contains a list of all labels for the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List labels for a task - tags: - - Tasks - post: - description: | - Adds a label to a task. - - Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. - operationId: PostTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to label. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: An object that contains a _`labelID`_ to add to the task. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains a list of all labels for the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Add a label to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels/{labelID}: - delete: - description: | - Deletes a label from a task. - operationId: DeleteTasksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to delete the label from. - in: path - name: taskID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Success. The label is deleted. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a label from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/logs: - get: - description: | - Retrieves a list of all logs for a [task](/influxdb3/cloud-serverless/reference/glossary/#task). - - When an InfluxDB task runs, a “run” record is created in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. - - Use this endpoint to retrieve only the log events for a task, - without additional task metadata. - operationId: GetTasksIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - taskFailure: - summary: Events for a failed task run. - value: - events: - - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 - time: '2022-07-13T07:06:54.198167Z' - - message: Completed(failed) - runID: 09a946fc3167d000 - time: '2022-07-13T07:07:13.104037Z' - - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' - runID: 09a946fc3167d000 - time: '2022-07-13T08:24:37.115323Z' - taskSuccess: - summary: Events for a successful task run. - value: - events: - - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - schema: - $ref: '#/components/schemas/Logs' - description: | - Success. The response body contains an `events` list with logs for the task. - Each log event `message` contains detail about the event. - If a task run fails, InfluxDB logs an event with the reason for the failure. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve all logs for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members: - get: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Lists all users that have the `member` role for the specified [task](/influxdb3/cloud-serverless/reference/glossary/#task). - operationId: GetTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. The response body contains a list of `users` that have - the `member` role for a task. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all task members - tags: - - Tasks - post: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Adds a user to members of a task and returns the member. - operationId: PostTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as a member of the task. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Created. The user is added to task members. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members/{userID}: - delete: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes a member from a [task](/influxdb3/cloud-serverless/reference/glossary/#task). - operationId: DeleteTasksIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners: - get: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Retrieves all users that have owner permission for a task. - operationId: GetTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve owners for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: | - Success. - The response contains a list of `users` that have the `owner` role for the task. - - If the task has no owners, the response contains an empty `users` array. - '401': - $ref: '#/components/responses/AuthorizationError' - '422': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - - You passed a parameter combination that InfluxDB doesn't support. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a task - tags: - - Tasks - post: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Assigns a task `owner` role to a user. - - Use this endpoint to create a _resource owner_ for the task. - A _resource owner_ is a user with `role: owner` for a specific resource. - operationId: PostTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as an owner of the task. - required: true - responses: - '201': - content: - application/json: - examples: - createdOwner: - summary: User has the owner role for the resource - value: - id: 0772396d1f411000 - links: - logs: /api/v2/users/0772396d1f411000/logs - self: /api/v2/users/0772396d1f411000 - name: USER_NAME - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceOwner' - description: | - Created. The task `owner` role is assigned to the user. - The response body contains the resource owner with - role and user detail. - '401': - $ref: '#/components/responses/AuthorizationError' - '422': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - - You passed a parameter combination that InfluxDB doesn't support. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners/{userID}: - delete: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - operationId: DeleteTasksIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The task ID. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/runs: - get: - description: | - Retrieves a list of runs for a task. - - To limit which task runs are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. - - operationId: GetTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the task to get runs for. - Only returns runs for this task. - in: path - name: taskID - required: true - schema: - type: string - - description: A task run ID. Only returns runs created after this run. - in: query - name: after - schema: - type: string - - description: | - Limits the number of task runs returned. Default is `100`. - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: 1 - type: integer - - description: | - A timestamp ([RFC3339 date/time format](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after this time. - in: query - name: afterTime - schema: - format: date-time - type: string - - description: | - A timestamp ([RFC3339 date/time format](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before this time. - in: query - name: beforeTime - schema: - format: date-time - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Runs' - description: Success. The response body contains the list of task runs. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List runs for a task - tags: - - Tasks - post: - description: | - Schedules a task run to start immediately, ignoring scheduled runs. - - Use this endpoint to manually start a task run. - Scheduled runs will continue to run as scheduled. - This may result in concurrently running tasks. - - To _retry_ a previous run (and avoid creating a new run), - use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - operationId: PostTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RunManually' - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Run' - description: Success. The run is scheduled to start. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Start a task run, overriding the schedule - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}: - delete: - description: | - Cancels a running [task](/influxdb3/cloud-serverless/reference/glossary/#task). - - Use this endpoint with InfluxDB OSS to cancel a running task. - - #### InfluxDB Cloud - - - Doesn't support this operation. - - operationId: DeleteTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to cancel. - in: path - name: taskID - required: true - schema: - type: string - - description: The ID of the task run to cancel. - in: path - name: runID - required: true - schema: - type: string - responses: - '204': - description: | - Success. The `DELETE` is accepted and the run will be cancelled. - - #### InfluxDB Cloud - - - Doesn't support this operation. - - Doesn't return this status. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Method not allowed. - - #### InfluxDB Cloud - - - Always returns this error; doesn't support cancelling tasks. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Cancel a running task - tags: - - Tasks - get: - description: | - Retrieves a specific run for a task. - - Use this endpoint to retrieve detail and logs for a specific task run. - - operationId: GetTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve runs for. - in: path - name: taskID - required: true - schema: - type: string - - description: The ID of the run to retrieve. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - runSuccess: - summary: A successful task run. - value: - finishedAt: '2022-07-18T14:46:07.308254Z' - id: 09b070dadaa7d000 - links: - logs: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs - retry: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry - self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 - task: /api/v2/tasks/0996e56b2f378000 - log: - - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - requestedAt: '2022-07-18T14:46:06Z' - scheduledFor: '2022-07-18T14:46:06Z' - startedAt: '2022-07-18T14:46:07.16222Z' - status: success - taskID: 0996e56b2f378000 - schema: - $ref: '#/components/schemas/Run' - description: Success. The response body contains the task run. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a run for a task. - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/logs: - get: - description: | - Retrieves all logs for a task run. - A log is a list of run events with `runID`, `time`, and `message` properties. - - Use this endpoint to help analyze task performance and troubleshoot failed task runs. - - operationId: GetTasksIDRunsIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to get logs for. - in: path - name: taskID - required: true - schema: - type: string - - description: The ID of the run to get logs for. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - taskFailure: - summary: Events for a failed task. - value: - events: - - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 - time: '2022-07-13T07:06:54.198167Z' - - message: Completed(failed) - runID: 09a946fc3167d000 - time: '2022-07-13T07:07:13.104037Z' - - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' - runID: 09a946fc3167d000 - time: '2022-07-13T08:24:37.115323Z' - taskSuccess: - summary: Events for a successful task run. - value: - events: - - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - schema: - $ref: '#/components/schemas/Logs' - description: | - Success. The response body contains an `events` list with logs for the task run. - Each log event `message` contains detail about the event. - If a run fails, InfluxDB logs an event with the reason for the failure. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve all logs for a run - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/retry: - post: - description: | - Queues a task run to - retry and returns the scheduled run. - - To manually start a _new_ task run, use the - [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). - - #### Limitations - - - The task must be _active_ (`status: "active"`). - operationId: PostTasksIDRunsIDRetry - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. - Specifies the task to retry. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A [task](/influxdb3/cloud-serverless/reference/glossary/#task) run ID. - Specifies the task run to retry. - - To find a task run ID, use the - [`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns) - to list task runs. - in: path - name: runID - required: true - schema: - type: string - requestBody: - content: - application/json; charset=utf-8: - schema: - type: object - responses: - '200': - content: - application/json: - examples: - retryTaskRun: - summary: A task run scheduled to retry - value: - id: 09d60ffe08738000 - links: - logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs - retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry - self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 - task: /api/v2/tasks/09a776832f381000 - requestedAt: '2022-08-16T20:05:11.84145Z' - scheduledFor: '2022-08-15T00:00:00Z' - status: scheduled - taskID: 09a776832f381000 - schema: - $ref: '#/components/schemas/Run' - description: Success. The response body contains the queued run. - '400': - content: - application/json: - examples: - inactiveTask: - summary: Can't retry an inactive task - value: - code: invalid - message: 'failed to retry run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - InfluxDB may return this error for the following reasons: - - - The task has `status: inactive`. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retry a task run - tags: - - Tasks - /api/v2/telegraf/plugins: {} - /api/v2/telegrafs: - get: - operationId: GetTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID the Telegraf config belongs to. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegrafs' - description: A list of Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf configurations - tags: - - Telegrafs - post: - operationId: PostTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPluginRequest' - description: Telegraf configuration to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: Telegraf configuration created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}: - delete: - operationId: DeleteTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a Telegraf configuration - tags: - - Telegrafs - get: - operationId: GetTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - - in: header - name: Accept - required: false - schema: - default: application/toml - enum: - - application/toml - - application/json - - application/octet-stream - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - application/octet-stream: - example: |- - [agent] - interval = "10s" - schema: - type: string - application/toml: - example: |- - [agent] - interval = "10s" - schema: - type: string - description: Telegraf configuration details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a Telegraf configuration - tags: - - Telegrafs - put: - operationId: PutTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPluginRequest' - description: Telegraf configuration update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: An updated Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels: - get: - operationId: GetTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels/{labelID}: - delete: - operationId: DeleteTelegrafsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Telegraf config not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members: - get: - operationId: GetTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of Telegraf config members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members/{userID}: - delete: - operationId: DeleteTelegrafsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners: - get: - operationId: GetTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: Returns Telegraf configuration owners as a ResourceOwners list - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a Telegraf configuration - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners/{userID}: - delete: - operationId: DeleteTelegrafsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a Telegraf config - tags: - - Telegrafs - /api/v2/templates/apply: - post: - description: | - Applies a template to - create or update a stack of InfluxDB - resources. - The response contains the diff of changes and the stack ID. - - Use this endpoint to install an InfluxDB template to an organization. - Provide template URLs or template objects in your request. - To customize which template resources are installed, use the `actions` - parameter. - - By default, when you apply a template, InfluxDB installs the template to - create and update stack resources and then generates a diff of the changes. - If you pass `dryRun: true` in the request body, InfluxDB validates the - template and generates the resource diff, but doesn’t make any - changes to your instance. - - #### Custom values for templates - - - Some templates may contain environment references for custom metadata. - To provide custom values for environment references, pass the _`envRefs`_ - property in the request body. - - - Some templates may contain queries that use - [secrets](/influxdb3/cloud-serverless/reference/glossary/#secret). - To provide custom secret values, pass the _`secrets`_ property - in the request body. - Don't expose secret values in templates. - - #### Required permissions - - - `write` permissions for resource types in the template. - - #### Rate limits (with InfluxDB Cloud) - - - Adjustable service quotas apply. - For more information, see [limits and adjustable quotas](/influxdb3/cloud-serverless/account-management/limits/). - - - operationId: ApplyTemplate - requestBody: - content: - application/json: - examples: - skipKindAction: - summary: Skip all bucket and task resources in the provided templates - value: - actions: - - action: skipKind - properties: - kind: Bucket - - action: skipKind - properties: - kind: Task - orgID: INFLUX_ORG_ID - templates: - - contents: - - '[object Object]': null - skipResourceAction: - summary: Skip specific resources in the provided templates - value: - actions: - - action: skipResource - properties: - kind: Label - resourceTemplateName: foo-001 - - action: skipResource - properties: - kind: Bucket - resourceTemplateName: bar-020 - - action: skipResource - properties: - kind: Bucket - resourceTemplateName: baz-500 - orgID: INFLUX_ORG_ID - templates: - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Bucket - metadata: - name: baz-500 - templateObjectEnvRefs: - summary: envRefs for template objects - value: - envRefs: - docker-bucket: MY_DOCKER_BUCKET - docker-spec-1: MY_DOCKER_SPEC - linux-cpu-label: MY_CPU_LABEL - orgID: INFLUX_ORG_ID - templates: - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Label - metadata: - name: - envRef: - key: linux-cpu-label - spec: - color: '#326BBA' - name: inputs.cpu - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Bucket - metadata: - name: - envRef: - key: docker-bucket - schema: - $ref: '#/components/schemas/TemplateApply' - application/x-jsonnet: - schema: - $ref: '#/components/schemas/TemplateApply' - text/yml: - schema: - $ref: '#/components/schemas/TemplateApply' - description: | - Parameters for applying templates. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: | - Success. - The template dry run succeeded. - The response body contains a resource diff of changes that the - template would have made if installed. - No resources were created or updated. - The diff and summary won't contain IDs for resources - that didn't exist at the time of the dry run. - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: | - Success. - The template applied successfully. - The response body contains the stack ID, a diff, and a summary. - The diff compares the initial state to the state after the template installation. - The summary contains newly created resources. - '422': - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/TemplateSummary' - - properties: - code: - type: string - message: - type: string - required: - - message - - code - type: object - description: | - Unprocessable entity. - - - The error may indicate one of the following problems: - - - The template failed validation. - - You passed a parameter combination that InfluxDB doesn't support. - '500': - content: - application/json: - examples: - createExceedsQuota: - summary: 'InfluxDB Cloud: Creating resource would exceed quota.' - value: - code: internal error - message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\"" - schema: - $ref: '#/components/schemas/Error' - description: | - Internal server error. - - #### InfluxDB Cloud - - - Returns this error if creating one of the template - resources (bucket, dashboard, task, user) exceeds your plan’s - adjustable service quotas. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Apply or dry-run a template - tags: - - Templates - x-codeSamples: - - label: 'cURL: Dry run with a remote template' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF - { - "dryRun": true, - "orgID": "INFLUX_ORG_ID", - "remotes": [ - { - "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml" - } - ] - } - EOF - - label: 'cURL: Apply with secret values' - lang: Shell - source: | - curl "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF | jq . - { - "orgID": "INFLUX_ORG_ID", - "secrets": { - "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL" - }, - "remotes": [ - { - "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml" - } - ] - } - EOF - - label: 'cURL: Apply template objects with environment references' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF - { "orgID": "INFLUX_ORG_ID", - "envRefs": { - "linux-cpu-label": "MY_CPU_LABEL", - "docker-bucket": "MY_DOCKER_BUCKET", - "docker-spec-1": "MY_DOCKER_SPEC" - }, - "templates": [ - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Label", - "metadata": { - "name": { - "envRef": { - "key": "linux-cpu-label" - } - } - }, - "spec": { - "color": "#326BBA", - "name": "inputs.cpu" - } - }] - }, - "templates": [ - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Label", - "metadata": { - "name": { - "envRef": { - "key": "linux-cpu-label" - } - } - }, - "spec": { - "color": "#326BBA", - "name": "inputs.cpu" - } - }] - }, - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Bucket", - "metadata": { - "name": { - "envRef": { - "key": "docker-bucket" - } - } - } - }] - } - ] - } - EOF - /api/v2/templates/export: - post: - operationId: ExportTemplate - requestBody: - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/TemplateExportByID' - - $ref: '#/components/schemas/TemplateExportByName' - description: Export resources as an InfluxDB template. - required: false - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Template' - application/x-yaml: - schema: - $ref: '#/components/schemas/Template' - description: The template was created successfully. Returns the newly created template. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Export a new template - tags: - - Templates - /api/v2/users: {} - /api/v2/users/{userID}: {} - /api/v2/users/{userID}/password: {} - /api/v2/variables: - get: - operationId: GetVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the organization. - in: query - name: org - schema: - type: string - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variables' - description: A list of variables for an organization. - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: List all variables - tags: - - Variables - post: - operationId: PostVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable created - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Create a variable - tags: - - Variables - /api/v2/variables/{variableID}: - delete: - operationId: DeleteVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '204': - description: Variable deleted - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Delete a variable - tags: - - Variables - get: - operationId: GetVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable found - '404': - $ref: '#/components/responses/GeneralServerError' - description: Variable not found - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Retrieve a variable - tags: - - Variables - patch: - operationId: PatchVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Update a variable - tags: - - Variables - put: - operationId: PutVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to replace - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Replace a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels: - get: - operationId: GetVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a variable - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a variable - tags: - - Variables - post: - operationId: PostVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels/{labelID}: - delete: - operationId: DeleteVariablesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - - description: The label ID to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Variable not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a variable - tags: - - Variables + # InfluxDB Cloud (TSM) endpoints — not supported for Cloud Serverless (InfluxDB 3 storage engine): + # /ping: {} + # /api/v2/query: + # post: + # deprecated: true + # description: | + # Retrieves data from buckets. + + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # operationId: PostQuery + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The content encoding (usually a compression algorithm) that the client can understand. + # in: header + # name: Accept-Encoding + # schema: + # default: identity + # description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. + # enum: + # - gzip + # - identity + # type: string + # - in: header + # name: Content-Type + # schema: + # enum: + # - application/json + # - application/vnd.flux + # type: string + # - description: | + # An organization name or ID. + + # #### InfluxDB 3 Cloud Serverless + + # - Doesn't use the `org` parameter or `orgID` parameter. + # in: query + # name: org + # schema: + # type: string + # - description: | + # An organization ID. + + # #### InfluxDB 3 Cloud Serverless + + # - Doesn't use the `org` parameter or `orgID` parameter. + # in: query + # name: orgID + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Query' + # application/vnd.flux: + # schema: + # type: string + # description: Flux query or specification to execute + # responses: + # '200': + # content: + # application/csv: + # schema: + # type: string + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # headers: + # Content-Encoding: + # description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + # schema: + # default: identity + # description: | + # The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + # enum: + # - gzip + # - identity + # type: string + # Trace-Id: + # description: The trace ID, if generated, of the request. + # schema: + # description: Trace ID of a request. + # type: string + # '400': + # content: + # application/json: + # examples: + # orgNotFound: + # summary: Organization not found + # value: + # code: invalid + # message: 'failed to decode request body: organization not found' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # The response body contains detail about the error. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '429': + # description: | + # #### InfluxDB 3 Cloud Serverless: + # - returns this error if a **read** or **write** request exceeds your + # plan's [adjustable service quotas](/influxdb3/cloud-serverless/account-management/limits/#adjustable-service-quotas) + # or if a **delete** request exceeds the maximum + # [global limit](/influxdb3/cloud-serverless/account-management/limits/#global-limits). + # headers: + # Retry-After: + # description: Non-negative decimal integer indicating seconds to wait before retrying the request. + # schema: + # format: int32 + # type: integer + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Query data + # tags: + # - Query data + # /api/v2/query/analyze: + # post: + # deprecated: true + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # operationId: PostQueryAnalyze + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - in: header + # name: Content-Type + # schema: + # enum: + # - application/json + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Query' + # description: Flux query to analyze + # responses: + # '200': + # content: + # application/json: + # examples: + # missingQueryPropertyKey: + # description: | + # Returns an error object if the Flux query is missing a property key. + + # The following sample query is missing the _`bucket`_ property key: + + # ```json + # { + # "query": "from(: \"iot_center\")\ + # ... + # } + # ``` + # summary: Missing property key error + # value: + # errors: + # - character: 0 + # column: 6 + # line: 1 + # message: missing property key + # schema: + # $ref: '#/components/schemas/AnalyzeQueryResponse' + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # '400': + # content: + # application/json: + # examples: + # invalidJSONStringValue: + # description: If the request body contains invalid JSON, returns `invalid` and problem detail. + # summary: Invalid JSON + # value: + # code: invalid + # message: 'invalid json: invalid character ''\'''' looking for beginning of value' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # InfluxDB is unable to parse the request. + # The response body contains detail about the problem. + # headers: + # X-Platform-Error-Code: + # description: | + # The reason for the error. + # schema: + # example: invalid + # type: string + # default: + # content: + # application/json: + # examples: + # emptyJSONObject: + # description: | + # If the request body contains an empty JSON object, returns `internal error`. + # summary: Empty JSON object in request body + # value: + # code: internal error + # message: An internal error has occurred - check server logs + # schema: + # $ref: '#/components/schemas/Error' + # description: Internal server error + # headers: + # X-Influx-Error: + # description: A string that describes the problem. + # schema: + # type: string + # X-Influx-Reference: + # description: The numeric reference code for the error type. + # schema: + # type: integer + # X-Platform-Error-Code: + # description: The reason for the error. + # schema: + # example: internal error + # type: string + # summary: Analyze a Flux query + # tags: + # - Query data + # /api/v2/query/ast: + # post: + # deprecated: true + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # operationId: PostQueryAst + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - in: header + # name: Content-Type + # schema: + # enum: + # - application/json + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LanguageRequest' + # description: The Flux query to analyze. + # responses: + # '200': + # content: + # schema: + # $ref: '#/components/schemas/ASTResponse' + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # '400': + # content: + # application/json: + # examples: + # invalidASTValue: + # description: | + # If the request body contains a missing property key in `from()`, + # returns `invalid` and problem detail. + # summary: Invalid AST + # value: + # code: invalid + # message: 'invalid AST: loc 1:6-1:19: missing property key' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # InfluxDB is unable to parse the request. + # The response body contains detail about the problem. + # headers: + # X-Platform-Error-Code: + # description: | + # The reason for the error. + # schema: + # example: invalid + # type: string + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Internal server error. + # summary: Generate a query Abstract Syntax Tree (AST) + # tags: + # - Query data + # /api/v2/query/suggestions: + # get: + # deprecated: true + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # operationId: GetQuerySuggestions + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # responses: + # '200': + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # '301': + # content: + # text/html: + # examples: + # movedPermanently: + # description: | + # The URL has been permanently moved. Use `/api/v2/query/suggestions`. + # summary: Invalid URL + # value: | + # Moved Permanently + # schema: + # properties: + # body: + # description: Response message with URL of requested resource. + # readOnly: true + # type: string + # description: | + # Moved Permanently. + # InfluxData has moved the URL of the endpoint. + # Use `/api/v2/query/suggestions` (without a trailing slash). + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Internal server error. + # summary: List Flux query suggestions + # tags: + # - Query data + # x-codeSamples: + # - label: cURL + # lang: Shell + # source: | + # curl --request GET "INFLUX_URL/api/v2/query/suggestions" \ + # --header "Accept: application/json" \ + # --header "Authorization: Token INFLUX_API_TOKEN" + # /api/v2/query/suggestions/{name}: + # get: + # deprecated: true + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # operationId: GetQuerySuggestionsName + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # A [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name. + # in: path + # name: name + # required: true + # schema: + # type: string + # responses: + # '200': + # description: | + # This endpoint isn't supported in InfluxDB 3 Cloud Serverless. + # See how to [query data](/influxdb3/cloud-serverless/query-data/). + # '500': + # content: + # application/json: + # examples: + # internalError: + # description: | + # The requested function doesn't exist. + # summary: Invalid function + # value: + # code: internal error + # message: An internal error has occurred + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Internal server error. + # The value passed for _`name`_ may have been misspelled. + # summary: Retrieve a query suggestion for a branching suggestion + # tags: + # - Query data + # /api/v2/resources: + # get: + # operationId: GetResources + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # responses: + # '200': + # content: + # application/json: + # schema: + # items: + # type: string + # type: array + # description: All resources targets + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Internal server error + # summary: List all known resources + # tags: + # - Resources + # - System information endpoints + # /api/v2/scripts: + # get: + # description: | + # Lists scripts. + + # + # operationId: GetScripts + # parameters: + # - description: | + # The offset for pagination. + # The number of records to skip. + + # For more information about pagination parameters, see Pagination. + # in: query + # name: offset + # required: false + # schema: + # minimum: 0 + # type: integer + # - description: | + # The maximum number of scripts to return. Default is `100`. + # in: query + # name: limit + # required: false + # schema: + # default: 100 + # maximum: 500 + # minimum: 0 + # type: integer + # - description: The script name. Lists scripts with the specified name. + # in: query + # name: name + # required: false + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # scripts: + # - createdAt: '2022-07-17T23:49:45.731237Z' + # description: find the last point from Sample Bucket + # id: 09afa3b220fe4000 + # language: flux + # name: getLastPointFromSampleBucket + # orgID: bea7ea952287f70d + # script: 'from(bucket: SampleBucket) |> range(start: -7d) |> limit(n:1)' + # updatedAt: '2022-07-17T23:49:45.731237Z' + # - createdAt: '2022-07-17T23:43:26.660308Z' + # description: getLastPoint finds the last point in a bucket + # id: 09afa23ff13e4000 + # language: flux + # name: getLastPoint + # orgID: bea7ea952287f70d + # script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' + # updatedAt: '2022-07-17T23:43:26.660308Z' + # schema: + # $ref: '#/components/schemas/Scripts' + # description: | + # Success. + # The response body contains the list of scripts. + # '400': + # content: + # application/json: + # examples: + # invalidSyntaxError: + # summary: Query parameter contains invalid syntax. + # value: + # code: 3 + # details: [] + # message: 'parsing field "limit": strconv.ParseUint: parsing "-1": invalid syntax' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # InfluxDB is unable to parse the request. + # The response body contains detail about the error. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error. + # summary: List scripts + # tags: + # - Invokable Scripts + # x-codeSamples: + # - label: 'cURL: retrieves the first 100 scripts.' + # lang: Shell + # source: | + # curl --request GET "INFLUX_URL/api/v2/scripts?limit=100&offset=0" \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --header "Accept: application/json" \ + # --header "Content-Type: application/json" + # post: + # description: | + # Creates an invokable script + # and returns the script. + + # + # operationId: PostScripts + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ScriptCreateRequest' + # description: The script to create. + # required: true + # responses: + # '201': + # content: + # application/json: + # examples: + # successResponse: + # value: + # createdAt: '2022-07-17T23:43:26.660308Z' + # description: getLastPoint finds the last point in a bucket + # id: 09afa23ff13e4000 + # language: flux + # name: getLastPoint + # orgID: bea7ea952287f70d + # script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' + # updatedAt: '2022-07-17T23:43:26.660308Z' + # schema: + # $ref: '#/components/schemas/Script' + # description: | + # Success. + # The response body contains the script and its metadata. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '422': + # content: + # application/json: + # examples: + # uniquenessError: + # description: | + # A script with the same `name` exists. + # value: + # code: conflict + # message: uniqueness violation + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Unprocessable entity. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error. + # summary: Create a script + # tags: + # - Invokable Scripts + # /api/v2/scripts/{scriptID}: + # delete: + # description: | + # Deletes a script and all associated records. + + # #### Limitations + + # - You can delete only one script per request. + # - If the script ID you provide doesn't exist for the organization, InfluxDB + # responds with an HTTP `204` status code. + + # + # operationId: DeleteScriptsID + # parameters: + # - description: | + # A script ID. + # Deletes the specified script. + # in: path + # name: scriptID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: | + # Success. + # The script is queued for deletion. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/ServerError' + # description: Unexpected error + # summary: Delete a script + # tags: + # - Invokable Scripts + # x-codeSamples: + # - label: cURL + # lang: Shell + # source: | + # curl -X 'DELETE' \ + # "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ + # --header "Authorization: Token INFLUX_TOKEN" \ + # --header 'Accept: application/json' + # get: + # description: | + # Retrieves a script. + + # + # operationId: GetScriptsID + # parameters: + # - description: | + # A script ID. + # Retrieves the specified script. + # in: path + # name: scriptID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # createdAt: '2022-07-17T23:49:45.731237Z' + # description: getLastPoint finds the last point in a bucket + # id: 09afa3b220fe4000 + # language: flux + # name: getLastPoint + # orgID: bea7ea952287f70d + # script: 'from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)' + # updatedAt: '2022-07-17T23:49:45.731237Z' + # schema: + # $ref: '#/components/schemas/Script' + # description: Success. The response body contains the script. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # content: + # application/json: + # examples: + # notFound: + # summary: | + # The requested script was not found. + # value: + # code: not found + # message: script "09afa3b220fe400" not found + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Not found. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/ServerError' + # description: Internal server error. + # summary: Retrieve a script + # tags: + # - Invokable Scripts + # patch: + # description: | + # Updates an invokable script. + + # Use this endpoint to modify values for script properties (`description` and `script`). + + # To update a script, pass an object that contains the updated key-value pairs. + + # #### Limitations + + # - If you send an empty request body, the script will neither update nor + # store an empty script, but InfluxDB will respond with an HTTP `200` status + # code. + + # + # operationId: PatchScriptsID + # parameters: + # - description: | + # A script ID. + # Updates the specified script. + # in: path + # name: scriptID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ScriptUpdateRequest' + # description: | + # An object that contains the updated script properties to apply. + # required: true + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # createdAt: '2022-07-17T23:49:45.731237Z' + # description: get last point from new bucket + # id: 09afa3b220fe4000 + # language: flux + # name: getLastPoint + # orgID: bea7ea952287f70d + # script: 'from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)' + # updatedAt: '2022-07-19T22:27:23.185436Z' + # schema: + # $ref: '#/components/schemas/Script' + # description: Success. The response body contains the updated script. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # content: + # application/json: + # examples: + # notFound: + # summary: | + # The requested script wasn't found. + # value: + # code: not found + # message: script "09afa3b220fe400" not found + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Not found. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/ServerError' + # description: Internal server error + # summary: Update a script + # tags: + # - Invokable Scripts + # x-codeSamples: + # - label: cURL + # lang: Shell + # source: | + # curl -X 'PATCH' \ + # "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ + # --header "Authorization: Token INFLUX_TOKEN" \ + # --header "Accept: application/json" + # --header "Content-Type: application/json" + # --data '{ + # "description": "get last point from new bucket", + # "script": "from(bucket: updatedBucket) |> range(start: -7d) |> limit(n:1)", "language": "flux" + # }' + # /api/v2/scripts/{scriptID}/invoke: + # post: + # description: | + # Runs a script and returns the result. + # When the script runs, InfluxDB replaces `params` keys referenced in the script with + # `params` key-values passed in the request body--for example: + + # The following sample script contains a _`mybucket`_ parameter : + + # ```json + # "script": "from(bucket: params.mybucket) + # |> range(start: -7d) + # |> limit(n:1)" + # ``` + + # The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request body + # passes a value for the _`mybucket`_ parameter: + + # ```json + # { + # "params": { + # "mybucket": "air_sensor" + # } + # } + # ``` + + # + # operationId: PostScriptsIDInvoke + # parameters: + # - description: | + # A script ID. + # Runs the specified script. + # in: path + # name: scriptID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ScriptInvocationParams' + # responses: + # '200': + # content: + # text/csv: + # examples: + # successResponse: + # value: | + # ,result,table,_start,_stop,_time,_value,_field,_measurement,host + # ,_result,0,2019-10-30T01:28:02.52716421Z,2022-07-26T01:28:02.52716421Z,2020-01-01T00:00:00Z,72.01,used_percent,mem,host2 + # schema: + # $ref: '#/components/schemas/ScriptHTTPResponseData' + # description: | + # Success. + # The response body contains the result of the script execution. + # '400': + # content: + # application/json: + # examples: + # invalidParameters: + # summary: The parameters passed to the script are invalid. + # value: + # code: invalid + # message: invalid parameters provided + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # InfluxDB is unable to parse the request. + # The response body contains detail about the error. + # headers: + # X-Platform-Error-Code: + # description: | + # The reason for the error. + # schema: + # example: invalid + # type: string + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # content: + # application/json: + # examples: + # bucketNotFound: + # description: InfluxDB can't find the requested bucket. + # summary: | + # Bucket not found + # value: + # code: not found + # message: 'failed to initialize execute state: could not find bucket "test-bucket"' + # scriptNotFound: + # description: InfluxDB can't find the requested script. + # summary: | + # Script not found + # value: + # code: not found + # message: script "09afa3b220fe400" not found + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Not found. + # headers: + # X-Platform-Error-Code: + # description: | + # The reason for the error. + # schema: + # example: not found + # type: string + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error. + # summary: Invoke a script + # tags: + # - Invokable Scripts + # /api/v2/scripts/{scriptID}/params: + # get: + # description: | + # Analyzes a script and determines required parameters. + # Find all `params` keys referenced in a script and return a list + # of keys. If it is possible to determine the type of the value + # from the context then the type is also returned -- for example: + + # The following sample script contains a _`mybucket`_ parameter : + + # ```json + # "script": "from(bucket: params.mybucket) + # |> range(start: -7d) + # |> limit(n:1)" + # ``` + + # Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params` + # returns the following: + + # ```json + # { + # "params": { + # "mybucket": "string" + # } + # } + # ``` + + # The type name returned for a parameter will be one of: + + # - `any` + # - `bool` + # - `duration` + # - `float` + # - `int` + # - `string` + # - `time` + # - `uint` + + # The type name `any` is used when the type of a parameter cannot + # be determined from the context, or the type is determined to + # be a structured type such as an array or record. + + # + # operationId: GetScriptsIDParams + # parameters: + # - description: | + # A script ID. + # The script to analyze for params. + # in: path + # name: scriptID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # successResponse: + # value: + # params: + # mybucket: string + # schema: + # $ref: '#/components/schemas/Params' + # description: | + # Success. + # The response body contains the parameters found, along with their types. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # content: + # application/json: + # examples: + # scriptNotFound: + # description: InfluxDB can't find the requested script. + # summary: | + # Script not found + # value: + # code: not found + # message: script "09afa3b220fe400" not found + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Not found. + # headers: + # X-Platform-Error-Code: + # description: | + # The reason for the error. + # schema: + # example: not found + # type: string + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error. + # summary: Find script parameters. + # tags: + # - Invokable Scripts + # x-codeSamples: + # - label: cURL + # lang: Shell + # source: | + # curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \ + # --header "Authorization: Token INFLUX_TOKEN" + # /api/v2/setup: {} + # /api/v2/setup/user: {} + # /api/v2/signin: {} + # /api/v2/signout: {} + # /api/v2/stacks: + # get: + # description: | + # Lists installed InfluxDB stacks. + + # To limit stacks in the response, pass query parameters in your request. + # If no query parameters are passed, InfluxDB returns all installed stacks + # for the organization. + + # + # operationId: ListStacks + # parameters: + # - description: | + # An organization ID. + # Only returns stacks owned by the specified [organization](/influxdb3/cloud-serverless/reference/glossary/#organization). + + # #### InfluxDB Cloud + + # - Doesn't require this parameter; + # InfluxDB only returns resources allowed by the API token. + # in: query + # name: orgID + # required: true + # schema: + # type: string + # - description: | + # A stack name. + # Finds stack `events` with this name and returns the stacks. + + # Repeatable. + # To filter for more than one stack name, + # repeat this parameter with each name--for example: + + # - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` + # examples: + # findStackByName: + # summary: Find stacks with the event name + # value: project-stack-0 + # in: query + # name: name + # schema: + # type: string + # - description: | + # A stack ID. + # Only returns the specified stack. + + # Repeatable. + # To filter for more than one stack ID, + # repeat this parameter with each ID--for example: + + # - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` + # examples: + # findStackByID: + # summary: Find a stack with the ID + # value: 09bd87cd33be3000 + # in: query + # name: stackID + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # properties: + # stacks: + # items: + # $ref: '#/components/schemas/Stack' + # type: array + # type: object + # description: Success. The response body contains the list of stacks. + # '400': + # content: + # application/json: + # examples: + # orgIdMissing: + # summary: The orgID query parameter is missing + # value: + # code: invalid + # message: 'organization id[""] is invalid: id must have a length of 16 bytes' + # orgProvidedNotFound: + # summary: The org or orgID passed doesn't own the token passed in the header + # value: + # code: invalid + # message: 'failed to decode request body: organization not found' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # The response body contains detail about the error. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List installed stacks + # tags: + # - Templates + # post: + # description: | + # Creates or initializes a stack. + + # Use this endpoint to _manually_ initialize a new stack with the following + # optional information: + + # - Stack name + # - Stack description + # - URLs for template manifest files + + # To automatically create a stack when applying templates, + # use the /api/v2/templates/apply endpoint. + + # #### Required permissions + + # - `write` permission for the organization + + # + # operationId: CreateStack + # requestBody: + # content: + # application/json: + # schema: + # properties: + # description: + # type: string + # name: + # type: string + # orgID: + # type: string + # urls: + # items: + # type: string + # type: array + # title: PostStackRequest + # type: object + # description: The stack to create. + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Stack' + # description: Success. Returns the newly created stack. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '422': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Unprocessable entity. + + # The error may indicate one of the following problems: + + # - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. + # - You passed a parameter combination that InfluxDB doesn't support. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Create a stack + # tags: + # - Templates + # /api/v2/stacks/{stack_id}: + # delete: + # operationId: DeleteStack + # parameters: + # - description: The identifier of the stack. + # in: path + # name: stack_id + # required: true + # schema: + # type: string + # - description: The identifier of the organization. + # in: query + # name: orgID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: The stack and its associated resources were deleted. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Delete a stack and associated resources + # tags: + # - Templates + # get: + # operationId: ReadStack + # parameters: + # - description: The identifier of the stack. + # in: path + # name: stack_id + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Stack' + # description: Returns the stack. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Retrieve a stack + # tags: + # - Templates + # patch: + # operationId: UpdateStack + # parameters: + # - description: The identifier of the stack. + # in: path + # name: stack_id + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # properties: + # additionalResources: + # items: + # properties: + # kind: + # type: string + # resourceID: + # type: string + # templateMetaName: + # type: string + # required: + # - kind + # - resourceID + # type: object + # type: array + # description: + # nullable: true + # type: string + # name: + # nullable: true + # type: string + # templateURLs: + # items: + # type: string + # nullable: true + # type: array + # title: PatchStackRequest + # type: object + # description: The stack to update. + # required: true + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Stack' + # description: Returns the updated stack. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Update a stack + # tags: + # - Templates + # /api/v2/stacks/{stack_id}/uninstall: + # post: + # operationId: UninstallStack + # parameters: + # - description: The identifier of the stack. + # in: path + # name: stack_id + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Stack' + # description: Returns the uninstalled stack. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Uninstall a stack + # tags: + # - Templates + # /api/v2/tasks: + # get: + # description: | + # Retrieves a list of [tasks](/influxdb3/cloud-serverless/reference/glossary/#task). + + # To limit which tasks are returned, pass query parameters in your request. + # If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. + # operationId: GetTasks + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) name. + # Only returns tasks with the specified name. + # Different tasks may have the same name. + # in: query + # name: name + # schema: + # type: string + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. + # Only returns tasks created after the specified task. + # in: query + # name: after + # schema: + # type: string + # - description: | + # A [user](/influxdb3/cloud-serverless/reference/glossary/#user) ID. + # Only returns tasks owned by the specified user. + # in: query + # name: user + # schema: + # type: string + # - description: | + # An [organization](/influxdb3/cloud-serverless/reference/glossary/#organization) name. + # Only returns tasks owned by the specified organization. + # in: query + # name: org + # schema: + # type: string + # - description: | + # An [organization](/influxdb3/cloud-serverless/reference/glossary/#organization) ID. + # Only returns tasks owned by the specified organization. + # in: query + # name: orgID + # schema: + # type: string + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) status. + # Only returns tasks that have the specified status (`active` or `inactive`). + # in: query + # name: status + # schema: + # enum: + # - active + # - inactive + # type: string + # - description: | + # The maximum number of [tasks](/influxdb3/cloud-serverless/reference/glossary/#task) to return. + # Default is `100`. + # The minimum is `1` and the maximum is `500`. + + # To reduce the payload size, combine _`type=basic`_ and _`limit`_ (see _Request samples_). + # For more information about the `basic` response, see the _`type`_ parameter. + # examples: + # all: + # summary: Return all tasks, without pagination. + # value: '-1' + # minPaginated: + # summary: Return a maximum of 50 tasks. + # value: '50' + # in: query + # name: limit + # schema: + # default: 100 + # maximum: 500 + # minimum: -1 + # type: integer + # - description: The number of records to skip. + # in: query + # name: offset + # required: false + # schema: + # default: 0 + # minimum: 0 + # type: integer + # - description: | + # The sort field. Only `name` is supported. + # Specifies the field used to sort records in the list. + # in: query + # name: sortBy + # required: false + # schema: + # enum: + # - name + # type: string + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) type (`basic` or `system`). + # Default is `system`. + # Specifies the level of detail for tasks in the response. + # The default (`system`) response contains all the metadata properties for tasks. + # To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). + # in: query + # name: type + # required: false + # schema: + # default: '' + # enum: + # - basic + # - system + # type: string + # - description: | + # A script ID. + # Only returns tasks that use the specified invokable script. + # in: query + # name: scriptID + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # basicTypeTaskOutput: + # description: | + # A sample response body for the `?type=basic` parameter. + # `type=basic` omits some task fields (`createdAt` and `updatedAt`) + # and field values (`org`, `flux`) in the response. + # summary: Basic output + # value: + # links: + # self: /api/v2/tasks?limit=100 + # tasks: + # - every: 30m + # flux: '' + # id: 09956cbb6d378000 + # labels: [] + # lastRunStatus: success + # latestCompleted: '2022-06-30T15:00:00Z' + # links: + # labels: /api/v2/tasks/09956cbb6d378000/labels + # logs: /api/v2/tasks/09956cbb6d378000/logs + # members: /api/v2/tasks/09956cbb6d378000/members + # owners: /api/v2/tasks/09956cbb6d378000/owners + # runs: /api/v2/tasks/09956cbb6d378000/runs + # self: /api/v2/tasks/09956cbb6d378000 + # name: task1 + # org: '' + # orgID: 48c88459ee424a04 + # ownerID: 0772396d1f411000 + # status: active + # systemTypeTaskOutput: + # description: | + # A sample response body for the `?type=system` parameter. + # `type=system` returns all task fields. + # summary: System output + # value: + # links: + # self: /api/v2/tasks?limit=100 + # tasks: + # - createdAt: '2022-06-27T15:09:06Z' + # description: IoT Center 90-day environment average. + # every: 30m + # flux: |- + # option task = {name: "task1", every: 30m} + + # from(bucket: "iot_center") + # |> range(start: -90d) + # |> filter(fn: (r) => r._measurement == "environment") + # |> aggregateWindow(every: 1h, fn: mean) + # id: 09956cbb6d378000 + # labels: [] + # lastRunStatus: success + # latestCompleted: '2022-06-30T15:00:00Z' + # links: + # labels: /api/v2/tasks/09956cbb6d378000/labels + # logs: /api/v2/tasks/09956cbb6d378000/logs + # members: /api/v2/tasks/09956cbb6d378000/members + # owners: /api/v2/tasks/09956cbb6d378000/owners + # runs: /api/v2/tasks/09956cbb6d378000/runs + # self: /api/v2/tasks/09956cbb6d378000 + # name: task1 + # org: my-iot-center + # orgID: 48c88459ee424a04 + # ownerID: 0772396d1f411000 + # status: active + # updatedAt: '2022-06-28T18:10:15Z' + # schema: + # $ref: '#/components/schemas/Tasks' + # description: | + # Success. + # The response body contains the list of tasks. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: List all tasks + # tags: + # - Tasks + # x-codeSamples: + # - label: 'cURL: all tasks, basic output' + # lang: Shell + # source: | + # curl INFLUX_URL/api/v2/tasks/?limit=-1&type=basic \ + # --header 'Content-Type: application/json' \ + # --header 'Authorization: Token INFLUX_API_TOKEN' + # post: + # description: | + # Creates a [task](/influxdb3/cloud-serverless/reference/glossary/#task) and returns the task. + + # Use this endpoint to create a scheduled task that runs a Flux script. + + # #### InfluxDB Cloud + + # - You can use either `flux` or `scriptID` to provide the task script. + + # - `flux`: a string of "raw" Flux that contains task options and the script--for example: + + # ```json + # { + # "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + # from(bucket: \"telegraf\") + # |> range(start: -1h) + # |> filter(fn: (r) => (r._measurement == \"cpu\")) + # |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + # |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + # |> aggregateWindow(every: 1h, fn: max) + # |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + # "status": "active", + # "description": "This task downsamples CPU data every hour" + # } + # ``` + + # - `scriptID`: the ID of an invokable script + # for the task to run. + # To pass task options when using `scriptID`, pass the options as + # properties in the request body--for example: + + # ```json + # { + # "name": "CPU Total 1 Hour New", + # "description": "This task downsamples CPU data every hour", + # "every": "1h", + # "scriptID": "SCRIPT_ID", + # "scriptParameters": + # { + # "rangeStart": "-1h", + # "bucket": "telegraf", + # "filterField": "cpu-total" + # } + # } + # ``` + + # #### Limitations: + + # - You can't use `flux` and `scriptID` for the same task. + + # + # operationId: PostTasks + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/TaskCreateRequest' + # description: The task to create + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Task' + # description: Success. The response body contains a `tasks` list with the new task. + # '400': + # content: + # application/json: + # examples: + # fluxAndScriptError: + # summary: The request body can't contain both flux and scriptID + # value: + # code: invalid + # message: 'failed to decode request: can not provide both scriptID and flux' + # missingFluxError: + # summary: The request body requires either a flux parameter or scriptID parameter + # value: + # code: invalid + # message: 'failed to decode request: flux required' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # The response body contains detail about the error. + + # #### InfluxDB Cloud + + # - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_. + # - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Create a task + # tags: + # - Tasks + # x-codeSamples: + # - label: 'cURL: create a Flux script task' + # lang: Shell + # source: | + # curl INFLUX_URL/api/v2/tasks \ + # --header "Content-type: application/json" \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --data-binary @- << EOF + # { + # "orgID": "INFLUX_ORG_ID", + # "description": "IoT Center 30d environment average.", + # "flux": "option task = {name: \"iot-center-task-1\", every: 30m}\ + # from(bucket: \"iot_center\")\ + # |> range(start: -30d)\ + # |> filter(fn: (r) => r._measurement == \"environment\")\ + # |> aggregateWindow(every: 1h, fn: mean)" + # } + # EOF + # - label: 'cURL: create a Flux script reference task' + # lang: Shell + # source: | + # curl INFLUX_URL/api/v2/tasks \ + # --header "Content-type: application/json" \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --data-binary @- << EOF + # { + # "orgID": "INFLUX_ORG_ID", + # "description": "IoT Center 30d environment average.", + # "scriptID": "085138a111448000", + # "scriptParameters": + # { + # "rangeStart": "-30d", + # "bucket": "air_sensor", + # "filterField": "temperature", + # "groupColumn": "_time" + # } + # } + # EOF + # /api/v2/tasks/{taskID}: + # delete: + # description: | + # Deletes a [task](/influxdb3/cloud-serverless/reference/glossary/#task) and associated records. + + # Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + # Once the task is deleted, InfluxDB cancels all scheduled runs of the task. + + # If you want to disable a task instead of delete it, update the task status to `inactive`. + # operationId: DeleteTasksID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. Specifies the task to delete. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Success. The task and task runs are deleted. Scheduled runs are canceled. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Delete a task + # tags: + # - Tasks + # get: + # description: | + # Retrieves a [task](/influxdb3/cloud-serverless/reference/glossary/#task). + # operationId: GetTasksID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. + # Specifies the task to retrieve. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Task' + # description: Success. The response body contains the task. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Retrieve a task + # tags: + # - Tasks + # patch: + # description: | + # Updates a [task](/influxdb3/cloud-serverless/reference/glossary/#task), + # and then cancels all scheduled runs of the task. + + # Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. + # Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. + + # To update a task, pass an object that contains the updated key-value pairs. + # To activate or inactivate a task, set the `status` property. + # _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. + + # #### InfluxDB Cloud + + # - Use either `flux` or `scriptID` to provide the task script. + + # - `flux`: a string of "raw" Flux that contains task options and the script--for example: + + # ```json + # { + # "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + # from(bucket: \"telegraf\") + # |> range(start: -1h) + # |> filter(fn: (r) => (r._measurement == \"cpu\")) + # |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + # |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + # |> aggregateWindow(every: 1h, fn: max) + # |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + # "status": "active", + # "description": "This task downsamples CPU data every hour" + # } + # ``` + + # - `scriptID`: the ID of an invokable script + # for the task to run. + # To pass task options when using `scriptID`, pass the options as + # properties in the request body--for example: + + # ```json + # { + # "name": "CPU Total 1 Hour New", + # "description": "This task downsamples CPU data every hour", + # "every": "1h", + # "scriptID": "SCRIPT_ID", + # "scriptParameters": + # { + # "rangeStart": "-1h", + # "bucket": "telegraf", + # "filterField": "cpu-total" + # } + # } + # ``` + + # #### Limitations: + + # - You can't use `flux` and `scriptID` for the same task. + # operationId: PatchTasksID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. + # Specifies the task to update. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/TaskUpdateRequest' + # description: An task update to apply. + # required: true + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Task' + # description: Success. The response body contains the updated task. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Update a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/labels: + # get: + # description: | + # Retrieves a list of all labels for a task. + + # Labels may be used for grouping and filtering tasks. + # operationId: GetTasksIDLabels + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to retrieve labels for. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelsResponse' + # description: Success. The response body contains a list of all labels for the task. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: List labels for a task + # tags: + # - Tasks + # post: + # description: | + # Adds a label to a task. + + # Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + # operationId: PostTasksIDLabels + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to label. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelMapping' + # description: An object that contains a _`labelID`_ to add to the task. + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelResponse' + # description: Success. The response body contains a list of all labels for the task. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Add a label to a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/labels/{labelID}: + # delete: + # description: | + # Deletes a label from a task. + # operationId: DeleteTasksIDLabelsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to delete the label from. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # - description: The ID of the label to delete. + # in: path + # name: labelID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Success. The label is deleted. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Delete a label from a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/logs: + # get: + # description: | + # Retrieves a list of all logs for a [task](/influxdb3/cloud-serverless/reference/glossary/#task). + + # When an InfluxDB task runs, a “run” record is created in the task’s history. + # Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. + + # Use this endpoint to retrieve only the log events for a task, + # without additional task metadata. + # operationId: GetTasksIDLogs + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The task ID. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # taskFailure: + # summary: Events for a failed task run. + # value: + # events: + # - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' + # runID: 09a946fc3167d000 + # time: '2022-07-13T07:06:54.198167Z' + # - message: Completed(failed) + # runID: 09a946fc3167d000 + # time: '2022-07-13T07:07:13.104037Z' + # - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' + # runID: 09a946fc3167d000 + # time: '2022-07-13T08:24:37.115323Z' + # taskSuccess: + # summary: Events for a successful task run. + # value: + # events: + # - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' + # runID: 09b070dadaa7d000 + # time: '2022-07-18T14:46:07.101231Z' + # - message: Completed(success) + # runID: 09b070dadaa7d000 + # time: '2022-07-18T14:46:07.242859Z' + # schema: + # $ref: '#/components/schemas/Logs' + # description: | + # Success. The response body contains an `events` list with logs for the task. + # Each log event `message` contains detail about the event. + # If a task run fails, InfluxDB logs an event with the reason for the failure. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Retrieve all logs for a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/members: + # get: + # deprecated: true + # description: | + # **Deprecated**: Tasks don't use `owner` and `member` roles. + # Use `/api/v2/authorizations` to assign user permissions. + + # Lists all users that have the `member` role for the specified [task](/influxdb3/cloud-serverless/reference/glossary/#task). + # operationId: GetTasksIDMembers + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The task ID. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceMembers' + # description: | + # Success. The response body contains a list of `users` that have + # the `member` role for a task. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all task members + # tags: + # - Tasks + # post: + # deprecated: true + # description: | + # **Deprecated**: Tasks don't use `owner` and `member` roles. + # Use `/api/v2/authorizations` to assign user permissions. + + # Adds a user to members of a task and returns the member. + # operationId: PostTasksIDMembers + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The task ID. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/AddResourceMemberRequestBody' + # description: A user to add as a member of the task. + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceMember' + # description: Created. The user is added to task members. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add a member to a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/members/{userID}: + # delete: + # deprecated: true + # description: | + # **Deprecated**: Tasks don't use `owner` and `member` roles. + # Use `/api/v2/authorizations` to assign user permissions. + + # Removes a member from a [task](/influxdb3/cloud-serverless/reference/glossary/#task). + # operationId: DeleteTasksIDMembersID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the member to remove. + # in: path + # name: userID + # required: true + # schema: + # type: string + # - description: The task ID. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Member removed + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Remove a member from a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/owners: + # get: + # deprecated: true + # description: | + # **Deprecated**: Tasks don't use `owner` and `member` roles. + # Use `/api/v2/authorizations` to assign user permissions. + + # Retrieves all users that have owner permission for a task. + # operationId: GetTasksIDOwners + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to retrieve owners for. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceOwners' + # description: | + # Success. + # The response contains a list of `users` that have the `owner` role for the task. + + # If the task has no owners, the response contains an empty `users` array. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '422': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Unprocessable entity. + + # The error may indicate one of the following problems: + + # - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. + # - You passed a parameter combination that InfluxDB doesn't support. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all owners of a task + # tags: + # - Tasks + # post: + # deprecated: true + # description: | + # **Deprecated**: Tasks don't use `owner` and `member` roles. + # Use `/api/v2/authorizations` to assign user permissions. + + # Assigns a task `owner` role to a user. + + # Use this endpoint to create a _resource owner_ for the task. + # A _resource owner_ is a user with `role: owner` for a specific resource. + # operationId: PostTasksIDOwners + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The task ID. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/AddResourceMemberRequestBody' + # description: A user to add as an owner of the task. + # required: true + # responses: + # '201': + # content: + # application/json: + # examples: + # createdOwner: + # summary: User has the owner role for the resource + # value: + # id: 0772396d1f411000 + # links: + # logs: /api/v2/users/0772396d1f411000/logs + # self: /api/v2/users/0772396d1f411000 + # name: USER_NAME + # role: owner + # status: active + # schema: + # $ref: '#/components/schemas/ResourceOwner' + # description: | + # Created. The task `owner` role is assigned to the user. + # The response body contains the resource owner with + # role and user detail. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '422': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Unprocessable entity. + + # The error may indicate one of the following problems: + + # - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. + # - You passed a parameter combination that InfluxDB doesn't support. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add an owner for a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/owners/{userID}: + # delete: + # deprecated: true + # description: | + # **Deprecated**: Tasks don't use `owner` and `member` roles. + # Use `/api/v2/authorizations` to assign user permissions. + # operationId: DeleteTasksIDOwnersID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the owner to remove. + # in: path + # name: userID + # required: true + # schema: + # type: string + # - description: The task ID. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Owner removed + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Remove an owner from a task + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/runs: + # get: + # description: | + # Retrieves a list of runs for a task. + + # To limit which task runs are returned, pass query parameters in your request. + # If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. + # + # operationId: GetTasksIDRuns + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # The ID of the task to get runs for. + # Only returns runs for this task. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # - description: A task run ID. Only returns runs created after this run. + # in: query + # name: after + # schema: + # type: string + # - description: | + # Limits the number of task runs returned. Default is `100`. + # in: query + # name: limit + # schema: + # default: 100 + # maximum: 500 + # minimum: 1 + # type: integer + # - description: | + # A timestamp ([RFC3339 date/time format](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp)). + # Only returns runs scheduled after this time. + # in: query + # name: afterTime + # schema: + # format: date-time + # type: string + # - description: | + # A timestamp ([RFC3339 date/time format](/influxdb3/cloud-serverless/reference/glossary/#rfc3339-timestamp)). + # Only returns runs scheduled before this time. + # in: query + # name: beforeTime + # schema: + # format: date-time + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Runs' + # description: Success. The response body contains the list of task runs. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: List runs for a task + # tags: + # - Tasks + # post: + # description: | + # Schedules a task run to start immediately, ignoring scheduled runs. + + # Use this endpoint to manually start a task run. + # Scheduled runs will continue to run as scheduled. + # This may result in concurrently running tasks. + + # To _retry_ a previous run (and avoid creating a new run), + # use the `POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint. + # + # operationId: PostTasksIDRuns + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - in: path + # name: taskID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/RunManually' + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Run' + # description: Success. The run is scheduled to start. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Start a task run, overriding the schedule + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/runs/{runID}: + # delete: + # description: | + # Cancels a running [task](/influxdb3/cloud-serverless/reference/glossary/#task). + + # Use this endpoint with InfluxDB OSS to cancel a running task. + + # #### InfluxDB Cloud + + # - Doesn't support this operation. + # + # operationId: DeleteTasksIDRunsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to cancel. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # - description: The ID of the task run to cancel. + # in: path + # name: runID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: | + # Success. The `DELETE` is accepted and the run will be cancelled. + + # #### InfluxDB Cloud + + # - Doesn't support this operation. + # - Doesn't return this status. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '405': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Method not allowed. + + # #### InfluxDB Cloud + + # - Always returns this error; doesn't support cancelling tasks. + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Cancel a running task + # tags: + # - Tasks + # get: + # description: | + # Retrieves a specific run for a task. + + # Use this endpoint to retrieve detail and logs for a specific task run. + # + # operationId: GetTasksIDRunsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to retrieve runs for. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # - description: The ID of the run to retrieve. + # in: path + # name: runID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # runSuccess: + # summary: A successful task run. + # value: + # finishedAt: '2022-07-18T14:46:07.308254Z' + # id: 09b070dadaa7d000 + # links: + # logs: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs + # retry: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry + # self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 + # task: /api/v2/tasks/0996e56b2f378000 + # log: + # - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' + # runID: 09b070dadaa7d000 + # time: '2022-07-18T14:46:07.101231Z' + # - message: Completed(success) + # runID: 09b070dadaa7d000 + # time: '2022-07-18T14:46:07.242859Z' + # requestedAt: '2022-07-18T14:46:06Z' + # scheduledFor: '2022-07-18T14:46:06Z' + # startedAt: '2022-07-18T14:46:07.16222Z' + # status: success + # taskID: 0996e56b2f378000 + # schema: + # $ref: '#/components/schemas/Run' + # description: Success. The response body contains the task run. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Retrieve a run for a task. + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/runs/{runID}/logs: + # get: + # description: | + # Retrieves all logs for a task run. + # A log is a list of run events with `runID`, `time`, and `message` properties. + + # Use this endpoint to help analyze task performance and troubleshoot failed task runs. + # + # operationId: GetTasksIDRunsIDLogs + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the task to get logs for. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # - description: The ID of the run to get logs for. + # in: path + # name: runID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # examples: + # taskFailure: + # summary: Events for a failed task. + # value: + # events: + # - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' + # runID: 09a946fc3167d000 + # time: '2022-07-13T07:06:54.198167Z' + # - message: Completed(failed) + # runID: 09a946fc3167d000 + # time: '2022-07-13T07:07:13.104037Z' + # - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' + # runID: 09a946fc3167d000 + # time: '2022-07-13T08:24:37.115323Z' + # taskSuccess: + # summary: Events for a successful task run. + # value: + # events: + # - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' + # runID: 09b070dadaa7d000 + # time: '2022-07-18T14:46:07.101231Z' + # - message: Completed(success) + # runID: 09b070dadaa7d000 + # time: '2022-07-18T14:46:07.242859Z' + # schema: + # $ref: '#/components/schemas/Logs' + # description: | + # Success. The response body contains an `events` list with logs for the task run. + # Each log event `message` contains detail about the event. + # If a run fails, InfluxDB logs an event with the reason for the failure. + # '400': + # $ref: '#/components/responses/BadRequestError' + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Retrieve all logs for a run + # tags: + # - Tasks + # /api/v2/tasks/{taskID}/runs/{runID}/retry: + # post: + # description: | + # Queues a task run to + # retry and returns the scheduled run. + + # To manually start a _new_ task run, use the + # `POST /api/v2/tasks/{taskID}/runs` endpoint. + + # #### Limitations + + # - The task must be _active_ (`status: "active"`). + # operationId: PostTasksIDRunsIDRetry + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) ID. + # Specifies the task to retry. + # in: path + # name: taskID + # required: true + # schema: + # type: string + # - description: | + # A [task](/influxdb3/cloud-serverless/reference/glossary/#task) run ID. + # Specifies the task run to retry. + + # To find a task run ID, use the + # `GET /api/v2/tasks/{taskID}/runs` endpoint + # to list task runs. + # in: path + # name: runID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json; charset=utf-8: + # schema: + # type: object + # responses: + # '200': + # content: + # application/json: + # examples: + # retryTaskRun: + # summary: A task run scheduled to retry + # value: + # id: 09d60ffe08738000 + # links: + # logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs + # retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry + # self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 + # task: /api/v2/tasks/09a776832f381000 + # requestedAt: '2022-08-16T20:05:11.84145Z' + # scheduledFor: '2022-08-15T00:00:00Z' + # status: scheduled + # taskID: 09a776832f381000 + # schema: + # $ref: '#/components/schemas/Run' + # description: Success. The response body contains the queued run. + # '400': + # content: + # application/json: + # examples: + # inactiveTask: + # summary: Can't retry an inactive task + # value: + # code: invalid + # message: 'failed to retry run: inactive task' + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Bad request. + # The response body contains detail about the error. + + # InfluxDB may return this error for the following reasons: + + # - The task has `status: inactive`. + # '401': + # $ref: '#/components/responses/AuthorizationError' + # '404': + # $ref: '#/components/responses/ResourceNotFoundError' + # '500': + # $ref: '#/components/responses/InternalServerError' + # default: + # $ref: '#/components/responses/GeneralServerError' + # summary: Retry a task run + # tags: + # - Tasks + # /api/v2/telegraf/plugins: {} + # /api/v2/telegrafs: + # get: + # operationId: GetTelegrafs + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The organization ID the Telegraf config belongs to. + # in: query + # name: orgID + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Telegrafs' + # description: A list of Telegraf configurations + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all Telegraf configurations + # tags: + # - Telegrafs + # post: + # operationId: PostTelegrafs + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/TelegrafPluginRequest' + # description: Telegraf configuration to create + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Telegraf' + # description: Telegraf configuration created + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Create a Telegraf configuration + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}: + # delete: + # operationId: DeleteTelegrafsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf configuration ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Delete has been accepted + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Delete a Telegraf configuration + # tags: + # - Telegrafs + # get: + # operationId: GetTelegrafsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf configuration ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # - in: header + # name: Accept + # required: false + # schema: + # default: application/toml + # enum: + # - application/toml + # - application/json + # - application/octet-stream + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Telegraf' + # application/octet-stream: + # example: |- + # [agent] + # interval = "10s" + # schema: + # type: string + # application/toml: + # example: |- + # [agent] + # interval = "10s" + # schema: + # type: string + # description: Telegraf configuration details + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Retrieve a Telegraf configuration + # tags: + # - Telegrafs + # put: + # operationId: PutTelegrafsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/TelegrafPluginRequest' + # description: Telegraf configuration update to apply + # required: true + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Telegraf' + # description: An updated Telegraf configurations + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Update a Telegraf configuration + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}/labels: + # get: + # operationId: GetTelegrafsIDLabels + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelsResponse' + # description: A list of all labels for a Telegraf config + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all labels for a Telegraf config + # tags: + # - Telegrafs + # post: + # operationId: PostTelegrafsIDLabels + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelMapping' + # description: Label to add + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelResponse' + # description: The label added to the Telegraf config + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add a label to a Telegraf config + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}/labels/{labelID}: + # delete: + # operationId: DeleteTelegrafsIDLabelsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # - description: The label ID. + # in: path + # name: labelID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Delete has been accepted + # '404': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Telegraf config not found + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Delete a label from a Telegraf config + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}/members: + # get: + # operationId: GetTelegrafsIDMembers + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceMembers' + # description: A list of Telegraf config members + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all users with member privileges for a Telegraf config + # tags: + # - Telegrafs + # post: + # operationId: PostTelegrafsIDMembers + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/AddResourceMemberRequestBody' + # description: User to add as member + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceMember' + # description: Member added to Telegraf config + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add a member to a Telegraf config + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}/members/{userID}: + # delete: + # operationId: DeleteTelegrafsIDMembersID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the member to remove. + # in: path + # name: userID + # required: true + # schema: + # type: string + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Member removed + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Remove a member from a Telegraf config + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}/owners: + # get: + # operationId: GetTelegrafsIDOwners + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf configuration ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceOwners' + # description: Returns Telegraf configuration owners as a ResourceOwners list + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all owners of a Telegraf configuration + # tags: + # - Telegrafs + # post: + # operationId: PostTelegrafsIDOwners + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The Telegraf configuration ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/AddResourceMemberRequestBody' + # description: User to add as owner + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/ResourceOwner' + # description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add an owner to a Telegraf configuration + # tags: + # - Telegrafs + # /api/v2/telegrafs/{telegrafID}/owners/{userID}: + # delete: + # operationId: DeleteTelegrafsIDOwnersID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The ID of the owner to remove. + # in: path + # name: userID + # required: true + # schema: + # type: string + # - description: The Telegraf config ID. + # in: path + # name: telegrafID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Owner removed + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Remove an owner from a Telegraf config + # tags: + # - Telegrafs + # /api/v2/templates/apply: + # post: + # description: | + # Applies a template to + # create or update a stack of InfluxDB + # resources. + # The response contains the diff of changes and the stack ID. + + # Use this endpoint to install an InfluxDB template to an organization. + # Provide template URLs or template objects in your request. + # To customize which template resources are installed, use the `actions` + # parameter. + + # By default, when you apply a template, InfluxDB installs the template to + # create and update stack resources and then generates a diff of the changes. + # If you pass `dryRun: true` in the request body, InfluxDB validates the + # template and generates the resource diff, but doesn’t make any + # changes to your instance. + + # #### Custom values for templates + + # - Some templates may contain environment references for custom metadata. + # To provide custom values for environment references, pass the _`envRefs`_ + # property in the request body. + + # - Some templates may contain queries that use + # [secrets](/influxdb3/cloud-serverless/reference/glossary/#secret). + # To provide custom secret values, pass the _`secrets`_ property + # in the request body. + # Don't expose secret values in templates. + + # #### Required permissions + + # - `write` permissions for resource types in the template. + + # #### Rate limits (with InfluxDB Cloud) + + # - Adjustable service quotas apply. + # For more information, see [limits and adjustable quotas](/influxdb3/cloud-serverless/account-management/limits/). + + # + # operationId: ApplyTemplate + # requestBody: + # content: + # application/json: + # examples: + # skipKindAction: + # summary: Skip all bucket and task resources in the provided templates + # value: + # actions: + # - action: skipKind + # properties: + # kind: Bucket + # - action: skipKind + # properties: + # kind: Task + # orgID: INFLUX_ORG_ID + # templates: + # - contents: + # - '[object Object]': null + # skipResourceAction: + # summary: Skip specific resources in the provided templates + # value: + # actions: + # - action: skipResource + # properties: + # kind: Label + # resourceTemplateName: foo-001 + # - action: skipResource + # properties: + # kind: Bucket + # resourceTemplateName: bar-020 + # - action: skipResource + # properties: + # kind: Bucket + # resourceTemplateName: baz-500 + # orgID: INFLUX_ORG_ID + # templates: + # - contents: + # - apiVersion: influxdata.com/v2alpha1 + # kind: Bucket + # metadata: + # name: baz-500 + # templateObjectEnvRefs: + # summary: envRefs for template objects + # value: + # envRefs: + # docker-bucket: MY_DOCKER_BUCKET + # docker-spec-1: MY_DOCKER_SPEC + # linux-cpu-label: MY_CPU_LABEL + # orgID: INFLUX_ORG_ID + # templates: + # - contents: + # - apiVersion: influxdata.com/v2alpha1 + # kind: Label + # metadata: + # name: + # envRef: + # key: linux-cpu-label + # spec: + # color: '#326BBA' + # name: inputs.cpu + # - contents: + # - apiVersion: influxdata.com/v2alpha1 + # kind: Bucket + # metadata: + # name: + # envRef: + # key: docker-bucket + # schema: + # $ref: '#/components/schemas/TemplateApply' + # application/x-jsonnet: + # schema: + # $ref: '#/components/schemas/TemplateApply' + # text/yml: + # schema: + # $ref: '#/components/schemas/TemplateApply' + # description: | + # Parameters for applying templates. + # required: true + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/TemplateSummary' + # description: | + # Success. + # The template dry run succeeded. + # The response body contains a resource diff of changes that the + # template would have made if installed. + # No resources were created or updated. + # The diff and summary won't contain IDs for resources + # that didn't exist at the time of the dry run. + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/TemplateSummary' + # description: | + # Success. + # The template applied successfully. + # The response body contains the stack ID, a diff, and a summary. + # The diff compares the initial state to the state after the template installation. + # The summary contains newly created resources. + # '422': + # content: + # application/json: + # schema: + # allOf: + # - $ref: '#/components/schemas/TemplateSummary' + # - properties: + # code: + # type: string + # message: + # type: string + # required: + # - message + # - code + # type: object + # description: | + # Unprocessable entity. + + + # The error may indicate one of the following problems: + + # - The template failed validation. + # - You passed a parameter combination that InfluxDB doesn't support. + # '500': + # content: + # application/json: + # examples: + # createExceedsQuota: + # summary: 'InfluxDB Cloud: Creating resource would exceed quota.' + # value: + # code: internal error + # message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\"" + # schema: + # $ref: '#/components/schemas/Error' + # description: | + # Internal server error. + + # #### InfluxDB Cloud + + # - Returns this error if creating one of the template + # resources (bucket, dashboard, task, user) exceeds your plan’s + # adjustable service quotas. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Apply or dry-run a template + # tags: + # - Templates + # x-codeSamples: + # - label: 'cURL: Dry run with a remote template' + # lang: Shell + # source: | + # curl --request POST "http://localhost:8086/api/v2/templates/apply" \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --data @- << EOF + # { + # "dryRun": true, + # "orgID": "INFLUX_ORG_ID", + # "remotes": [ + # { + # "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml" + # } + # ] + # } + # EOF + # - label: 'cURL: Apply with secret values' + # lang: Shell + # source: | + # curl "http://localhost:8086/api/v2/templates/apply" \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --data @- << EOF | jq . + # { + # "orgID": "INFLUX_ORG_ID", + # "secrets": { + # "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL" + # }, + # "remotes": [ + # { + # "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml" + # } + # ] + # } + # EOF + # - label: 'cURL: Apply template objects with environment references' + # lang: Shell + # source: | + # curl --request POST "http://localhost:8086/api/v2/templates/apply" \ + # --header "Authorization: Token INFLUX_API_TOKEN" \ + # --data @- << EOF + # { "orgID": "INFLUX_ORG_ID", + # "envRefs": { + # "linux-cpu-label": "MY_CPU_LABEL", + # "docker-bucket": "MY_DOCKER_BUCKET", + # "docker-spec-1": "MY_DOCKER_SPEC" + # }, + # "templates": [ + # { "contents": [{ + # "apiVersion": "influxdata.com/v2alpha1", + # "kind": "Label", + # "metadata": { + # "name": { + # "envRef": { + # "key": "linux-cpu-label" + # } + # } + # }, + # "spec": { + # "color": "#326BBA", + # "name": "inputs.cpu" + # } + # }] + # }, + # "templates": [ + # { "contents": [{ + # "apiVersion": "influxdata.com/v2alpha1", + # "kind": "Label", + # "metadata": { + # "name": { + # "envRef": { + # "key": "linux-cpu-label" + # } + # } + # }, + # "spec": { + # "color": "#326BBA", + # "name": "inputs.cpu" + # } + # }] + # }, + # { "contents": [{ + # "apiVersion": "influxdata.com/v2alpha1", + # "kind": "Bucket", + # "metadata": { + # "name": { + # "envRef": { + # "key": "docker-bucket" + # } + # } + # } + # }] + # } + # ] + # } + # EOF + # /api/v2/templates/export: + # post: + # operationId: ExportTemplate + # requestBody: + # content: + # application/json: + # schema: + # oneOf: + # - $ref: '#/components/schemas/TemplateExportByID' + # - $ref: '#/components/schemas/TemplateExportByName' + # description: Export resources as an InfluxDB template. + # required: false + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Template' + # application/x-yaml: + # schema: + # $ref: '#/components/schemas/Template' + # description: The template was created successfully. Returns the newly created template. + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Export a new template + # tags: + # - Templates + # /api/v2/users: {} + # /api/v2/users/{userID}: {} + # /api/v2/users/{userID}/password: {} + # /api/v2/variables: + # get: + # operationId: GetVariables + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The name of the organization. + # in: query + # name: org + # schema: + # type: string + # - description: The organization ID. + # in: query + # name: orgID + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variables' + # description: A list of variables for an organization. + # '400': + # $ref: '#/components/responses/GeneralServerError' + # description: Invalid request + # default: + # $ref: '#/components/responses/GeneralServerError' + # description: Internal server error + # summary: List all variables + # tags: + # - Variables + # post: + # operationId: PostVariables + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable to create + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable created + # default: + # $ref: '#/components/responses/GeneralServerError' + # description: Internal server error + # summary: Create a variable + # tags: + # - Variables + # /api/v2/variables/{variableID}: + # delete: + # operationId: DeleteVariablesID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Variable deleted + # default: + # $ref: '#/components/responses/GeneralServerError' + # description: Internal server error + # summary: Delete a variable + # tags: + # - Variables + # get: + # operationId: GetVariablesID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable found + # '404': + # $ref: '#/components/responses/GeneralServerError' + # description: Variable not found + # default: + # $ref: '#/components/responses/GeneralServerError' + # description: Internal server error + # summary: Retrieve a variable + # tags: + # - Variables + # patch: + # operationId: PatchVariablesID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable update to apply + # required: true + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable updated + # default: + # $ref: '#/components/responses/GeneralServerError' + # description: Internal server error + # summary: Update a variable + # tags: + # - Variables + # put: + # operationId: PutVariablesID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable to replace + # required: true + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Variable' + # description: Variable updated + # default: + # $ref: '#/components/responses/GeneralServerError' + # description: Internal server error + # summary: Replace a variable + # tags: + # - Variables + # /api/v2/variables/{variableID}/labels: + # get: + # operationId: GetVariablesIDLabels + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # responses: + # '200': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelsResponse' + # description: A list of all labels for a variable + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: List all labels for a variable + # tags: + # - Variables + # post: + # operationId: PostVariablesIDLabels + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # requestBody: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelMapping' + # description: Label to add + # required: true + # responses: + # '201': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/LabelResponse' + # description: The newly added label + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Add a label to a variable + # tags: + # - Variables + # /api/v2/variables/{variableID}/labels/{labelID}: + # delete: + # operationId: DeleteVariablesIDLabelsID + # parameters: + # - $ref: '#/components/parameters/TraceSpan' + # - description: The variable ID. + # in: path + # name: variableID + # required: true + # schema: + # type: string + # - description: The label ID to delete. + # in: path + # name: labelID + # required: true + # schema: + # type: string + # responses: + # '204': + # description: Delete has been accepted + # '404': + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Variable not found + # default: + # content: + # application/json: + # schema: + # $ref: '#/components/schemas/Error' + # description: Unexpected error + # summary: Delete a label from a variable + # tags: + # - Variables /api/v2/write: post: description: | @@ -7244,10 +7250,10 @@ paths: #### Write endpoints - The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless. + The `/write` and `/api/v2/write` endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless. - - Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v1/). - - Use [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v2/). + - Use the `/write` endpoint for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v1/). + - Use `/api/v2/write` endpoint for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v2/). #### Rate limits @@ -7670,10 +7676,10 @@ paths: #### Write endpoints - The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless. + The `/write` and `/api/v2/write` endpoints are functionally equivalent for writing data to InfluxDB Cloud Serverless. - - Use the [`/write` endpoint](#operation/PostLegacyWrite) for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v1/). - - Use [`/api/v2/write` endpoint](#operation/PostWrite) for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v2/). + - Use the `/write` endpoint for [InfluxDB v1 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v1/). + - Use `/api/v2/write` endpoint for [InfluxDB v2 parameter compatibility](/influxdb3/cloud-serverless/guides/api-compatibility/v2/). #### Rate limits @@ -7870,7 +7876,7 @@ components: results don't include the specified record. Use `after` instead of the `offset` parameter. - For more information about pagination parameters, see [Pagination](/influxdb3/cloud-serverless/api/#tag/Pagination). + For more information about pagination parameters, see Pagination. in: query name: after required: false @@ -7899,7 +7905,7 @@ components: The offset for pagination. The number of records to skip. - For more information about pagination parameters, see [Pagination](/influxdb3/cloud-serverless/api/#tag/Pagination). + For more information about pagination parameters, see Pagination. in: query name: offset required: false @@ -12604,7 +12610,7 @@ components: Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the - [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to + `GET /api/v2/authorizations` endpoint to list authorizations. type: string createdAt: @@ -12695,7 +12701,7 @@ components: Specifies the owner of the task. To find a user ID, you can use the - [`GET /api/v2/users` endpoint](#operation/GetUsers) to + `GET /api/v2/users` endpoint to list users. type: string scriptID: @@ -13191,7 +13197,7 @@ components: If you apply templates without providing a stack ID, InfluxDB initializes a new stack with all new resources. - To find a stack ID, use the InfluxDB [`/api/v2/stacks` API endpoint](#operation/ListStacks) to list stacks. + To find a stack ID, use the InfluxDB `/api/v2/stacks` API endpoint to list stacks. type: string @@ -14492,7 +14498,7 @@ components: type: http TokenAuthentication: description: | - Use the [Token authentication](#section/Authentication/TokenAuthentication) + Use the Token authentication scheme to authenticate to the InfluxDB API. In your API requests, send an `Authorization` header. @@ -14521,7 +14527,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - `/authorizations` endpoints) ### Related guides diff --git a/api-docs/influxdb3/cloud-serverless/tags.yml b/api-docs/influxdb3/cloud-serverless/tags.yml index 7cec23eb4..285821eea 100644 --- a/api-docs/influxdb3/cloud-serverless/tags.yml +++ b/api-docs/influxdb3/cloud-serverless/tags.yml @@ -2,36 +2,54 @@ tags: API compatibility: x-traitTag: true description: | + InfluxDB Cloud Serverless supports a subset of the InfluxDB v2 API. + Other endpoints in this reference are for the InfluxDB Cloud (TSM) API — + they may be accessible, but are not supported or recommended for use with + InfluxDB Cloud Serverless, which is powered by the InfluxDB 3 storage engine. + ### Write data - InfluxDB 3 Cloud Serverless provides the following HTTP API endpoints for writing data: + InfluxDB 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. + - **Recommended**: `/api/v2/write` endpoint + for new write workloads or for bringing existing InfluxDB v2 write workloads. + - `/write` endpoint for bringing existing InfluxDB v1 write workloads. - Both endpoints accept the same line protocol format and process data in the same way. + Both endpoints accept line protocol format and process data in the same way. ### Query data - InfluxDB 3 Cloud Serverless provides the following protocols for executing a query: + InfluxDB 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. + - HTTP API `/query` request that contains an InfluxQL query. + Use this endpoint when bringing existing InfluxDB v1 query workloads. + + ### Management endpoints + + Use the following endpoints to manage Cloud Serverless resources: + + - API tokens (authorizations) — create and manage API tokens + - Buckets — create and manage storage buckets + - Organizations — view and manage organizations + - Accounts — manage account information ### 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. + The `/api/v2/write` endpoint works with the Token authentication scheme 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. + The `/write` and `/query` endpoints work with InfluxDB 1.x username/password 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: Get started querying InfluxDB + href: /influxdb3/cloud-serverless/get-started/query/ + - title: Manage API tokens + href: /influxdb3/cloud-serverless/security/tokens/ + - title: Manage buckets + href: /influxdb3/cloud-serverless/admin/buckets/ - 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 @@ -40,11 +58,10 @@ tags: Authentication: x-traitTag: true description: | - Use one of the following schemes to authenticate to the InfluxDB 3 Cloud Serverless API: + Use one of the following schemes to authenticate to the InfluxDB Cloud Serverless API: - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - + - Token authentication + - Basic authentication Authorizations (API tokens): description: > @@ -68,13 +85,21 @@ tags: href: /influxdb3/cloud-serverless/admin/buckets/ Cells: + x-traitTag: true description: > - Manage cells within InfluxDB 3 Cloud Serverless dashboards. + Manage cells within dashboards. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Checks: + x-traitTag: true description: > Create and manage monitoring checks that query data and generate - notification statuses in InfluxDB 3 Cloud Serverless. + notification statuses. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Common parameters: x-traitTag: true @@ -83,26 +108,37 @@ tags: endpoints, including `bucket`, `bucketID`, `org`, and `orgID`. Config: + x-traitTag: true description: > - Retrieve configuration information for an InfluxDB 3 Cloud Serverless - instance. + Retrieve configuration information for an InfluxDB instance. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Dashboards: + x-traitTag: true description: > - Create and manage dashboards in InfluxDB 3 Cloud Serverless. + Create and manage dashboards. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). DBRPs: + x-traitTag: true description: > - Manage database and retention policy (DBRP) mappings that route InfluxDB - v1-compatible requests to InfluxDB 3 Cloud Serverless buckets. - x-related: - - title: Database and retention policy mapping - href: /influxdb3/cloud-serverless/reference/api/influxdb-1x/dbrp/ + Manage database and retention policy (DBRP) mappings. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Delete: + x-traitTag: true description: > - Delete time series data from an InfluxDB 3 Cloud Serverless bucket by - specifying a time range and optional predicate. + Delete time series data from a bucket by specifying a time range and + optional predicate. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Headers: x-traitTag: true @@ -112,20 +148,28 @@ tags: `Content-Type`. Invokable Scripts: + x-traitTag: true description: > - Store, manage, and execute custom Flux scripts in InfluxDB 3 Cloud - Serverless. Scripts accept runtime parameters and can be invoked via - dedicated endpoints. + Store, manage, and execute custom Flux scripts. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Labels: + x-traitTag: true description: > - Create and manage labels for organizing InfluxDB 3 Cloud Serverless - resources. + Create and manage labels for organizing resources. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Legacy Authorizations: + x-traitTag: true description: > - Manage legacy (v1-compatible) authorization credentials in InfluxDB 3 - Cloud Serverless. + Manage legacy (v1-compatible) authorization credentials. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Limits: description: > @@ -133,14 +177,21 @@ tags: organization. NotificationEndpoints: + x-traitTag: true description: > - Create and manage notification endpoints that receive alert notifications - from InfluxDB 3 Cloud Serverless monitoring checks. + Create and manage notification endpoints that receive alert notifications. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). NotificationRules: + x-traitTag: true description: > Create and manage notification rules that define when and how - InfluxDB 3 Cloud Serverless sends notifications to endpoints. + notifications are sent to endpoints. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Organizations: description: > @@ -157,8 +208,12 @@ tags: InfluxDB 3 Cloud Serverless API. Ping: + x-traitTag: true description: > - Check the availability of the InfluxDB 3 Cloud Serverless instance. + Check the availability of an InfluxDB instance. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Query data: description: > @@ -178,9 +233,12 @@ tags: Serverless API. Resources: + x-traitTag: true description: > - Retrieve a list of top-level resource types available in the InfluxDB 3 - Cloud Serverless API. + Retrieve a list of top-level resource types available in the API. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Response codes: x-traitTag: true @@ -189,36 +247,63 @@ tags: endpoints and their meanings. Routes: + x-traitTag: true description: > - Retrieve top-level routes for the InfluxDB 3 Cloud Serverless API. + Retrieve top-level routes for the InfluxDB API. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Rules: + x-traitTag: true description: > - Manage notification rules in InfluxDB 3 Cloud Serverless. + Manage notification rules. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Secrets: + x-traitTag: true description: > - Create and manage secrets (key-value pairs) for use in InfluxDB 3 Cloud - Serverless Flux scripts and tasks. + Create and manage secrets (key-value pairs) for use in Flux scripts + and tasks. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Security and access endpoints: + x-traitTag: true description: > - Endpoints for managing authentication and access control in InfluxDB 3 - Cloud Serverless. + Endpoints for managing authentication and access control. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Setup: + x-traitTag: true description: > - Configure an initial InfluxDB 3 Cloud Serverless instance, including - creating the initial user, organization, and bucket. + Configure an initial InfluxDB instance, including creating the initial + user, organization, and bucket. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Signin: + x-traitTag: true description: > Create a user session by signing in with username and password credentials. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Signout: + x-traitTag: true description: > End a user session by signing out. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Supported operations: x-traitTag: true @@ -234,29 +319,47 @@ tags: | **Delete** | `DELETE` | Remove a resource. | System information endpoints: + x-traitTag: true description: > - Endpoints for retrieving system-level information about the InfluxDB 3 - Cloud Serverless instance. + Endpoints for retrieving system-level information about an InfluxDB + instance. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Tasks: + x-traitTag: true description: > Schedule and manage Flux tasks that process and transform data on a - recurring basis in InfluxDB 3 Cloud Serverless. + recurring basis. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Telegraf Plugins: + x-traitTag: true description: > - Retrieve available Telegraf plugin configuration templates for use with - InfluxDB 3 Cloud Serverless. + Retrieve available Telegraf plugin configuration templates. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Telegrafs: + x-traitTag: true description: > Create and manage Telegraf agent configurations that collect and write - data to InfluxDB 3 Cloud Serverless. + data to InfluxDB. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Templates: + x-traitTag: true description: > - Export and apply InfluxDB templates, and manage template stacks for - InfluxDB 3 Cloud Serverless. + Export and apply InfluxDB templates, and manage template stacks. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Usage: description: > @@ -264,21 +367,28 @@ tags: Serverless organization. Users: + x-traitTag: true description: > - View specific users that are members of your InfluxDB 3 Cloud Serverless - organization. - x-related: - - title: Manage users - href: /influxdb3/cloud-serverless/organizations/users/ + View specific users that are members of your organization. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Variables: + x-traitTag: true description: > - Create and manage variables for use in InfluxDB 3 Cloud Serverless - dashboards. + Create and manage variables for use in dashboards. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Views: + x-traitTag: true description: > - Manage cell views within InfluxDB 3 Cloud Serverless dashboards. + Manage cell views within dashboards. + This is an InfluxDB Cloud (TSM) endpoint that may be accessible but is + not supported or recommended for use with InfluxDB Cloud Serverless + (powered by the InfluxDB 3 storage engine). Write data: description: > diff --git a/api-docs/scripts/generate-openapi-articles.ts b/api-docs/scripts/generate-openapi-articles.ts index c901de7ac..b6ac0f972 100644 --- a/api-docs/scripts/generate-openapi-articles.ts +++ b/api-docs/scripts/generate-openapi-articles.ts @@ -2,149 +2,109 @@ /** * Generate OpenAPI Articles Script * - * Generates Hugo data files and content pages from OpenAPI specifications - * for all InfluxDB products. + * Processes OpenAPI specs for Hugo-native API documentation. This script + * expects specs to already be fetched (via getswagger.sh) and post-processed + * (via post-process-specs.ts) before it runs. * - * Products are auto-discovered by scanning api-docs/ for .config.yml files. - * Hugo paths, menu keys, and static file names are derived from directory - * structure and existing Hugo frontmatter. - * - * This script: - * 1. Discovers products from .config.yml files - * 2. Cleans output directories (unless --no-clean) - * 3. Transforms documentation links in specs - * 4. Copies specs to static directory for download - * 5. Generates tag-based data fragments (YAML and JSON) - * 6. Generates Hugo content pages from article data + * Modes: + * - Default: copy specs to static/ + generate Hugo article pages + * - --static-only: copy specs to static/ only (no article generation) * * Usage: - * node generate-openapi-articles.js # Clean and generate all products - * node generate-openapi-articles.js influxdb3-core # Clean and generate single product + * node generate-openapi-articles.js # Full generation (static + articles) + * node generate-openapi-articles.js cloud-v2 # Single product + * node generate-openapi-articles.js --static-only # Copy specs to static/ only * node generate-openapi-articles.js --no-clean # Generate without cleaning * node generate-openapi-articles.js --dry-run # Preview what would be cleaned - * node generate-openapi-articles.js --skip-fetch # Skip getswagger.sh fetch step * node generate-openapi-articles.js --validate-links # Validate documentation links * * @module generate-openapi-articles */ -import { execSync } from 'child_process'; import * as path from 'path'; import * as fs from 'fs'; // Import the OpenAPI to Hugo converter const openapiPathsToHugo = require('./openapi-paths-to-hugo-data/index.js'); -// --------------------------------------------------------------------------- -// Interfaces -// --------------------------------------------------------------------------- - -/** Operation metadata structure from tag-based articles */ +/** + * Operation metadata structure from tag-based articles + */ interface OperationMeta { operationId: string; method: string; path: string; summary: string; tags: string[]; + /** Compatibility version (v1 or v2) for migration context */ compatVersion?: string; + /** External documentation link */ externalDocs?: { description: string; url: string; }; } -/** Article data structure from articles.yml */ -interface ArticleData { - articles: Array<{ - path: string; - fields: { - name?: string; - title?: string; - description?: string; - tag?: string; - isConceptual?: boolean; - showSecuritySchemes?: boolean; - tagDescription?: string; - menuGroup?: string; - staticFilePath?: string; - operations?: OperationMeta[]; - related?: (string | { title: string; href: string })[]; - source?: string; - weight?: number; - }; - }>; +/** + * Spec file configuration with optional display name + */ +interface SpecFileConfig { + /** Path to the OpenAPI spec file */ + path: string; + /** Display name for downloads (e.g., "Management API", "v2 Data API") */ + displayName?: string; } -/** Single API entry from .config.yml */ -interface ApiConfigEntry { - root: string; - 'x-influxdata-docs-aliases'?: string[]; -} - -/** Parsed .config.yml file */ -interface DotConfig { - 'x-influxdata-product-name'?: string; - apis?: Record; -} - -/** A resolved API section within a product */ -interface DiscoveredApi { - /** API key from .config.yml (e.g., 'v3', 'management', 'data') */ - apiKey: string; - /** Version number from the @-suffix (e.g., '3', '0', '2') */ - version: string; - /** Resolved full path to the spec file */ - specFile: string; - /** Hugo section slug: 'api' or 'management-api' */ - sectionSlug: string; -} - -/** A fully resolved product discovered from .config.yml */ -interface DiscoveredProduct { - /** Directory containing .config.yml */ - configDir: string; - /** Product directory relative to api-docs/ (e.g., 'influxdb3/core') */ - productDir: string; - /** Human-readable name from x-influxdata-product-name */ - productName: string; - /** Hugo content directory (e.g., 'content/influxdb3/core') */ +/** + * Product configuration for API generation + */ +interface ProductConfig { + /** Path to the OpenAPI spec file (single spec - use specFiles for multiple) */ + specFile?: string; + /** Multiple spec files to merge for this product */ + specFiles?: SpecFileConfig[]; + /** Path to the Hugo content directory for generated pages */ pagesDir: string; - /** Hugo menu key from cascade.product (e.g., 'influxdb3_core') */ - menuKey: string; - /** True if hand-maintained api/_index.md has its own menu entry */ - skipParentMenu: boolean; - /** Static file directory name (e.g., 'influxdb3-core') */ - staticDirName: string; - /** Resolved API sections */ - apis: DiscoveredApi[]; + /** Optional description of the product */ + description?: string; + /** Hugo menu identifier for this product (e.g., 'influxdb3_core') */ + menuKey?: string; + /** Skip adding menu entry to generated parent page (use when existing reference page has menu entry) */ + skipParentMenu?: boolean; + /** Use tag-based generation instead of path-based (default: false) */ + useTagBasedGeneration?: boolean; } -/** Product data from products.yml with api_path */ +/** + * Map of product identifiers to their configuration + */ +type ProductConfigMap = Record; + +// Calculate the relative paths +const DOCS_ROOT = '.'; +// Read resolved specs from _build/ (written by post-process-specs.ts). +// Source specs in api-docs/ are never read directly by this script. +const API_DOCS_ROOT = 'api-docs/_build'; + +// CLI flags +const validateLinks = process.argv.includes('--validate-links'); +const staticOnly = process.argv.includes('--static-only'); +const noClean = process.argv.includes('--no-clean'); +const dryRun = process.argv.includes('--dry-run'); + +/** + * Product data from products.yml with api_path + */ interface ProductData { name: string; api_path?: string; alt_link_key?: string; } -// --------------------------------------------------------------------------- -// Constants and CLI flags -// --------------------------------------------------------------------------- - -const DOCS_ROOT = '.'; -const API_DOCS_ROOT = 'api-docs'; - -const validateLinks = process.argv.includes('--validate-links'); -const skipFetch = process.argv.includes('--skip-fetch'); -const noClean = process.argv.includes('--no-clean'); -const dryRun = process.argv.includes('--dry-run'); - -// --------------------------------------------------------------------------- -// Utility functions -// --------------------------------------------------------------------------- - /** - * Load products with API paths from data/products.yml. - * Returns a map of alt_link_key to API path for alt_links generation. + * Load products with API paths from data/products.yml + * Returns a map of alt_link_key to API path for alt_links generation + * The alt_link_key matches what the Hugo product-selector template expects */ function loadApiProducts(): Map { const yaml = require('js-yaml'); @@ -157,10 +117,12 @@ function loadApiProducts(): Map { const productsContent = fs.readFileSync(productsFile, 'utf8'); const products = yaml.load(productsContent) as Record; + const apiProducts = new Map(); - for (const [, product] of Object.entries(products)) { + for (const [key, product] of Object.entries(products)) { if (product.api_path && product.alt_link_key) { + // Use alt_link_key as the key (matches Hugo template expectations) apiProducts.set(product.alt_link_key, product.api_path); } } @@ -168,291 +130,76 @@ function loadApiProducts(): Map { return apiProducts; } +// Load API products at module initialization const apiProductsMap = loadApiProducts(); -/** Execute a shell command and handle errors */ -function execCommand(command: string, description?: string): void { - try { - if (description) { - console.log(`\n${description}...`); - } - console.log(`Executing: ${command}\n`); - execSync(command, { stdio: 'inherit' }); - } catch (error) { - console.error(`\n❌ Error executing command: ${command}`); - if (error instanceof Error) { - console.error(error.message); - } - process.exit(1); - } -} - -// --------------------------------------------------------------------------- -// Auto-discovery functions -// --------------------------------------------------------------------------- - /** - * Recursively find all .config.yml files under api-docs/. - * Excludes the root api-docs/.config.yml and internal directories. - */ -function findConfigFiles(rootDir: string): string[] { - const configs: string[] = []; - const skipDirs = new Set([ - 'node_modules', - 'dist', - '_build', - 'scripts', - 'openapi', - ]); - - function scanDir(dir: string, depth: number): void { - if (depth > 5) return; - let entries: fs.Dirent[]; - try { - entries = fs.readdirSync(dir, { withFileTypes: true }); - } catch { - return; - } - for (const entry of entries) { - if (skipDirs.has(entry.name)) continue; - const fullPath = path.join(dir, entry.name); - if (entry.isDirectory()) { - scanDir(fullPath, depth + 1); - } else if (entry.name === '.config.yml' && dir !== rootDir) { - configs.push(fullPath); - } - } - } - - scanDir(rootDir, 0); - return configs.sort(); -} - -/** - * Parse an API entry key like 'v3@3' into apiKey and version. - */ -function parseApiEntry(entry: string): { apiKey: string; version: string } { - const atIdx = entry.indexOf('@'); - if (atIdx === -1) { - return { apiKey: entry, version: '0' }; - } - return { - apiKey: entry.substring(0, atIdx), - version: entry.substring(atIdx + 1), - }; -} - -/** - * Determine Hugo section slug from API key. - * 'management' → 'management-api', everything else → 'api'. - */ -function getSectionSlug(apiKey: string): string { - if (apiKey === 'management') return 'management-api'; - return 'api'; -} - -/** - * Derive a clean static directory name from a product directory path. - * Replaces path separators and underscores with hyphens. + * Execute a shell command and handle errors * - * @example 'influxdb3/core' → 'influxdb3-core' - * @example 'enterprise_influxdb/v1' → 'enterprise-influxdb-v1' + * @param command - Command to execute + * @param description - Human-readable description of the command + * @throws Exits process with code 1 on error */ -function deriveStaticDirName(productDir: string): string { - return productDir.replace(/[/_]/g, '-'); -} - /** - * Read the cascade.product field from a product's _index.md frontmatter. - * This value serves as the Hugo menu key. - */ -function readMenuKey(pagesDir: string): string { - const yaml = require('js-yaml'); - const indexFile = path.join(pagesDir, '_index.md'); - - if (!fs.existsSync(indexFile)) { - console.warn(`⚠️ Product index not found: ${indexFile}`); - return ''; - } - - const content = fs.readFileSync(indexFile, 'utf8'); - const fmMatch = content.match(/^---\n([\s\S]*?)\n---/); - if (!fmMatch) return ''; - - try { - const fm = yaml.load(fmMatch[1]) as Record; - const cascade = fm.cascade as Record | undefined; - if (cascade?.product) return cascade.product; - - // Fallback: first key of the menu map - if (fm.menu && typeof fm.menu === 'object') { - const keys = Object.keys(fm.menu as Record); - if (keys.length > 0) return keys[0]; - } - } catch { - console.warn(`⚠️ Could not parse frontmatter in ${indexFile}`); - } - - return ''; -} - -/** - * Check whether a hand-maintained api/_index.md already has a menu entry. - * If so, the generator should skip adding its own parent menu entry. + * Generate a clean static directory name from a product key. + * Handles the influxdb3_* products to avoid redundant 'influxdb-influxdb3' prefixes. * - * Only detects genuinely hand-maintained files — files previously generated - * by this script (which have articleDataKey in frontmatter) are ignored, - * since they'll be regenerated during this run. + * @param productKey - Product identifier (e.g., 'cloud-v2', 'influxdb3_core') + * @returns Clean directory name (e.g., 'influxdb-cloud-v2', 'influxdb3-core') */ -function hasExistingApiMenu(pagesDir: string): boolean { - const yaml = require('js-yaml'); - const apiIndex = path.join(pagesDir, 'api', '_index.md'); - - if (!fs.existsSync(apiIndex)) return false; - - const content = fs.readFileSync(apiIndex, 'utf8'); - const fmMatch = content.match(/^---\n([\s\S]*?)\n---/); - if (!fmMatch) return false; - - try { - const fm = yaml.load(fmMatch[1]) as Record; - // Skip files generated by this script (they have articleDataKey) - if (fm.articleDataKey) return false; - return !!fm.menu; - } catch { - return false; +function getStaticDirName(productKey: string): string { + // For influxdb3_* products, convert underscore to hyphen and don't add prefix + if (productKey.startsWith('influxdb3_')) { + return productKey.replace('_', '-'); } + // For other products, add 'influxdb-' prefix + return `influxdb-${productKey}`; } /** - * Discover all products by scanning api-docs/ for .config.yml files. - * Derives Hugo paths from directory structure and existing frontmatter. - */ -function discoverProducts(): DiscoveredProduct[] { - const yaml = require('js-yaml'); - const products: DiscoveredProduct[] = []; - const configFiles = findConfigFiles(API_DOCS_ROOT); - - for (const configPath of configFiles) { - const configDir = path.dirname(configPath); - const productDir = path.relative(API_DOCS_ROOT, configDir); - - let config: DotConfig; - try { - const raw = fs.readFileSync(configPath, 'utf8'); - config = yaml.load(raw) as DotConfig; - } catch (err) { - console.warn(`⚠️ Could not parse ${configPath}: ${err}`); - continue; - } - - if (!config.apis || Object.keys(config.apis).length === 0) { - continue; - } - - const pagesDir = path.join(DOCS_ROOT, 'content', productDir); - const staticDirName = deriveStaticDirName(productDir); - const menuKey = readMenuKey(pagesDir); - const skipParentMenu = hasExistingApiMenu(pagesDir); - - // Parse API entries, skipping compatibility specs - const apis: DiscoveredApi[] = []; - for (const [entryKey, entry] of Object.entries(config.apis)) { - const { apiKey, version } = parseApiEntry(entryKey); - - // Skip v1-compatibility entries (being removed in pipeline restructure) - if (apiKey.includes('compatibility')) continue; - - // Prefer post-processed spec from _build/ (has overlays and tag configs), - // fall back to source spec for standalone usage - const sourceSpec = path.join(configDir, entry.root); - const buildSpec = path.join(API_DOCS_ROOT, '_build', productDir, entry.root); - const specFile = fs.existsSync(buildSpec) ? buildSpec : sourceSpec; - const sectionSlug = getSectionSlug(apiKey); - - apis.push({ apiKey, version, specFile, sectionSlug }); - } - - if (apis.length === 0) continue; - - products.push({ - configDir, - productDir, - productName: config['x-influxdata-product-name'] || productDir, - pagesDir, - menuKey, - skipParentMenu, - staticDirName, - apis, - }); - } - - return products; -} - -// --------------------------------------------------------------------------- -// Cleanup functions -// --------------------------------------------------------------------------- - -/** - * Get all paths that would be cleaned for a product. + * Get all paths that would be cleaned for a product * - * @param product - The product to clean - * @param allStaticDirNames - Names of all products (to avoid prefix collisions) + * @param productKey - Product identifier (e.g., 'influxdb3_core') + * @param config - Product configuration + * @returns Object with directories and files arrays */ function getCleanupPaths( - product: DiscoveredProduct, - allStaticDirNames: string[] -): { - directories: string[]; - files: string[]; -} { + productKey: string, + config: ProductConfig +): { directories: string[]; files: string[] } { + const staticDirName = getStaticDirName(productKey); const staticPath = path.join(DOCS_ROOT, 'static/openapi'); + const directories: string[] = []; const files: string[] = []; // Tag specs directory: static/openapi/{staticDirName}/ - const tagSpecsDir = path.join(staticPath, product.staticDirName); + const tagSpecsDir = path.join(staticPath, staticDirName); if (fs.existsSync(tagSpecsDir)) { directories.push(tagSpecsDir); } - // Article data directory: data/article_data/influxdb/{staticDirName}/ + // Article data directory: data/article_data/influxdb/{productKey}/ const articleDataDir = path.join( DOCS_ROOT, - `data/article_data/influxdb/${product.staticDirName}` + `data/article_data/influxdb/${productKey}` ); if (fs.existsSync(articleDataDir)) { directories.push(articleDataDir); } - // Content pages: content/{pagesDir}/{sectionSlug}/ for each API - for (const api of product.apis) { - const contentDir = path.join(product.pagesDir, api.sectionSlug); - if (fs.existsSync(contentDir)) { - directories.push(contentDir); - } + // Content pages directory: content/{pagesDir}/api/ + const contentApiDir = path.join(config.pagesDir, 'api'); + if (fs.existsSync(contentApiDir)) { + directories.push(contentApiDir); } - // Root spec files: static/openapi/{staticDirName}*.yml and .json - // Avoid matching files that belong to products with longer names - // (e.g., 'influxdb-cloud' should not match 'influxdb-cloud-dedicated-*.yml') - const longerPrefixes = allStaticDirNames.filter( - (n) => - n !== product.staticDirName && n.startsWith(product.staticDirName + '-') - ); - + // Root spec files: static/openapi/{staticDirName}-*.yml and .json if (fs.existsSync(staticPath)) { const staticFiles = fs.readdirSync(staticPath); + const pattern = new RegExp(`^${staticDirName}-.*\\.(yml|json)$`); staticFiles - .filter((f) => { - if (!f.startsWith(product.staticDirName)) return false; - // Exclude files belonging to a longer-named product - for (const longer of longerPrefixes) { - if (f.startsWith(longer)) return false; - } - return f.endsWith('.yml') || f.endsWith('.json'); - }) + .filter((f) => pattern.test(f)) .forEach((f) => { files.push(path.join(staticPath, f)); }); @@ -461,18 +208,22 @@ function getCleanupPaths( return { directories, files }; } -/** Clean output directories for a product before regeneration. */ -function cleanProductOutputs( - product: DiscoveredProduct, - allStaticDirNames: string[] -): void { - const { directories, files } = getCleanupPaths(product, allStaticDirNames); +/** + * Clean output directories for a product before regeneration + * + * @param productKey - Product identifier + * @param config - Product configuration + */ +function cleanProductOutputs(productKey: string, config: ProductConfig): void { + const { directories, files } = getCleanupPaths(productKey, config); + // Remove directories recursively for (const dir of directories) { console.log(`🧹 Removing directory: ${dir}`); fs.rmSync(dir, { recursive: true, force: true }); } + // Remove individual files for (const file of files) { console.log(`🧹 Removing file: ${file}`); fs.unlinkSync(file); @@ -481,21 +232,21 @@ function cleanProductOutputs( const total = directories.length + files.length; if (total > 0) { console.log( - `✓ Cleaned ${directories.length} directories, ${files.length} files for ${product.staticDirName}` + `✓ Cleaned ${directories.length} directories, ${files.length} files for ${productKey}` ); } } -/** Display dry-run preview of what would be cleaned. */ -function showDryRunPreview( - product: DiscoveredProduct, - allStaticDirNames: string[] -): void { - const { directories, files } = getCleanupPaths(product, allStaticDirNames); +/** + * Display dry-run preview of what would be cleaned + * + * @param productKey - Product identifier + * @param config - Product configuration + */ +function showDryRunPreview(productKey: string, config: ProductConfig): void { + const { directories, files } = getCleanupPaths(productKey, config); - console.log( - `\nDRY RUN: Would clean the following for ${product.staticDirName}:\n` - ); + console.log(`\nDRY RUN: Would clean the following for ${productKey}:\n`); if (directories.length > 0) { console.log('Directories to remove:'); @@ -516,9 +267,786 @@ function showDryRunPreview( ); } -// --------------------------------------------------------------------------- -// Link transformation -// --------------------------------------------------------------------------- +/** + * Generate Hugo data files from OpenAPI specification + * + * @param specFile - Path to the OpenAPI spec file + * @param dataOutPath - Output path for OpenAPI path fragments + * @param articleOutPath - Output path for article metadata + */ +function generateDataFromOpenAPI( + specFile: string, + dataOutPath: string, + articleOutPath: string +): void { + if (!fs.existsSync(dataOutPath)) { + fs.mkdirSync(dataOutPath, { recursive: true }); + } + + openapiPathsToHugo.generateHugoData({ + dataOutPath, + articleOutPath, + specFile, + }); +} + +/** + * Options for generating pages from article data + */ +interface GeneratePagesOptions { + /** Path to the articles data directory */ + articlesPath: string; + /** Output path for generated content pages */ + contentPath: string; + /** Hugo menu identifier for navigation (e.g., 'influxdb3_core') */ + menuKey?: string; + /** Parent menu item name (e.g., 'InfluxDB HTTP API') */ + menuParent?: string; + /** Product description for the parent page */ + productDescription?: string; + /** Skip adding menu entry to generated parent page */ + skipParentMenu?: boolean; +} + +/** + * Generate Hugo content pages from article data + * + * Creates markdown files with frontmatter from article metadata. + * Each article becomes a page with type: api that renders via Hugo-native templates. + * + * @param options - Generation options + */ +function generatePagesFromArticleData(options: GeneratePagesOptions): void { + const { + articlesPath, + contentPath, + menuKey, + menuParent, + productDescription, + skipParentMenu, + } = options; + const yaml = require('js-yaml'); + const articlesFile = path.join(articlesPath, 'articles.yml'); + + if (!fs.existsSync(articlesFile)) { + console.warn(`⚠️ Articles file not found: ${articlesFile}`); + return; + } + + // Read articles data + const articlesContent = fs.readFileSync(articlesFile, 'utf8'); + const data = yaml.load(articlesContent) as { + articles: Array<{ + path: string; + fields: Record; + }>; + }; + + if (!data.articles || !Array.isArray(data.articles)) { + console.warn(`⚠️ No articles found in ${articlesFile}`); + return; + } + + // Ensure content directory exists + if (!fs.existsSync(contentPath)) { + fs.mkdirSync(contentPath, { recursive: true }); + } + + // Determine the API parent directory from the first article's path + // e.g., if article path is "api/v1/health", the API root is "api" + const firstArticlePath = data.articles[0]?.path || ''; + const apiRootDir = firstArticlePath.split('/')[0]; + + // Generate parent _index.md for the API section + if (apiRootDir) { + const apiParentDir = path.join(contentPath, apiRootDir); + const parentIndexFile = path.join(apiParentDir, '_index.md'); + + if (!fs.existsSync(apiParentDir)) { + fs.mkdirSync(apiParentDir, { recursive: true }); + } + + if (!fs.existsSync(parentIndexFile)) { + // Build description - use product description or generate from product name + const apiDescription = + productDescription || + `Use the InfluxDB HTTP API to write data, query data, and manage databases, tables, and tokens.`; + + const parentFrontmatter: Record = { + title: menuParent || 'InfluxDB HTTP API', + description: apiDescription, + weight: 104, + type: 'api', + }; + + // Add menu entry for parent page (unless skipParentMenu is true) + if (menuKey && !skipParentMenu) { + parentFrontmatter.menu = { + [menuKey]: { + name: menuParent || 'InfluxDB HTTP API', + parent: 'Reference', + }, + }; + } + + // Build page content with intro paragraph and children listing + const introText = apiDescription.replace( + 'InfluxDB', + '{{% product-name %}}' + ); + const parentContent = `--- +${yaml.dump(parentFrontmatter)}--- + +${introText} + +{{< children >}} +`; + + fs.writeFileSync(parentIndexFile, parentContent); + console.log(`✓ Generated parent index at ${parentIndexFile}`); + } + } + + // Generate a page for each article + for (const article of data.articles) { + const pagePath = path.join(contentPath, article.path); + const pageFile = path.join(pagePath, '_index.md'); + + // Create directory if needed + if (!fs.existsSync(pagePath)) { + fs.mkdirSync(pagePath, { recursive: true }); + } + + // Build frontmatter object + // Use menuName for display (actual endpoint path like /health) + // Fall back to name or path if menuName is not set + const displayName = + article.fields.menuName || article.fields.name || article.path; + const frontmatter: Record = { + title: displayName, + description: `API reference for ${displayName}`, + type: 'api', + // Use explicit layout to override Hugo's default section template lookup + // (Hugo's section lookup ignores `type`, so we need `layout` for the 3-column API layout) + layout: 'list', + staticFilePath: article.fields.staticFilePath, + weight: 100, + }; + + // Add menu entry if menuKey is provided + // Use menuName for menu display (shows actual endpoint path like /health) + if (menuKey) { + frontmatter.menu = { + [menuKey]: { + name: displayName, + ...(menuParent && { parent: menuParent }), + }, + }; + } + + // Add related links if present in article fields + if ( + article.fields.related && + Array.isArray(article.fields.related) && + article.fields.related.length > 0 + ) { + frontmatter.related = article.fields.related; + } + + // Add OpenAPI tags if present in article fields (for frontmatter metadata) + if ( + article.fields.apiTags && + Array.isArray(article.fields.apiTags) && + article.fields.apiTags.length > 0 + ) { + frontmatter.api_tags = article.fields.apiTags; + } + + const pageContent = `--- +${yaml.dump(frontmatter)}--- +`; + + fs.writeFileSync(pageFile, pageContent); + } + + console.log( + `✓ Generated ${data.articles.length} content pages in ${contentPath}` + ); +} + +/** + * Options for generating tag-based pages from article data + */ +interface GenerateTagPagesOptions { + /** Path to the articles data directory */ + articlesPath: string; + /** Output path for generated content pages */ + contentPath: string; + /** Hugo menu identifier for navigation (e.g., 'influxdb3_core') */ + menuKey?: string; + /** Parent menu item name (e.g., 'InfluxDB HTTP API') */ + menuParent?: string; + /** Product description for the parent page */ + productDescription?: string; + /** Skip adding menu entry to generated parent page */ + skipParentMenu?: boolean; + /** Map of API path to path-specific spec file (for single-operation rendering) */ + pathSpecFiles?: Map; +} + +/** + * Generate Hugo content pages from tag-based article data + * + * Creates markdown files with frontmatter from article metadata. + * Each article becomes a page with type: api that renders via Hugo-native templates. + * Includes operation metadata for TOC generation. + * + * @param options - Generation options + */ +function generateTagPagesFromArticleData( + options: GenerateTagPagesOptions +): void { + const { + articlesPath, + contentPath, + menuKey, + menuParent, + productDescription, + skipParentMenu, + pathSpecFiles, + } = options; + const yaml = require('js-yaml'); + const articlesFile = path.join(articlesPath, 'articles.yml'); + + if (!fs.existsSync(articlesFile)) { + console.warn(`⚠️ Articles file not found: ${articlesFile}`); + return; + } + + // Read articles data + const articlesContent = fs.readFileSync(articlesFile, 'utf8'); + const data = yaml.load(articlesContent) as { + articles: Array<{ + path: string; + fields: { + name?: string; + title?: string; + description?: string; + tag?: string; + isConceptual?: boolean; + showSecuritySchemes?: boolean; + tagDescription?: string; + menuGroup?: string; + staticFilePath?: string; + operations?: OperationMeta[]; + related?: (string | { title: string; href: string })[]; + weight?: number; + }; + }>; + }; + + if (!data.articles || !Array.isArray(data.articles)) { + console.warn(`⚠️ No articles found in ${articlesFile}`); + return; + } + + // Ensure content directory exists + if (!fs.existsSync(contentPath)) { + fs.mkdirSync(contentPath, { recursive: true }); + } + + // Generate parent _index.md for the API section + const apiParentDir = path.join(contentPath, 'api'); + const parentIndexFile = path.join(apiParentDir, '_index.md'); + + if (!fs.existsSync(apiParentDir)) { + fs.mkdirSync(apiParentDir, { recursive: true }); + } + + if (!fs.existsSync(parentIndexFile)) { + // Build description - use product description or generate from product name + const apiDescription = + productDescription || + `Use the InfluxDB HTTP API to write data, query data, and manage databases, tables, and tokens.`; + + const parentFrontmatter: Record = { + title: menuParent || 'InfluxDB HTTP API', + description: apiDescription, + weight: 104, + type: 'api', + }; + + // Add menu entry for parent page (unless skipParentMenu is true) + if (menuKey && !skipParentMenu) { + parentFrontmatter.menu = { + [menuKey]: { + name: menuParent || 'InfluxDB HTTP API', + parent: 'Reference', + }, + }; + } + + // Add alt_links for cross-product API navigation + if (apiProductsMap.size > 0) { + const altLinks: Record = {}; + apiProductsMap.forEach((apiPath, productName) => { + altLinks[productName] = apiPath; + }); + parentFrontmatter.alt_links = altLinks; + } + + // Build page content with intro paragraph and children listing + const introText = apiDescription.replace( + 'InfluxDB', + '{{% product-name %}}' + ); + const parentContent = `--- +${yaml.dump(parentFrontmatter)}--- + +${introText} + +{{< children >}} +`; + + fs.writeFileSync(parentIndexFile, parentContent); + console.log(`✓ Generated parent index at ${parentIndexFile}`); + } + + // Generate "All endpoints" page + const allEndpointsDir = path.join(apiParentDir, 'all-endpoints'); + const allEndpointsFile = path.join(allEndpointsDir, '_index.md'); + + if (!fs.existsSync(allEndpointsDir)) { + fs.mkdirSync(allEndpointsDir, { recursive: true }); + } + + const allEndpointsFrontmatter: Record = { + title: 'All endpoints', + description: `View all API endpoints sorted by path.`, + type: 'api', + layout: 'all-endpoints', + weight: 999, + isAllEndpoints: true, + }; + + // Add menu entry for all-endpoints page + if (menuKey) { + allEndpointsFrontmatter.menu = { + [menuKey]: { + name: 'All endpoints', + parent: menuParent || 'InfluxDB HTTP API', + }, + }; + } + + // Add alt_links for cross-product API navigation + if (apiProductsMap.size > 0) { + const altLinks: Record = {}; + apiProductsMap.forEach((apiPath, productName) => { + altLinks[productName] = apiPath; + }); + allEndpointsFrontmatter.alt_links = altLinks; + } + + const allEndpointsContent = `--- +${yaml.dump(allEndpointsFrontmatter)}--- + +All {{% product-name %}} API endpoints, sorted by path. +`; + + fs.writeFileSync(allEndpointsFile, allEndpointsContent); + console.log(`✓ Generated all-endpoints page at ${allEndpointsFile}`); + + // Generate a page for each article (tag) + for (const article of data.articles) { + const pagePath = path.join(contentPath, article.path); + const pageFile = path.join(pagePath, '_index.md'); + + // Create directory if needed + if (!fs.existsSync(pagePath)) { + fs.mkdirSync(pagePath, { recursive: true }); + } + + // Build frontmatter object + const title = article.fields.title || article.fields.name || article.path; + const isConceptual = article.fields.isConceptual === true; + + // Determine weight: use article.fields.weight if set, otherwise default to 100 + const weight = article.fields.weight ?? 100; + + const frontmatter: Record = { + title, + description: article.fields.description || `API reference for ${title}`, + type: 'api', + layout: isConceptual ? 'single' : 'list', + staticFilePath: article.fields.staticFilePath, + weight, + // Tag-based fields + tag: article.fields.tag, + isConceptual, + menuGroup: article.fields.menuGroup, + }; + + // Add operations for TOC generation (only for non-conceptual pages) + if ( + !isConceptual && + article.fields.operations && + article.fields.operations.length > 0 + ) { + frontmatter.operations = article.fields.operations; + } + + // Add tag description for conceptual pages + if (isConceptual && article.fields.tagDescription) { + frontmatter.tagDescription = article.fields.tagDescription; + } + + // Add showSecuritySchemes flag for authentication pages + if (article.fields.showSecuritySchemes) { + frontmatter.showSecuritySchemes = true; + } + + // Note: We deliberately don't add menu entries for tag-based API pages. + // The API sidebar navigation (api/sidebar-nav.html) handles navigation + // for API reference pages, avoiding conflicts with existing menu items + // like "Query data" and "Write data" that exist in the main sidebar. + + // Add related links if present in article fields + if ( + article.fields.related && + Array.isArray(article.fields.related) && + article.fields.related.length > 0 + ) { + frontmatter.related = article.fields.related; + } + + // Add client library related link for InfluxDB 3 products + if (contentPath.includes('influxdb3/') && !isConceptual) { + // Extract product segment from contentPath (e.g., "core" from ".../influxdb3/core") + const influxdb3Match = contentPath.match(/influxdb3\/([^/]+)/); + if (influxdb3Match) { + const productSegment = influxdb3Match[1]; + const clientLibLink = { + title: 'InfluxDB 3 API client libraries', + href: `/influxdb3/${productSegment}/reference/client-libraries/v3/`, + }; + const existing = + (frontmatter.related as Array<{ title: string; href: string }>) || []; + const alreadyHas = existing.some( + (r) => typeof r === 'object' && r.href === clientLibLink.href + ); + if (!alreadyHas) { + frontmatter.related = [...existing, clientLibLink]; + } + } + } + + // Add alt_links for cross-product API navigation + if (apiProductsMap.size > 0) { + const altLinks: Record = {}; + apiProductsMap.forEach((apiPath, productName) => { + altLinks[productName] = apiPath; + }); + frontmatter.alt_links = altLinks; + } + + const pageContent = `--- +${yaml.dump(frontmatter)}--- +`; + + fs.writeFileSync(pageFile, pageContent); + } + + console.log( + `✓ Generated ${data.articles.length} tag-based content pages in ${contentPath}` + ); + + // NOTE: Path page generation is disabled - all operations are now displayed + // inline on tag pages using Hugo-native templates with hash-based navigation + // for deep linking. The tag pages render all operations in a single scrollable + // view with a server-side generated TOC for quick navigation. +} + +/** + * Article data structure from articles.yml + */ +interface ArticleData { + articles: Array<{ + path: string; + fields: { + name?: string; + title?: string; + description?: string; + tag?: string; + isConceptual?: boolean; + showSecuritySchemes?: boolean; + tagDescription?: string; + menuGroup?: string; + staticFilePath?: string; + operations?: OperationMeta[]; + related?: (string | { title: string; href: string })[]; + source?: string; + }; + }>; +} + +/** + * Merge article data from multiple specs into a single articles.yml + * + * Articles are merged by tag name. Operations from different specs are combined + * into the same article if they share the same tag. + * + * @param articlesFiles - Array of paths to articles.yml files to merge + * @param outputPath - Path to write the merged articles.yml + */ +function mergeArticleData(articlesFiles: string[], outputPath: string): void { + const yaml = require('js-yaml'); + const mergedArticles = new Map(); + + for (const file of articlesFiles) { + if (!fs.existsSync(file)) { + console.warn(`⚠️ Articles file not found for merge: ${file}`); + continue; + } + + const content = fs.readFileSync(file, 'utf8'); + const data = yaml.load(content) as ArticleData; + + if (!data.articles || !Array.isArray(data.articles)) { + console.warn(`⚠️ No articles found in ${file}`); + continue; + } + + for (const article of data.articles) { + const key = article.fields.tag || article.path; + const existing = mergedArticles.get(key); + + if (existing) { + // Merge operations from this spec into existing article + if (article.fields.operations && article.fields.operations.length > 0) { + existing.fields.operations = [ + ...(existing.fields.operations || []), + ...article.fields.operations, + ]; + } + + // Merge related links (dedup by href for both strings and objects) + if (article.fields.related && article.fields.related.length > 0) { + const existingRelated = existing.fields.related || []; + const existingHrefs = new Set( + existingRelated.map((r) => (typeof r === 'string' ? r : r.href)) + ); + const newRelated = article.fields.related.filter((r) => { + const href = typeof r === 'string' ? r : r.href; + return !existingHrefs.has(href); + }); + existing.fields.related = [...existingRelated, ...newRelated]; + } + + // Keep the longest/most detailed description + if ( + article.fields.description && + (!existing.fields.description || + article.fields.description.length > + existing.fields.description.length) + ) { + existing.fields.description = article.fields.description; + } + + // Merge tagDescription if not already set + if (article.fields.tagDescription && !existing.fields.tagDescription) { + existing.fields.tagDescription = article.fields.tagDescription; + } + } else { + // Add new article + mergedArticles.set(key, JSON.parse(JSON.stringify(article))); + } + } + } + + // Convert map to array and write + const mergedData: ArticleData = { + articles: Array.from(mergedArticles.values()), + }; + + // Ensure output directory exists + const outputDir = path.dirname(outputPath); + if (!fs.existsSync(outputDir)) { + fs.mkdirSync(outputDir, { recursive: true }); + } + + // Write both YAML and JSON versions + const yamlPath = outputPath.endsWith('.yml') + ? outputPath + : `${outputPath}.yml`; + const jsonPath = yamlPath.replace(/\.yml$/, '.json'); + + fs.writeFileSync(yamlPath, yaml.dump(mergedData)); + fs.writeFileSync(jsonPath, JSON.stringify(mergedData, null, 2)); + + console.log( + `✓ Merged ${mergedArticles.size} articles from ${articlesFiles.length} specs to ${outputPath}` + ); +} + +/** + * Product configurations for all InfluxDB editions + * + * Maps product identifiers to their OpenAPI specs and content directories + */ +const productConfigs: ProductConfigMap = { + // InfluxDB v2 products - use tag-based generation for consistency + // These have existing /reference/api/ pages with menu entries, + // so we skip adding menu entries to the generated parent pages. + 'cloud-v2': { + specFiles: [ + { + path: path.join( + API_DOCS_ROOT, + 'influxdb/cloud/influxdb-cloud-v2-openapi.yaml' + ), + displayName: 'API', + }, + ], + pagesDir: path.join(DOCS_ROOT, 'content/influxdb/cloud'), + description: 'InfluxDB Cloud (v2 API)', + menuKey: 'influxdb_cloud', + skipParentMenu: true, + useTagBasedGeneration: true, + }, + 'oss-v2': { + specFiles: [ + { + path: path.join( + API_DOCS_ROOT, + 'influxdb/v2/influxdb-oss-v2-openapi.yaml' + ), + displayName: 'API', + }, + ], + pagesDir: path.join(DOCS_ROOT, 'content/influxdb/v2'), + description: 'InfluxDB OSS v2', + menuKey: 'influxdb_v2', + skipParentMenu: true, + useTagBasedGeneration: true, + }, + // InfluxDB 3 products use tag-based generation for better UX + // Keys use underscores to match Hugo data directory structure + influxdb3_core: { + specFile: path.join( + API_DOCS_ROOT, + 'influxdb3/core/influxdb3-core-openapi.yaml' + ), + pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/core'), + description: 'InfluxDB 3 Core', + menuKey: 'influxdb3_core', + useTagBasedGeneration: true, + }, + influxdb3_enterprise: { + specFile: path.join( + API_DOCS_ROOT, + 'influxdb3/enterprise/influxdb3-enterprise-openapi.yaml' + ), + pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/enterprise'), + description: 'InfluxDB 3 Enterprise', + menuKey: 'influxdb3_enterprise', + useTagBasedGeneration: true, + }, + // Cloud Dedicated and Clustered use multiple specs: + // - Management API: database, token, and cluster management (runs on management console) + // - v2 Data API: write, query, and compatibility endpoints (runs on cluster host) + // Both specs are kept separate for downloads (different servers/auth) but article + // data is merged so the sidebar shows functional tags from both. + // These products have existing /reference/api/ pages with menu entries, + // so we skip adding menu entries to the generated parent pages. + 'cloud-dedicated': { + specFiles: [ + { + path: path.join( + API_DOCS_ROOT, + 'influxdb3/cloud-dedicated/management/openapi.yml' + ), + displayName: 'Management API', + }, + { + path: path.join( + API_DOCS_ROOT, + 'influxdb3/cloud-dedicated/influxdb3-cloud-dedicated-openapi.yaml' + ), + displayName: 'v2 Data API', + }, + ], + pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/cloud-dedicated'), + description: 'InfluxDB Cloud Dedicated', + menuKey: 'influxdb3_cloud_dedicated', + skipParentMenu: true, + useTagBasedGeneration: true, + }, + 'cloud-serverless': { + specFiles: [ + { + path: path.join( + API_DOCS_ROOT, + 'influxdb3/cloud-serverless/influxdb3-cloud-serverless-openapi.yaml' + ), + displayName: 'v2 Data API', + }, + ], + pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/cloud-serverless'), + description: 'InfluxDB Cloud Serverless', + menuKey: 'influxdb3_cloud_serverless', + skipParentMenu: true, + useTagBasedGeneration: true, + }, + clustered: { + specFiles: [ + { + path: path.join( + API_DOCS_ROOT, + 'influxdb3/clustered/management/openapi.yml' + ), + displayName: 'Management API', + }, + { + path: path.join( + API_DOCS_ROOT, + 'influxdb3/clustered/influxdb3-clustered-openapi.yaml' + ), + displayName: 'v2 Data API', + }, + ], + pagesDir: path.join(DOCS_ROOT, 'content/influxdb3/clustered'), + description: 'InfluxDB Clustered', + menuKey: 'influxdb3_clustered', + skipParentMenu: true, + useTagBasedGeneration: true, + }, + // InfluxDB v1 products - use tag-based generation + // These have existing /tools/api/ pages with menu entries, + // so we skip adding menu entries to the generated parent pages. + 'oss-v1': { + specFile: path.join( + API_DOCS_ROOT, + 'influxdb/v1/influxdb-oss-v1-openapi.yaml' + ), + pagesDir: path.join(DOCS_ROOT, 'content/influxdb/v1'), + description: 'InfluxDB OSS v1', + menuKey: 'influxdb_v1', + skipParentMenu: true, + useTagBasedGeneration: true, + }, + 'enterprise-v1': { + specFile: path.join( + API_DOCS_ROOT, + 'enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml' + ), + pagesDir: path.join(DOCS_ROOT, 'content/enterprise_influxdb/v1'), + description: 'InfluxDB Enterprise v1', + menuKey: 'enterprise_influxdb_v1', + skipParentMenu: true, + useTagBasedGeneration: true, + }, +}; /** Fields that can contain markdown with links */ const MARKDOWN_FIELDS = new Set(['description', 'summary']); @@ -526,9 +1054,37 @@ const MARKDOWN_FIELDS = new Set(['description', 'summary']); /** Link placeholder pattern */ const LINK_PATTERN = /\/influxdb\/version\//g; +/** Base URL for absolutifying links in downloadable specs */ +const DOCS_BASE_URL = 'https://docs.influxdata.com'; + +/** + * Derive documentation root from spec file path. + * + * @example + * 'api-docs/influxdb3/core/influxdb3-core-openapi.yaml' → '/influxdb3/core' + * 'api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml' → '/influxdb3/enterprise' + * 'api-docs/influxdb/v2/influxdb-oss-v2-openapi.yaml' → '/influxdb/v2' + * 'api-docs/influxdb/v1/influxdb-oss-v1-openapi.yaml' → '/influxdb/v1' + * 'api-docs/enterprise_influxdb/v1/influxdb-enterprise-v1-openapi.yaml' → '/enterprise_influxdb/v1' + */ +function deriveProductPath(specPath: string): string { + // Match: api-docs/[_build/](enterprise_influxdb|influxdb3|influxdb)/(product-or-version)/... + const match = specPath.match( + /api-docs\/(?:_build\/)?(enterprise_influxdb|influxdb3?)\/([\w-]+)\// + ); + if (!match) { + throw new Error(`Cannot derive product path from: ${specPath}`); + } + return `/${match[1]}/${match[2]}`; +} + /** * Transform documentation links in OpenAPI spec markdown fields. * Replaces `/influxdb/version/` with the actual product path. + * + * @param spec - Parsed OpenAPI spec object + * @param productPath - Target path (e.g., '/influxdb3/core') + * @returns Spec with transformed links (new object, original unchanged) */ function transformDocLinks( spec: Record, @@ -566,23 +1122,88 @@ function transformDocLinks( return transformObject(spec); } +/** + * Prepend base URL to relative doc links for downloadable specs. + * Transforms markdown link targets (`](/path)`) and `x-related` href values. + * Skips external URLs, anchors, and protocol-relative URLs. + * + * @param spec - Parsed OpenAPI spec object with relative links + * @param baseUrl - Base URL to prepend (e.g., 'https://docs.influxdata.com') + * @returns Spec with absolute links (new object, original unchanged) + */ +function absolutifyLinks( + spec: Record, + baseUrl: string +): Record { + // Match `](/path` but not `](//` (protocol-relative) + const INTERNAL_LINK_RE = /(]\()(\/(?!\/))/g; + + function transformValue( + value: unknown, + key?: string, + parent?: Record + ): unknown { + if (typeof value === 'string') { + if (key && MARKDOWN_FIELDS.has(key)) { + return value.replace(INTERNAL_LINK_RE, `$1${baseUrl}$2`); + } + if ( + key === 'href' && + parent?.title && + value.startsWith('/') + ) { + return `${baseUrl}${value}`; + } + return value; + } + if (Array.isArray(value)) { + return value.map((item) => transformValue(item)); + } + if (value !== null && typeof value === 'object') { + return transformObject(value as Record); + } + return value; + } + + function transformObject( + obj: Record + ): Record { + const result: Record = {}; + for (const [k, v] of Object.entries(obj)) { + result[k] = transformValue(v, k, obj); + } + return result; + } + + return transformObject(spec); +} + /** * Resolve a URL path to a content file path. * - * @example '/influxdb3/core/api/auth/' → 'content/influxdb3/core/api/auth/_index.md' + * @example + * '/influxdb3/core/api/auth/' → 'content/influxdb3/core/api/auth/_index.md' */ function resolveContentPath(urlPath: string, contentDir: string): string { const normalized = urlPath.replace(/\/$/, ''); const indexPath = path.join(contentDir, normalized, '_index.md'); const directPath = path.join(contentDir, normalized + '.md'); - if (fs.existsSync(indexPath)) return indexPath; - if (fs.existsSync(directPath)) return directPath; - return indexPath; + if (fs.existsSync(indexPath)) { + return indexPath; + } + if (fs.existsSync(directPath)) { + return directPath; + } + return indexPath; // Return expected path for error message } /** * Validate that transformed links point to existing content. + * + * @param spec - Transformed OpenAPI spec + * @param contentDir - Path to Hugo content directory + * @returns Array of error messages for broken links */ function validateDocLinks( spec: Record, @@ -596,6 +1217,7 @@ function validateDocLinks( let match; while ((match = linkPattern.exec(value)) !== null) { const [, linkText, linkUrl] = match; + // Only validate internal links (start with /) if (linkUrl.startsWith('/') && !linkUrl.startsWith('//')) { const contentPath = resolveContentPath(linkUrl, contentDir); if (!fs.existsSync(contentPath)) { @@ -605,6 +1227,7 @@ function validateDocLinks( } } } + // Reset regex lastIndex for next string linkPattern.lastIndex = 0; } else if (Array.isArray(value)) { value.forEach((item, index) => @@ -623,503 +1246,345 @@ function validateDocLinks( return errors; } -// --------------------------------------------------------------------------- -// Page generation -// --------------------------------------------------------------------------- - /** - * Options for generating tag-based pages from article data + * Convert display name to filename-safe slug + * + * @param displayName - Display name (e.g., "Management API") + * @returns Filename-safe slug (e.g., "management-api") */ -interface GenerateTagPagesOptions { - articlesPath: string; - contentPath: string; - sectionSlug: string; - menuKey?: string; - menuParent?: string; - productDescription?: string; - skipParentMenu?: boolean; - specDownloadPath: string; - articleDataKey: string; - articleSection: string; - pathSpecFiles?: Map; +function slugifyDisplayName(displayName: string): string { + return displayName + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-|-$/g, ''); } /** - * Generate Hugo content pages from tag-based article data. + * Process a single spec file: transform links, write to static folder * - * Creates markdown files with frontmatter from article metadata. - * Each article becomes a page with type: api that renders via Hugo-native - * templates. Includes operation metadata for TOC generation. + * @param specConfig - Spec file configuration + * @param staticPath - Static directory path + * @param staticDirName - Product directory name + * @param productKey - Product identifier + * @returns Object with paths to generated files, or null if processing failed */ -function generateTagPagesFromArticleData( - options: GenerateTagPagesOptions -): void { - const { - articlesPath, - contentPath, - sectionSlug, - menuKey, - menuParent, - productDescription, - skipParentMenu, - specDownloadPath, - articleDataKey, - articleSection, - } = options; +function processSpecFile( + specConfig: SpecFileConfig, + staticPath: string, + staticDirName: string, + productKey: string +): { + staticSpecPath: string; + staticJsonSpecPath: string; + articlesPath: string; +} | null { const yaml = require('js-yaml'); - const articlesFile = path.join(articlesPath, 'articles.yml'); - if (!fs.existsSync(articlesFile)) { - console.warn(`⚠️ Articles file not found: ${articlesFile}`); - return; + if (!fs.existsSync(specConfig.path)) { + console.warn(`⚠️ Spec file not found: ${specConfig.path}`); + return null; } - const articlesContent = fs.readFileSync(articlesFile, 'utf8'); - const data = yaml.load(articlesContent) as ArticleData; - - if (!data.articles || !Array.isArray(data.articles)) { - console.warn(`⚠️ No articles found in ${articlesFile}`); - return; + // Generate filename from display name or use default. + // Strip staticDirName prefix from the spec filename to avoid doubled names + // (e.g., influxdb3-core + influxdb3-core-openapi → influxdb3-core-openapi). + let specSlug: string; + if (specConfig.displayName) { + specSlug = slugifyDisplayName(specConfig.displayName); + } else { + const rawName = path.parse(specConfig.path).name; + const prefix = `${staticDirName}-`; + specSlug = rawName.startsWith(prefix) + ? rawName.slice(prefix.length) + : rawName; } - if (!fs.existsSync(contentPath)) { - fs.mkdirSync(contentPath, { recursive: true }); - } + const staticSpecPath = path.join( + staticPath, + `${staticDirName}-${specSlug}.yml` + ); + const staticJsonSpecPath = path.join( + staticPath, + `${staticDirName}-${specSlug}.json` + ); + const articlesPath = path.join( + DOCS_ROOT, + `data/article_data/influxdb/${productKey}/${specSlug}` + ); - // Generate parent _index.md for the section - const sectionDir = path.join(contentPath, sectionSlug); - const parentIndexFile = path.join(sectionDir, '_index.md'); + try { + const specContent = fs.readFileSync(specConfig.path, 'utf8'); + const specObject = yaml.load(specContent) as Record; - if (!fs.existsSync(sectionDir)) { - fs.mkdirSync(sectionDir, { recursive: true }); - } - - if (!fs.existsSync(parentIndexFile)) { - const apiDescription = - productDescription || - `Use the InfluxDB HTTP API to write data, query data, and manage databases, tables, and tokens.`; - - const parentFrontmatter: Record = { - title: menuParent || 'InfluxDB HTTP API', - description: apiDescription, - weight: 104, - type: 'api', - articleDataKey, - articleSection, - }; - - if (menuKey && !skipParentMenu) { - parentFrontmatter.menu = { - [menuKey]: { - name: menuParent || 'InfluxDB HTTP API', - identifier: `api-reference-${articleDataKey}-${sectionSlug}`, - parent: 'Reference', - }, - }; - } - - if (apiProductsMap.size > 0) { - const altLinks: Record = {}; - apiProductsMap.forEach((apiPath, productName) => { - altLinks[productName] = apiPath; - }); - parentFrontmatter.alt_links = altLinks; - } - - const introText = apiDescription.replace( - 'InfluxDB', - '{{% product-name %}}' + // Transform documentation links (/influxdb/version/ -> actual product path) + const productPath = deriveProductPath(specConfig.path); + const transformedSpec = transformDocLinks(specObject, productPath); + console.log( + `✓ Transformed documentation links for ${specConfig.displayName || specSlug} to ${productPath}` ); - const parentContent = `--- -${yaml.dump(parentFrontmatter)}--- -${introText} + // Validate links if enabled + if (validateLinks) { + const contentDir = path.resolve(__dirname, '../../content'); + const linkErrors = validateDocLinks(transformedSpec, contentDir); + if (linkErrors.length > 0) { + console.warn(`\n⚠️ Link validation warnings for ${specConfig.path}:`); + linkErrors.forEach((err) => console.warn(` ${err}`)); + } + } -{{< children >}} -`; + // Absolutify links for downloadable specs (relative paths → full URLs) + const downloadSpec = absolutifyLinks(transformedSpec, DOCS_BASE_URL); - fs.writeFileSync(parentIndexFile, parentContent); - console.log(`✓ Generated parent index at ${parentIndexFile}`); + // Write downloadable spec to static folder + fs.writeFileSync(staticSpecPath, yaml.dump(downloadSpec)); + console.log(`✓ Wrote downloadable spec to ${staticSpecPath}`); + + fs.writeFileSync( + staticJsonSpecPath, + JSON.stringify(downloadSpec, null, 2) + ); + console.log(`✓ Generated JSON spec at ${staticJsonSpecPath}`); + + return { staticSpecPath, staticJsonSpecPath, articlesPath }; + } catch (specError) { + console.warn(`⚠️ Could not process spec: ${specError}`); + return null; + } +} + +/** + * Process a single product: fetch spec, generate data, and create pages + * + * Supports both single spec (specFile) and multiple specs (specFiles). + * For multiple specs, article data is merged so the sidebar shows + * functional tags from all specs. + * + * @param productKey - Product identifier (e.g., 'cloud-v2') + * @param config - Product configuration + */ +function processProduct(productKey: string, config: ProductConfig): void { + console.log('\n' + '='.repeat(80)); + console.log(`Processing ${config.description || productKey}`); + console.log('='.repeat(80)); + + // Clean output directories before regeneration (unless --no-clean, --dry-run, or --static-only) + if (!noClean && !dryRun && !staticOnly) { + cleanProductOutputs(productKey, config); } - // Generate "All endpoints" page - const allEndpointsDir = path.join(sectionDir, 'all-endpoints'); - const allEndpointsFile = path.join(allEndpointsDir, '_index.md'); + const staticPath = path.join(DOCS_ROOT, 'static/openapi'); + const staticDirName = getStaticDirName(productKey); + const staticPathsPath = path.join(staticPath, `${staticDirName}/paths`); + const mergedArticlesPath = path.join( + DOCS_ROOT, + `data/article_data/influxdb/${productKey}` + ); - if (!fs.existsSync(allEndpointsDir)) { - fs.mkdirSync(allEndpointsDir, { recursive: true }); + // Ensure static directory exists + if (!fs.existsSync(staticPath)) { + fs.mkdirSync(staticPath, { recursive: true }); } - const allEndpointsFrontmatter: Record = { - title: 'All endpoints', - description: `View all API endpoints sorted by path.`, - type: 'api', - layout: 'all-endpoints', - weight: 999, - isAllEndpoints: true, - articleDataKey, - articleSection, - }; + try { + // Determine spec files to process + const specFiles: SpecFileConfig[] = config.specFiles + ? config.specFiles + : config.specFile + ? [{ path: config.specFile }] + : []; - if (menuKey) { - allEndpointsFrontmatter.menu = { - [menuKey]: { - name: 'All endpoints', - identifier: `all-endpoints-${articleDataKey}-${sectionSlug}`, - parent: menuParent || 'InfluxDB HTTP API', - }, - }; - } - - if (apiProductsMap.size > 0) { - const altLinks: Record = {}; - apiProductsMap.forEach((apiPath, productName) => { - altLinks[productName] = apiPath; - }); - allEndpointsFrontmatter.alt_links = altLinks; - } - - const allEndpointsContent = `--- -${yaml.dump(allEndpointsFrontmatter)}--- - -All {{% product-name %}} API endpoints, sorted by path. -`; - - fs.writeFileSync(allEndpointsFile, allEndpointsContent); - console.log(`✓ Generated all-endpoints page at ${allEndpointsFile}`); - - // Generate a page for each article (tag) - for (const article of data.articles) { - const pagePath = path.join(contentPath, article.path); - const pageFile = path.join(pagePath, '_index.md'); - - if (!fs.existsSync(pagePath)) { - fs.mkdirSync(pagePath, { recursive: true }); + if (specFiles.length === 0) { + console.warn(`⚠️ No spec files configured for ${productKey}`); + return; } - const title = article.fields.title || article.fields.name || article.path; - const isConceptual = article.fields.isConceptual === true; - const weight = article.fields.weight ?? 100; - - const frontmatter: Record = { - title, - description: article.fields.description || `API reference for ${title}`, - type: 'api', - layout: isConceptual ? 'single' : 'list', - staticFilePath: article.fields.staticFilePath, - weight, - tag: article.fields.tag, - isConceptual, - menuGroup: article.fields.menuGroup, - specDownloadPath, - articleDataKey, - articleSection, - }; - - if ( - !isConceptual && - article.fields.operations && - article.fields.operations.length > 0 - ) { - frontmatter.operations = article.fields.operations; + // Check if any spec files exist + const existingSpecs = specFiles.filter((s) => fs.existsSync(s.path)); + if (existingSpecs.length === 0) { + console.warn( + `⚠️ No spec files found for ${productKey}. Run getswagger.sh first if needed.` + ); + return; } - if (isConceptual && article.fields.tagDescription) { - frontmatter.tagDescription = article.fields.tagDescription; - } + // Process each spec file + const processedSpecs: Array<{ + staticSpecPath: string; + articlesPath: string; + }> = []; + const allPathSpecFiles = new Map(); - if (article.fields.showSecuritySchemes) { - frontmatter.showSecuritySchemes = true; - } + for (const specConfig of specFiles) { + console.log( + `\n📄 Processing spec: ${specConfig.displayName || specConfig.path}` + ); - // Add related links if present - if ( - article.fields.related && - Array.isArray(article.fields.related) && - article.fields.related.length > 0 - ) { - frontmatter.related = article.fields.related; - } + const result = processSpecFile( + specConfig, + staticPath, + staticDirName, + productKey + ); - // Add client library related link for InfluxDB 3 products - if (contentPath.includes('influxdb3/') && !isConceptual) { - const influxdb3Match = contentPath.match(/influxdb3\/([^/]+)/); - if (influxdb3Match) { - const productSegment = influxdb3Match[1]; - const clientLibLink = { - title: 'InfluxDB 3 API client libraries', - href: `/influxdb3/${productSegment}/reference/client-libraries/v3/`, - }; - const existing = - (frontmatter.related as Array<{ title: string; href: string }>) || []; - const alreadyHas = existing.some( - (r) => typeof r === 'object' && r.href === clientLibLink.href - ); - if (!alreadyHas) { - frontmatter.related = [...existing, clientLibLink]; + if (result) { + processedSpecs.push(result); + + // Generate tag-based article data for this spec (skip in --static-only mode) + if (!staticOnly && config.useTagBasedGeneration) { + const specSlug = specConfig.displayName + ? slugifyDisplayName(specConfig.displayName) + : path.parse(specConfig.path).name; + const staticTagsPath = path.join( + staticPath, + `${staticDirName}/${specSlug}` + ); + + console.log( + `\n📋 Generating tag-based data for ${specConfig.displayName || specSlug}...` + ); + openapiPathsToHugo.generateHugoDataByTag({ + specFile: result.staticSpecPath, + dataOutPath: staticTagsPath, + articleOutPath: result.articlesPath, + includePaths: true, + }); + + // Generate path-specific specs + const specPathsPath = path.join(staticPathsPath, specSlug); + const pathSpecFiles = openapiPathsToHugo.generatePathSpecificSpecs( + result.staticSpecPath, + specPathsPath + ); + + // Merge path spec files into combined map + pathSpecFiles.forEach((value: string, key: string) => { + allPathSpecFiles.set(key, value); + }); } } } - if (apiProductsMap.size > 0) { - const altLinks: Record = {}; - apiProductsMap.forEach((apiPath, productName) => { - altLinks[productName] = apiPath; - }); - frontmatter.alt_links = altLinks; - } + // Article generation (skip in --static-only mode) + if (!staticOnly) { + // Merge article data from all specs (for multi-spec products) + if (processedSpecs.length > 1) { + console.log( + `\n📋 Merging article data from ${processedSpecs.length} specs...` + ); + const articlesFiles = processedSpecs.map((s) => + path.join(s.articlesPath, 'articles.yml') + ); + mergeArticleData( + articlesFiles, + path.join(mergedArticlesPath, 'articles.yml') + ); + } else if (processedSpecs.length === 1) { + // Single spec - copy articles to final location if needed + const sourceArticles = path.join( + processedSpecs[0].articlesPath, + 'articles.yml' + ); + const targetArticles = path.join(mergedArticlesPath, 'articles.yml'); - const pageContent = `--- -${yaml.dump(frontmatter)}--- -`; + // Only copy if source and target are different + if ( + sourceArticles !== targetArticles && + fs.existsSync(sourceArticles) + ) { + if (!fs.existsSync(mergedArticlesPath)) { + fs.mkdirSync(mergedArticlesPath, { recursive: true }); + } + fs.copyFileSync(sourceArticles, targetArticles); + fs.copyFileSync( + sourceArticles.replace('.yml', '.json'), + targetArticles.replace('.yml', '.json') + ); + console.log(`✓ Copied article data to ${mergedArticlesPath}`); + } + } - fs.writeFileSync(pageFile, pageContent); - } - - console.log( - `✓ Generated ${data.articles.length} tag-based content pages in ${contentPath}` - ); -} - -// --------------------------------------------------------------------------- -// Spec processing -// --------------------------------------------------------------------------- - -/** - * Process a single API section: transform links, write static spec, - * generate tag data, and create Hugo content pages. - */ -function processApiSection( - product: DiscoveredProduct, - api: DiscoveredApi, - staticBasePath: string -): void { - const yaml = require('js-yaml'); - const isDualApi = product.apis.length > 1; - - console.log(`\n📄 Processing ${api.sectionSlug} section (${api.apiKey})`); - - // --- 1. Determine paths --- - - // Root spec download: single → {dir}.yml, dual → {dir}-{section}.yml - const specSuffix = isDualApi ? `-${api.sectionSlug}` : ''; - const staticSpecPath = path.join( - staticBasePath, - `${product.staticDirName}${specSuffix}.yml` - ); - const staticJsonSpecPath = staticSpecPath.replace('.yml', '.json'); - - // Tag specs directory - const tagSpecsBase = isDualApi - ? path.join(staticBasePath, product.staticDirName, api.sectionSlug) - : path.join(staticBasePath, product.staticDirName); - - // Article data - const articlesPath = path.join( - DOCS_ROOT, - 'data/article_data/influxdb', - product.staticDirName, - api.sectionSlug - ); - - // Download path for frontmatter - const specDownloadPath = `/openapi/${product.staticDirName}${specSuffix}.yml`; - - // Path spec files for per-operation rendering - const pathSpecsDir = isDualApi - ? path.join(staticBasePath, product.staticDirName, api.sectionSlug, 'paths') - : path.join(staticBasePath, product.staticDirName, 'paths'); - - // --- 2. Read and transform spec --- - - if (!fs.existsSync(api.specFile)) { - console.warn(`⚠️ Spec file not found: ${api.specFile}`); - return; - } - - const specContent = fs.readFileSync(api.specFile, 'utf8'); - const specObject = yaml.load(specContent) as Record; - - const productPath = `/${product.productDir}`; - const transformedSpec = transformDocLinks(specObject, productPath); - console.log( - `✓ Transformed documentation links for ${api.apiKey} to ${productPath}` - ); - - // Validate links if enabled - if (validateLinks) { - const contentDir = path.join(DOCS_ROOT, 'content'); - const linkErrors = validateDocLinks(transformedSpec, contentDir); - if (linkErrors.length > 0) { - console.warn(`\n⚠️ Link validation warnings for ${api.specFile}:`); - linkErrors.forEach((err) => console.warn(` ${err}`)); - } - } - - // --- 3. Write transformed spec to static folder --- - - if (!fs.existsSync(staticBasePath)) { - fs.mkdirSync(staticBasePath, { recursive: true }); - } - - fs.writeFileSync(staticSpecPath, yaml.dump(transformedSpec)); - console.log(`✓ Wrote transformed spec to ${staticSpecPath}`); - - fs.writeFileSync( - staticJsonSpecPath, - JSON.stringify(transformedSpec, null, 2) - ); - console.log(`✓ Generated JSON spec at ${staticJsonSpecPath}`); - - // --- 4. Generate tag-based data --- - - console.log( - `\n📋 Generating tag-based data for ${api.apiKey} in ${tagSpecsBase}...` - ); - openapiPathsToHugo.generateHugoDataByTag({ - specFile: staticSpecPath, - dataOutPath: tagSpecsBase, - articleOutPath: articlesPath, - includePaths: true, - }); - - // Generate path-specific specs - openapiPathsToHugo.generatePathSpecificSpecs(staticSpecPath, pathSpecsDir); - - // --- 5. Generate Hugo content pages --- - - generateTagPagesFromArticleData({ - articlesPath, - contentPath: product.pagesDir, - sectionSlug: api.sectionSlug, - menuKey: product.menuKey, - menuParent: 'InfluxDB HTTP API', - skipParentMenu: product.skipParentMenu, - specDownloadPath, - articleDataKey: product.staticDirName, - articleSection: api.sectionSlug, - }); -} - -/** - * Process a single product: clean outputs and process each API section. - */ -function processProduct( - product: DiscoveredProduct, - allStaticDirNames: string[] -): void { - console.log('\n' + '='.repeat(80)); - console.log(`Processing ${product.productName}`); - console.log('='.repeat(80)); - - // Clean output directories before regeneration - if (!noClean && !dryRun) { - cleanProductOutputs(product, allStaticDirNames); - } - - const staticBasePath = path.join(DOCS_ROOT, 'static/openapi'); - - // Fetch specs if needed - if (!skipFetch) { - const getswaggerScript = path.join(API_DOCS_ROOT, 'getswagger.sh'); - if (fs.existsSync(getswaggerScript)) { - // The build function in generate-api-docs.sh handles per-product - // fetching. When called standalone, use product directory name. - execCommand( - `cd ${API_DOCS_ROOT} && ./getswagger.sh ${product.productDir} -B`, - `Fetching OpenAPI spec for ${product.productName}` - ); - } else { - console.log(`⚠️ getswagger.sh not found, skipping fetch step`); - } - } else { - console.log(`⏭️ Skipping getswagger.sh (--skip-fetch flag set)`); - } - - // Process each API section independently - for (const api of product.apis) { - processApiSection(product, api, staticBasePath); - } - - console.log(`\n✅ Successfully processed ${product.productName}\n`); -} - -// --------------------------------------------------------------------------- -// Main -// --------------------------------------------------------------------------- - -function main(): void { - const args = process.argv.slice(2).filter((arg) => !arg.startsWith('--')); - - // Discover all products from .config.yml files - const allProducts = discoverProducts(); - - if (allProducts.length === 0) { - console.error( - '❌ No products discovered. Ensure .config.yml files exist under api-docs/.' - ); - process.exit(1); - } - - // Determine which products to process - let productsToProcess: DiscoveredProduct[]; - - if (args.length === 0) { - productsToProcess = allProducts; - console.log( - `\n📋 Discovered ${allProducts.length} products, processing all...\n` - ); - } else { - // Match by staticDirName or productDir - productsToProcess = []; - const invalid: string[] = []; - - for (const arg of args) { - const found = allProducts.find( - (p) => - p.staticDirName === arg || - p.productDir === arg || - p.productDir.replace(/\//g, '-') === arg - ); - if (found) { - productsToProcess.push(found); + // Generate Hugo content pages from (merged) article data + if (config.useTagBasedGeneration) { + generateTagPagesFromArticleData({ + articlesPath: mergedArticlesPath, + contentPath: config.pagesDir, + menuKey: config.menuKey, + menuParent: 'InfluxDB HTTP API', + skipParentMenu: config.skipParentMenu, + pathSpecFiles: allPathSpecFiles, + }); } else { - invalid.push(arg); + generatePagesFromArticleData({ + articlesPath: mergedArticlesPath, + contentPath: config.pagesDir, + menuKey: config.menuKey, + menuParent: 'InfluxDB HTTP API', + skipParentMenu: config.skipParentMenu, + }); } } - if (invalid.length > 0) { - console.error( - `\n❌ Unknown product identifier(s): ${invalid.join(', ')}` - ); - console.error('\nDiscovered products:'); - allProducts.forEach((p) => { - console.error( - ` - ${p.staticDirName} (${p.productName}) [${p.productDir}]` - ); - }); - process.exit(1); - } - console.log( - `\n📋 Processing specified products: ${productsToProcess.map((p) => p.staticDirName).join(', ')}\n` + `\n✅ Successfully processed ${config.description || productKey}\n` + ); + } catch (error) { + console.error(`\n❌ Error processing ${productKey}:`, error); + process.exit(1); + } +} + +/** + * Main execution function + */ +function main(): void { + // Filter out CLI flags from arguments + const args = process.argv.slice(2).filter((arg) => !arg.startsWith('--')); + + // Determine which products to process + let productsToProcess: string[]; + + if (args.length === 0) { + // No arguments: process all products + productsToProcess = Object.keys(productConfigs); + console.log('\n📋 Processing all products...\n'); + } else { + // Arguments provided: process only specified products + productsToProcess = args; + console.log( + `\n📋 Processing specified products: ${productsToProcess.join(', ')}\n` ); } - // Collect all staticDirNames for prefix-safe cleanup - const allStaticDirNames = allProducts.map((p) => p.staticDirName); + // Validate product keys + const invalidProducts = productsToProcess.filter( + (key) => !productConfigs[key] + ); + if (invalidProducts.length > 0) { + console.error( + `\n❌ Invalid product identifier(s): ${invalidProducts.join(', ')}` + ); + console.error('\nValid products:'); + Object.keys(productConfigs).forEach((key) => { + console.error(` - ${key}: ${productConfigs[key].description}`); + }); + process.exit(1); + } // Handle dry-run mode if (dryRun) { console.log('\n📋 DRY RUN MODE - No files will be modified\n'); - productsToProcess.forEach((p) => showDryRunPreview(p, allStaticDirNames)); + productsToProcess.forEach((productKey) => { + showDryRunPreview(productKey, productConfigs[productKey]); + }); console.log('\nDry run complete. No files were modified.'); return; } // Process each product - productsToProcess.forEach((product) => { - processProduct(product, allStaticDirNames); + productsToProcess.forEach((productKey) => { + const config = productConfigs[productKey]; + processProduct(productKey, config); }); console.log('\n' + '='.repeat(80)); @@ -1134,16 +1599,14 @@ if (require.main === module) { // Export for use as a module export { - discoverProducts, + productConfigs, processProduct, - processApiSection, + generateDataFromOpenAPI, + generatePagesFromArticleData, + deriveProductPath, transformDocLinks, validateDocLinks, resolveContentPath, - deriveStaticDirName, - getSectionSlug, - parseApiEntry, - readMenuKey, MARKDOWN_FIELDS, LINK_PATTERN, };