legacy.yml

openapi: 3.0.0
info:
  title: Influx Legacy API
  version: 2.0.1
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
servers:
  - url: ''
paths:
  /query:
    get:
      operationId: GetLegacyQuery
      tags:
        - Legacy Query
      summary: Query with the 1.x compatibility API
      description: Queries InfluxDB using InfluxQL.
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: header
          name: Accept
          schema:
            type: string
            description: |
              Media type that the client can understand.

              **Note**: With `application/csv`, query results include [**unix timestamps**]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#unix-timestamp) instead of [RFC3339 timestamps]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp).
            default: application/json
            enum:
              - application/json
              - application/csv
              - text/csv
              - application/x-msgpack
        - in: header
          name: Accept-Encoding
          description: The content encoding (usually a compression algorithm) that the client can understand.
          schema:
            type: string
            description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.'
            default: identity
            enum:
              - gzip
              - identity
        - in: header
          name: Content-Type
          schema:
            type: string
            enum:
              - application/json
        - in: query
          name: u
          description: The InfluxDB 1.x username to authenticate the request.
          schema:
            type: string
        - in: query
          name: p
          description: The InfluxDB 1.x password to authenticate the request.
          schema:
            type: string
        - in: query
          name: db
          required: true
          description: |
            The database to query data from.
            This is mapped to an InfluxDB [bucket]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#bucket).
            For more information, see [Database and retention policy mapping]({{% INFLUXDB_DOCS_URL %}}/api/influxdb-1x/dbrp/).
          schema:
            type: string
        - in: query
          name: rp
          description: |
            The retention policy to query data from.
            This is mapped to an InfluxDB [bucket]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#bucket).
            For more information, see [Database and retention policy mapping]({{% INFLUXDB_DOCS_URL %}}/api/influxdb-1x/dbrp/).
          schema:
            type: string
        - in: query
          name: q
          required: true
          description: 'The InfluxQL query to execute. To execute multiple queries, delimit queries with a semicolon (`;`).'
          schema:
            type: string
        - in: query
          name: epoch
          description: |
            A unix timestamp precision.
            Formats timestamps as [unix (epoch) timestamps]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#unix-timestamp) the specified precision
            instead of [RFC3339 timestamps]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp) with nanosecond precision.
          schema:
            type: string
            enum:
              - ns
              - u
              - µ
              - ms
              - s
              - m
              - h
      responses:
        '200':
          description: Query results
          headers:
            Content-Encoding:
              description: Lists encodings (usually compression algorithms) that have been applied to the response payload.
              schema:
                type: string
                description: |
                  The content coding:
                    - `gzip`: compressed data
                    - `identity`: unmodified, uncompressed data.
                default: identity
                enum:
                  - gzip
                  - identity
            Transfer-Encoding:
              description: |
                `chunked` if the response is chunked.
              schema:
                type: string
                description: The transfer encoding.
                default: chunked
                enum:
                  - chunked
            Trace-Id:
              description: 'The trace ID, if generated, of the request.'
              schema:
                type: string
                description: Trace ID of a request.
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/InfluxqlCsvResponse'
            application/csv:
              schema:
                $ref: '#/components/schemas/InfluxqlCsvResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/InfluxqlJsonResponse'
              examples:
                influxql-chunk_size_2:
                  value: |
                    {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
                    {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
            application/x-msgpack:
              schema:
                type: string
                format: binary
        '429':
          description: |
            #### InfluxDB Cloud:
              - returns this error if a **read** or **write** request exceeds your
                plan's [adjustable service quotas]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#adjustable-service-quotas)
                or if a **delete** request exceeds the maximum
                [global limit]({{% INFLUXDB_DOCS_URL %}}/account-management/limits/#global-limits)
              - returns `Retry-After` header that describes when to try the write again.

            #### InfluxDB OSS:
              - doesn't return this error.
          headers:
            Retry-After:
              description: A non-negative decimal integer indicating the seconds to delay after the response is received.
              schema:
                type: integer
                format: int32
        default:
          description: Error processing query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /write:
    post:
      operationId: PostLegacyWrite
      tags:
        - Legacy Write
      summary: Write time series data into InfluxDB in a V1-compatible format
      requestBody:
        description: Line protocol body
        required: true
        content:
          text/plain:
            schema:
              type: string
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: query
          name: u
          description: The InfluxDB 1.x username to authenticate the request.
          schema:
            type: string
        - in: query
          name: p
          description: The InfluxDB 1.x password to authenticate the request.
          schema:
            type: string
        - in: query
          name: db
          schema:
            type: string
          required: true
          description: 'Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.'
        - in: query
          name: rp
          schema:
            type: string
          description: Retention policy name.
        - in: query
          name: precision
          schema:
            type: string
          description: Write precision.
        - in: header
          name: Content-Encoding
          description: 'When present, its value indicates to the database that compression is applied to the line protocol body.'
          schema:
            type: string
            description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
            default: identity
            enum:
              - gzip
              - identity
      responses:
        '204':
          description: Write data is correctly formatted and accepted for writing to the bucket.
        '400':
          description: Line protocol poorly formed and no points were written.  Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineProtocolError'
        '401':
          description: Token doesn't have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: No token was sent and they are required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineProtocolLengthError'
        '429':
          description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
          headers:
            Retry-After:
              description: A non-negative decimal integer indicating the seconds to delay after the response is received.
              schema:
                type: integer
                format: int32
        '503':
          description: Server is temporarily unavailable to accept writes.  The Retry-After header describes when to try the write again.
          headers:
            Retry-After:
              description: A non-negative decimal integer indicating the seconds to delay after the response is received.
              schema:
                type: integer
                format: int32
        default:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /legacy/authorizations:
    servers:
      - url: /private
    get:
      operationId: GetLegacyAuthorizations
      tags:
        - Legacy Authorizations
      summary: List all legacy authorizations
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: query
          name: userID
          schema:
            type: string
          description: |
            A user ID.
            Only returns legacy authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).
        - in: query
          name: user
          schema:
            type: string
          description: |
            A user name.
            Only returns legacy authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).
        - in: query
          name: orgID
          schema:
            type: string
          description: |
            An organization ID.
            Only returns legacy authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).
        - in: query
          name: org
          schema:
            type: string
          description: |
            An organization name.
            Only returns legacy authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).
        - in: query
          name: token
          schema:
            type: string
          description: |
            An authorization name token.
            Only returns legacy authorizations with the specified name.
        - in: query
          name: authID
          schema:
            type: string
          description: |
            An authorization ID.
            Returns the specified legacy authorization.
      responses:
        '200':
          description: Success. The response body contains a list of legacy `authorizations`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  links:
                    readOnly: true
                    $ref: '#/components/schemas/Links'
                  authorizations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Authorization'
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
    post:
      operationId: PostLegacyAuthorizations
      tags:
        - Legacy Authorizations
      summary: Create a legacy authorization
      description: |
        Creates a legacy authorization and returns the legacy authorization.

        #### Required permissions

        - `write-users USER_ID` if you pass the `userID` property in the request body.

        *`USER_ID`* is the ID of the user that you want to scope the authorization to.
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
      requestBody:
        description: The legacy authorization to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegacyAuthorizationPostRequest'
      responses:
        '201':
          description: |
            Created. The legacy authorization is created.
            The response body contains the newly created legacy authorization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'
        '400':
          description: Invalid request
          $ref: '#/components/responses/ServerError'
        '401':
          description: |
            Unauthorized.
            The API token passed doesn't have the permissions necessary for the
            request.
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      The HTTP status code description. Default is `unauthorized`.
                    readOnly: true
                    type: string
                    enum:
                      - unauthorized
                  message:
                    readOnly: true
                    description: A human-readable message that may contain detail about the error.
                    type: string
              examples:
                unauthorizedWriteUsers:
                  summary: 'The token doesn''t have the write:user permission'
                  value:
                    code: unauthorized
                    message: 'write:users/08028e90933bf000 is unauthorized'
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
  '/legacy/authorizations/{authID}':
    servers:
      - url: /private
    get:
      operationId: GetLegacyAuthorizationsID
      tags:
        - Legacy Authorizations
      summary: Retrieve a legacy authorization
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: path
          name: authID
          schema:
            type: string
          required: true
          description: The ID of the legacy authorization to get.
      responses:
        '200':
          description: Legacy authorization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
    patch:
      operationId: PatchLegacyAuthorizationsID
      tags:
        - Legacy Authorizations
      summary: Update a legacy authorization to be active or inactive
      requestBody:
        description: Legacy authorization to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizationUpdateRequest'
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: path
          name: authID
          schema:
            type: string
          required: true
          description: The ID of the legacy authorization to update.
      responses:
        '200':
          description: The active or inactive legacy authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authorization'
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
    delete:
      operationId: DeleteLegacyAuthorizationsID
      tags:
        - Legacy Authorizations
      summary: Delete a legacy authorization
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: path
          name: authID
          schema:
            type: string
          required: true
          description: The ID of the legacy authorization to delete.
      responses:
        '204':
          description: Legacy authorization deleted
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
  '/legacy/authorizations/{authID}/password':
    servers:
      - url: /private
    post:
      operationId: PostLegacyAuthorizationsIDPassword
      tags:
        - Legacy Authorizations
      summary: Set a legacy authorization password
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - in: path
          name: authID
          schema:
            type: string
          required: true
          description: The ID of the legacy authorization to update.
      requestBody:
        description: New password
        required: true
        content:
          application/json:
            schema:
              properties:
                password:
                  type: string
              required:
                - password
      responses:
        '204':
          description: Legacy authorization password set
        default:
          description: Unexpected error
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    TraceSpan:
      in: header
      name: Zap-Trace-Span
      description: OpenTracing span context
      example:
        trace_id: '1'
        span_id: '1'
        baggage:
          key: value
      required: false
      schema:
        type: string
  schemas:
    LegacyAuthorizationPostRequest:
      required:
        - orgID
        - permissions
      allOf:
        - $ref: '#/components/schemas/AuthorizationUpdateRequest'
        - type: object
          properties:
            orgID:
              type: string
              description: The organization ID. Identifies the organization that the authorization is scoped to.
            userID:
              type: string
              description: The user ID. Identifies the user that the authorization is scoped to.
            token:
              type: string
              description: The name that you provide for the authorization.
            permissions:
              type: array
              minItems: 1
              description: |
                The list of permissions that provide `read` and `write` access to organization resources.
                An authorization must contain at least one permission.
              items:
                $ref: '#/components/schemas/Permission'
    InfluxqlJsonResponse:
      description: |
        The JSON response for an InfluxQL query.

        A response contains the collection of results for a query.
        `results` is an array of resultset objects.

        If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
      type: object
      properties:
        results:
          type: array
          oneOf:
            - required:
                - statement_id
                - error
            - required:
                - statement_id
                - series
          items:
            type: object
            description: |
              A resultset object that contains the `statement_id` and the `series` array.

              Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
            properties:
              statement_id:
                type: integer
                description: |
                  An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
              error:
                type: string
              series:
                type: array
                description: |
                  An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.

                  If a property is not present, it is assumed to be `null`.
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the series
                    tags:
                      type: object
                      description: |
                        A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
                      additionalProperties:
                        type: string
                    partial:
                      type: boolean
                      description: |
                        True if the series is not complete--the response data is chunked; otherwise, false or omitted.
                    columns:
                      type: array
                      description: An array of column names
                      items:
                        type: string
                    values:
                      type: array
                      description: |
                        An array of rows, where each row is an array of values.
                      items:
                        type: array
                        items: {}
              partial:
                type: boolean
                description: |
                  True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
    InfluxqlCsvResponse:
      description: CSV Response to InfluxQL Query
      type: string
      example: |
        name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
    Authorization:
      required:
        - orgID
        - permissions
      allOf:
        - $ref: '#/components/schemas/AuthorizationUpdateRequest'
        - type: object
          properties:
            createdAt:
              type: string
              format: date-time
              readOnly: true
            updatedAt:
              type: string
              format: date-time
              readOnly: true
            orgID:
              type: string
              description: |
                The organization ID.
                Specifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that the authorization is scoped to.
            permissions:
              type: array
              minItems: 1
              description: |
                The list of permissions.
                An authorization must have at least one permission.
              items:
                $ref: '#/components/schemas/Permission'
            id:
              readOnly: true
              type: string
              description: The authorization ID.
            token:
              readOnly: true
              type: string
              description: |
                The API token.
                The token value is unique to the authorization.
                [API tokens]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) are
                used to authenticate and authorize InfluxDB API requests and `influx`
                CLI commands--after receiving the request, InfluxDB checks that the
                token is valid and that the `permissions` allow the requested action(s).
            userID:
              readOnly: true
              type: string
              description: 'The user ID. Specifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.'
            user:
              readOnly: true
              type: string
              description: |
                The user name.
                Specifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the authorization.
                If the authorization is _scoped_ to a user, the user;
                otherwise, the creator of the authorization.
            org:
              readOnly: true
              type: string
              description: |
                The organization name.
                Specifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)
                that the token is scoped to.
            links:
              type: object
              readOnly: true
              example:
                self: /api/v2/authorizations/1
                user: /api/v2/users/12
              properties:
                self:
                  readOnly: true
                  $ref: '#/components/schemas/Link'
                user:
                  readOnly: true
                  $ref: '#/components/schemas/Link'
    AuthorizationUpdateRequest:
      properties:
        status:
          description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.'
          default: active
          type: string
          enum:
            - active
            - inactive
        description:
          type: string
          description: A description of the token.
    Permission:
      required:
        - action
        - resource
      properties:
        action:
          type: string
          enum:
            - read
            - write
        resource:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - authorizations
                - buckets
                - dashboards
                - orgs
                - tasks
                - telegrafs
                - users
                - variables
                - secrets
                - labels
                - views
                - documents
                - notificationRules
                - notificationEndpoints
                - checks
                - dbrp
                - annotations
                - sources
                - scrapers
                - notebooks
                - remotes
                - replications
                - instance
                - flows
                - functions
                - subscriptions
              description: |
                A resource type.
                Identifies the API resource's type (or _kind_).
            id:
              type: string
              description: |
                A resource ID.
                Identifies a specific resource.
            name:
              type: string
              description: |
                The name of the resource.
                _Note: not all resource types have a `name` property_.
            orgID:
              type: string
              description: |
                An organization ID.
                Identifies the organization that owns the resource.
            org:
              type: string
              description: |
                An organization name.
                The organization that owns the resource.
    Links:
      type: object
      description: |
        URI pointers for additional paged results.
      properties:
        next:
          $ref: '#/components/schemas/Link'
        self:
          $ref: '#/components/schemas/Link'
        prev:
          $ref: '#/components/schemas/Link'
      required:
        - self
    Link:
      type: string
      format: uri
      readOnly: true
      description: URI of resource.
    LineProtocolError:
      properties:
        code:
          description: Code is the machine-readable error code.
          readOnly: true
          type: string
          enum:
            - internal error
            - not found
            - conflict
            - invalid
            - empty value
            - unavailable
        message:
          readOnly: true
          description: Human-readable message.
          type: string
        op:
          readOnly: true
          description: Describes the logical code operation when the error occurred. Useful for debugging.
          type: string
        err:
          readOnly: true
          description: Stack of errors that occurred during processing of the request. Useful for debugging.
          type: string
        line:
          readOnly: true
          description: First line in the request body that contains malformed data.
          type: integer
          format: int32
      required:
        - code
    LineProtocolLengthError:
      properties:
        code:
          description: Code is the machine-readable error code.
          readOnly: true
          type: string
          enum:
            - invalid
        message:
          readOnly: true
          description: Human-readable message.
          type: string
      required:
        - code
        - message
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          readOnly: true
          description: Human-readable message.
          type: string
        op:
          readOnly: true
          description: Describes the logical code operation when the error occurred. Useful for debugging.
          type: string
        err:
          readOnly: true
          description: Stack of errors that occurred during processing of the request. Useful for debugging.
          type: string
      required:
        - code
    ErrorCode:
      description: code is the machine-readable error code.
      readOnly: true
      type: string
      enum:
        - internal error
        - not implemented
        - not found
        - conflict
        - invalid
        - unprocessable entity
        - empty value
        - unavailable
        - forbidden
        - too many requests
        - unauthorized
        - method not allowed
        - request too large
        - unsupported media type
  responses:
    ServerError:
      description: Non 2XX error response from server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'