oss.yml

openapi: "3.0.0"
info:
  title: InfluxDB OSS API Service
  version: 2.0.0
  description: |
    The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
servers:
  - url: /api/v2
#REF_OSS_TAGS
#REF_OSS_TAG_GROUPS
paths:
#REF_COMMON_PATHS
  /debug/pprof/all:
    $ref: "./oss/paths/debug_pprof_all.yml"
  /debug/pprof/allocs:
    $ref: "./oss/paths/debug_pprof_allocs.yml"
  /debug/pprof/block:
    $ref: "./oss/paths/debug_pprof_block.yml"
  /debug/pprof/cmdline:
    $ref: "./oss/paths/debug_pprof_cmdline.yml"
  /debug/pprof/goroutine:
    $ref: "./oss/paths/debug_pprof_goroutine.yml"
  /debug/pprof/heap:
    $ref: "./oss/paths/debug_pprof_heap.yml"
  /debug/pprof/mutex:
    $ref: "./oss/paths/debug_pprof_mutex.yml"
  /debug/pprof/profile:
    $ref: "./oss/paths/debug_pprof_profile.yml"
  /debug/pprof/threadcreate:
    $ref: "./oss/paths/debug_pprof_threadcreate.yml"
  /debug/pprof/trace:
    $ref: "./oss/paths/debug_pprof_trace.yml"
  /health:
    $ref: "./oss/paths/health.yml"
  /metrics:
    $ref: "./oss/paths/metrics.yml"
  /ready:
    $ref: "./oss/paths/ready.yml"
  /users:
    $ref: "./common/paths/users.yml"
  "/users/{userID}":
    $ref: "./common/paths/users_userID.yml"
  /setup:
    $ref: "./common/paths/setup.yml"
  /variables:
    $ref: "./common/paths/variables.yml"
  "/variables/{variableID}":
    $ref: "./common/paths/variables_variableID.yml"
  /sources:
    $ref: "./common/paths/sources.yml"
  /sources/{sourceID}:
    $ref: "./common/paths/sources_sourceID.yml"
  /sources/{sourceID}/health:
    $ref: "./common/paths/sources_sourceID_health.yml"
  /sources/{sourceID}/buckets:
    $ref: "./common/paths/sources_sourceID_buckets.yml"
  /scrapers:
    $ref: "./common/paths/scrapers.yml"
  "/scrapers/{scraperTargetID}":
    $ref: "./common/paths/scrapers_scraperTargetID.yml"
  "/scrapers/{scraperTargetID}/labels":
    $ref: "./common/paths/scrapers_scraperTargetID_labels.yml"
  "/scrapers/{scraperTargetID}/labels/{labelID}":
    $ref: "./common/paths/scrapers_scraperTargetID_labels_labelID.yml"
  "/scrapers/{scraperTargetID}/members":
    $ref: "./common/paths/scrapers_scraperTargetID_members.yml"
  "/scrapers/{scraperTargetID}/members/{userID}":
    $ref: "./common/paths/scrapers_scraperTargetID_members_userID.yml"
  "/scrapers/{scraperTargetID}/owners":
    $ref: "./common/paths/scrapers_scraperTargetID_owners.yml"
  "/scrapers/{scraperTargetID}/owners/{userID}":
    $ref: "./common/paths/scrapers_scraperTargetID_owners_userID.yml"
  "/backup/kv":
    $ref: "./oss/paths/backup_kv.yml"
  "/backup/metadata":
    $ref: "./oss/paths/backup_metadata.yml"
  "/backup/shards/{shardID}":
    $ref: "./oss/paths/backup_shards_shardID.yml"
  "/restore/kv":
    $ref: "./oss/paths/restore_kv.yml"
  "/restore/sql":
    $ref: "./oss/paths/restore_sql.yml"
  "/restore/bucket/{bucketID}":
    $ref: "./oss/paths/restore_bucket_bucketID.yml"
  "/restore/bucketMetadata":
    $ref: "./oss/paths/restore_bucketMetadata.yml"
  "/restore/shards/{shardID}":
    $ref: "./oss/paths/restore_shards_shardID.yml"
  "/config":
    $ref: "./oss/paths/config.yml"
  /remotes:
    $ref: "./oss/paths/remotes.yml"
  /remotes/{remoteID}:
    $ref: "./oss/paths/remotes_remoteID.yml"
  /replications:
    $ref: "./oss/paths/replications.yml"
  /replications/{replicationID}:
    $ref: "./oss/paths/replications_replicationID.yml"
  /replications/{replicationID}/validate:
    $ref: "./oss/paths/replications_replicationID_validate.yml"
  /dashboards:
    $ref: "./common/paths/dashboards.yml"
  /tasks:
    $ref: "./common/paths/tasks.yml"
  "/tasks/{taskID}":
    $ref: "./common/paths/tasks_taskID.yml"
