openapi: 3.0.0
info:
  title: InfluxDB v1 HTTP API for InfluxDB Cloud Serverless
  version: ''
  description: |
    The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.

    This documentation is generated from the
    [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).

    #### Related

    [InfluxDB `/api/v2` API for InfluxDB Cloud Serverless](/influxdb/cloud-serverless/api/v2/)
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  summary: The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB v3 Cloud Serverless bucket.
servers:
  - url: /
security:
  - TokenAuthentication: []
  - BasicAuthentication: []
  - QuerystringAuthentication: []
tags:
  - name: Authentication
    description: |
      The InfluxDB 1.x API requires authentication for all requests.
      InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.


      For more information, see the following:
      - [Token authentication](#section/Authentication/TokenAuthentication)
      - [Basic authentication](#section/Authentication/BasicAuthentication)
      - [Querystring authentication](#section/Authentication/QuerystringAuthentication)

      <!-- ReDoc-Inject: <security-definitions> -->
    x-traitTag: true
  - name: Query
  - name: Write
paths:
  /write:
    post:
      operationId: PostWriteV1
      tags:
        - 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'
        - $ref: '#/components/parameters/AuthUserV1'
        - $ref: '#/components/parameters/AuthPassV1'
        - 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 does not 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'
  /query:
    post:
      operationId: PostQueryV1
      tags:
        - Query
      summary: Query using the InfluxDB v1 HTTP API
      requestBody:
        description: InfluxQL query to execute.
        content:
          text/plain:
            schema:
              type: string
      parameters:
        - $ref: '#/components/parameters/TraceSpan'
        - $ref: '#/components/parameters/AuthUserV1'
        - $ref: '#/components/parameters/AuthPassV1'
        - in: header
          name: Accept
          schema:
            type: string
            description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
            default: application/json
            enum:
              - application/json
              - application/csv
              - text/csv
              - application/x-msgpack
        - in: header
          name: Accept-Encoding
          description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
          schema:
            type: string
            description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
            default: identity
            enum:
              - gzip
              - identity
        - in: header
          name: Content-Type
          schema:
            type: string
            enum:
              - application/vnd.influxql
        - in: query
          name: db
          schema:
            type: string
          required: true
          description: Bucket to query.
        - in: query
          name: rp
          schema:
            type: string
          description: Retention policy name.
        - in: query
          name: q
          description: Defines the influxql query to run.
          schema:
            type: string
      responses:
        '200':
          description: Query results
          headers:
            Content-Encoding:
              description: The Content-Encoding entity header is used to compress the media-type.  When present, its value indicates which encodings were applied to the entity-body
              schema:
                type: string
                description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
                default: identity
                enum:
                  - gzip
                  - identity
            Trace-Id:
              description: The Trace-Id header reports the request's trace ID, if one was generated.
              schema:
                type: string
                description: Specifies the request's trace ID.
          content:
            application/csv:
              schema:
                $ref: '#/components/schemas/InfluxQLCSVResponse'
            text/csv:
              schema:
                $ref: '#/components/schemas/InfluxQLCSVResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/InfluxQLResponse'
              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: Token is temporarily over quota. The Retry-After header describes when to try the read 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: Error processing query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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
    AuthUserV1:
      in: query
      name: u
      required: false
      schema:
        type: string
      description: Username.
    AuthPassV1:
      in: query
      name: p
      required: false
      schema:
        type: string
      description: User token.
  schemas:
    InfluxQLResponse:
      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.
      properties:
        results:
          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`.
          items:
            properties:
              error:
                type: string
              partial:
                description: |
                  True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
                type: boolean
              series:
                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:
                  properties:
                    columns:
                      description: An array of column names
                      items:
                        type: string
                      type: array
                    name:
                      description: The name of the series
                      type: string
                    partial:
                      description: |
                        True if the series is not complete--the response data is chunked; otherwise, false or omitted.
                      type: boolean
                    tags:
                      additionalProperties:
                        type: string
                      description: |
                        A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
                      type: object
                    values:
                      description: |
                        An array of rows, where each row is an array of values.
                      items:
                        items: {}
                        type: array
                      type: array
                  type: object
                type: array
              statement_id:
                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.
                type: integer
            type: object
          oneOf:
          - required:
            - statement_id
            - error
          - required:
            - statement_id
            - series
          type: array
      type: object
    InfluxQLCSVResponse:
      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
    Error:
      properties:
        code:
          description: Code is the machine-readable error code.
          readOnly: true
          type: string
          enum:
            - internal error
            - not found
            - conflict
            - invalid
            - unprocessable entity
            - empty value
            - unavailable
            - forbidden
            - too many requests
            - unauthorized
            - method not allowed
        message:
          readOnly: true
          description: Message is a human-readable message.
          type: string
      required:
        - code
        - message
    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: Message is a human-readable message.
          type: string
        op:
          readOnly: true
          description: Op describes the logical code operation during error. Useful for debugging.
          type: string
        err:
          readOnly: true
          description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
          type: string
        line:
          readOnly: true
          description: First line within sent body containing malformed data
          type: integer
          format: int32
      required:
        - code
        - message
        - op
        - err
    LineProtocolLengthError:
      properties:
        code:
          description: Code is the machine-readable error code.
          readOnly: true
          type: string
          enum:
            - invalid
        message:
          readOnly: true
          description: Message is a human-readable message.
          type: string
        maxLength:
          readOnly: true
          description: Max length in bytes for a body of line-protocol.
          type: integer
          format: int32
      required:
        - code
        - message
        - maxLength
  securitySchemes:
    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 YOUR_INFLUX_TOKEN`


        For examples and more information, see the following:
          - [`/authorizations`](#tag/Authorizations) endpoint.
          - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
          - [Manage API tokens](/influxdb/cloud/security/tokens/).
    BasicAuthentication:
      type: http
      scheme: basic
      description: |
        Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
        scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):


        For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
    QuerystringAuthentication:
      type: apiKey
      in: query
      name: u=&p=
      description: |
        Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
        scheme with InfluxDB 1.x API parameters to provide credentials through the query string.


        For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).