components:
  parameters:
  #REF_COMMON_PARAMETERS
  schemas:
  #REF_COMMON_SCHEMAS
    User:
      $ref: "./common/schemas/User.yml"
    Users:
      $ref: "./common/schemas/Users.yml"
    OnboardingRequest:
      $ref: "./common/schemas/OnboardingRequest.yml"
    OnboardingResponse:
      $ref: "./common/schemas/OnboardingResponse.yml"
    Variable:
      $ref: "./common/schemas/Variable.yml"
    Variables:
      $ref: "./common/schemas/Variables.yml"
    Source:
      $ref: "./common/schemas/Source.yml"
    Sources:
      $ref: "./common/schemas/Sources.yml"
    ScraperTargetRequest:
      $ref: "./common/schemas/ScraperTargetRequest.yml"
    ScraperTargetResponse:
      $ref: "./common/schemas/ScraperTargetResponse.yml"
    ScraperTargetResponses:
      $ref: "./common/schemas/ScraperTargetResponses.yml"
    MetadataBackup:
      $ref: "./oss/schemas/MetadataBackup.yml"
    BucketMetadataManifests:
      $ref: "./oss/schemas/BucketMetadataManifests.yml"
    BucketMetadataManifest:
      $ref: "./oss/schemas/BucketMetadataManifest.yml"
    RetentionPolicyManifests:
      $ref: "./oss/schemas/RetentionPolicyManifests.yml"
    RetentionPolicyManifest:
      $ref: "./oss/schemas/RetentionPolicyManifest.yml"
    ShardGroupManifests:
      $ref: "./oss/schemas/ShardGroupManifests.yml"
    ShardGroupManifest:
      $ref: "./oss/schemas/ShardGroupManifest.yml"
    ShardManifests:
      $ref: "./oss/schemas/ShardManifests.yml"
    ShardManifest:
      $ref: "./oss/schemas/ShardManifest.yml"
    ShardOwners:
      $ref: "./oss/schemas/ShardOwners.yml"
    ShardOwner:
      $ref: "./oss/schemas/ShardOwner.yml"
    SubscriptionManifests:
      $ref: "./oss/schemas/SubscriptionManifests.yml"
    SubscriptionManifest:
      $ref: "./oss/schemas/SubscriptionManifest.yml"
    RestoredBucketMappings:
      $ref: "./oss/schemas/RestoredBucketMappings.yml"
    BucketShardMappings:
      $ref: "./oss/schemas/BucketShardMappings.yml"
    BucketShardMapping:
      $ref: "./oss/schemas/BucketShardMapping.yml"
    Config:
      $ref: "./oss/schemas/Config.yml"
    RemoteConnection:
      $ref: "./oss/schemas/RemoteConnection.yml"
    RemoteConnections:
      $ref: "./oss/schemas/RemoteConnections.yml"
    RemoteConnectionCreationRequest:
      $ref: "./oss/schemas/RemoteConnectionCreationRequest.yml"
    RemoteConnectionUpdateRequest:
      $ref: "./oss/schemas/RemoteConnectionUpdateRequest.yml"
    Replication:
      $ref: "./oss/schemas/Replication.yml"
    Replications:
      $ref: "./oss/schemas/Replications.yml"
    ReplicationCreationRequest:
      $ref: "./oss/schemas/ReplicationCreationRequest.yml"
    ReplicationUpdateRequest:
      $ref: "./oss/schemas/ReplicationUpdateRequest.yml"
    Tasks:
      $ref: "./common/schemas/Tasks.yml"
    Task:
      $ref: "./common/schemas/Task.yml"
    TaskCreateRequest:
      $ref: "./common/schemas/TaskCreateRequest.yml"
    TaskUpdateRequest:
      $ref: "./common/schemas/TaskUpdateRequest.yml"
  responses:
    #REF_COMMON_RESPONSES
  examples:
    AuthorizationPostRequest:
      $ref: "./common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationPostRequest"
    AuthorizationWithResourcePostRequest:
      $ref: "./common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithResourcePostRequest"
    AuthorizationWithUserPostRequest:
      $ref: "./common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithUserPostRequest"
    TaskWithFluxRequest:
      $ref: "./common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest"
  securitySchemes:
    # TODO: Uncomment when Bearer auth is also available in Cloud:
    # BearerAuthentication:
    #   type: http
    #   scheme: "bearer"
    #   description: |
    #     Use the [Bearer authentication](#section/Authentication/BearerAuthentication)
    #     scheme to authenticate to the InfluxDB API.
    #
    #     In your API requests, send an `Authorization` header.
    #     For the header value, provide the word `Bearer` followed by a space and an InfluxDB API token.
    #
    #     ### Syntax
    #
    #     `Authorization: Bearer YOUR_INFLUX_API_TOKEN`
    #
    #     For more information and examples, see the following:
    #
    #     - [`/authorizations`(#tag/Authorizations-(API-tokens)) endpoints]
    #     - [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)
    #     - [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)
    TokenAuthentication:
      type: apiKey
      name: Authorization
      in: header
      description: |
        Use the [Token authentication](#section/Authentication/TokenAuthentication)
        scheme to authenticate to the InfluxDB API.

        In your API requests, send an `Authorization` header.
        For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
        The word `Token` is case-sensitive.

        ### Syntax

        `Authorization: Token INFLUX_API_TOKEN`

        ### Example

        #### Use Token authentication with cURL

        The following example shows how to use cURL to send an API request that uses Token authentication:

        ```sh
        curl --request GET "INFLUX_URL/api/v2/buckets" \
            --header "Authorization: Token INFLUX_API_TOKEN"
        ```

        Replace the following:

          - *`INFLUX_URL`*: your InfluxDB URL
          - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)

        ### Related endpoints

        - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))

        ### Related guides

        - [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)
        - [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)
    BasicAuthentication:
      type: http
      scheme: basic
      description: |
        ### Basic authentication scheme

        Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it:

        ### Syntax

        `Authorization: Basic BASE64_ENCODED_CREDENTIALS`

        To construct the `BASE64_ENCODED_CREDENTIALS`, combine the username and
        the password with a colon (`USERNAME:PASSWORD`), and then encode the
        resulting string in [base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64).
        Many HTTP clients encode the credentials for you before sending the
        request.

        _**Warning**: Base64-encoding can easily be reversed to obtain the original
        username and password. It is used to keep the data intact and does not provide
        security. You should always use HTTPS when authenticating or sending a request with
        sensitive information._

        ### Examples

        In the examples, replace the following:

        - **`USERNAME`**: InfluxDB username
        - **`PASSWORD`**: InfluxDB [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)
        - **`INFLUX_URL`**: your InfluxDB URL

        #### Encode credentials with cURL

        The following example shows how to use cURL to send an API request that uses Basic authentication.
        With the `--user` option, cURL encodes the credentials and passes them
        in the `Authorization: Basic` header.

        ```sh
        curl --get "INFLUX_URL/api/v2/signin"
            --user "USERNAME":"PASSWORD"
        ```

        #### Encode credentials with Flux

        The Flux [`http.basicAuth()` function](https://docs.influxdata.com/flux/v0.x/stdlib/http/basicauth/) returns a Base64-encoded
        basic authentication header using a specified username and password combination.

        #### Encode credentials with JavaScript

        The following example shows how to use the JavaScript `btoa()` function
        to create a Base64-encoded string:

        ```js
        btoa('USERNAME:PASSWORD')
        ```

        The output is the following:

        ```js
        'VVNFUk5BTUU6UEFTU1dPUkQ='
        ```

        Once you have the Base64-encoded credentials, you can pass them in the
        `Authorization` header--for example:

        ```sh
        curl --get "INFLUX_URL/api/v2/signin"
            --header "Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ="
        ```

        To learn more about HTTP authentication, see
        [Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._
security:
  - TokenAuthentication: []
  # TODO: Uncomment when Bearer auth is also available in Cloud:
  # - BearerAuthentication: []