InfluxDB Bucket Schemas API

openapi: 3.2.0
info:
  title: Complete InfluxDB Cloud Bucket Schemas API
servers:
- url: ''
security:
- TokenAuthentication: []
tags:
- name: Bucket Schemas
paths:
  /api/v2/buckets/{bucketID}/schema/measurements:
    summary: Bucket schemas
    get:
      description: 'Lists _explicit_

        schemas

        (`"schemaType": "explicit"`) for a bucket.


        _Explicit_ schemas are used to enforce column names, tags, fields, and data

        types for your data.


        By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`)

        that conforms to your data.


        #### Related guides


        - Using bucket schemas'
      operationId: getMeasurementSchemas
      parameters:
      - description: 'An organization name.

          Specifies the organization that owns the schema.

          '
        in: query
        name: org
        schema:
          type: string
      - description: 'An organization ID.

          Specifies the organization that owns the schema.

          '
        in: query
        name: orgID
        schema:
          type: string
      - description: 'A measurement name.

          Only returns measurement schemas with the specified name.

          '
        in: query
        name: name
        schema:
          type: string
      - description: 'A bucket ID.

          Lists measurement schemas for the specified bucket.

          '
        in: path
        name: bucketID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchemaList'
          description: A list of measurement schemas returning summary information.
          headers:
            ETag:
              description: The current version of the bucket schema
              schema:
                type: string
        '400':
          content:
            application/json:
              examples:
                invalidSchemaType:
                  summary: Invalid schema type.
                  value:
                    code: invalid
                    message: bucket schemaType must be explicit
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            '
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: List measurement schemas of a bucket
      tags:
      - Bucket Schemas
    post:
      description: 'Creates an _explict_ measurement schema

        for a bucket.


        _Explicit_ schemas are used to enforce column names, tags, fields, and data

        types for your data.


        By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`)

        that conforms to your data.


        Use this endpoint to create schemas that prevent non-conforming write requests.


        #### Limitations


        - Buckets must be created with the "explict" `schemaType` in order to use

        schemas.


        #### Related guides


        - Manage bucket schemas.

        - Create a bucket with an explicit schema'
      operationId: createMeasurementSchema
      parameters:
      - description: 'An organization name.

          Specifies the organization that owns the schema.

          '
        in: query
        name: org
        schema:
          type: string
      - description: 'An organization ID.

          Specifies the organization that owns the schema.

          '
        in: query
        name: orgID
        schema:
          type: string
      - description: 'A bucket ID.

          Adds a schema for the specified bucket.

          '
        in: path
        name: bucketID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementSchemaCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchema'
          description: The current version of the measurement schema.
          headers:
            ETag:
              description: The current version of the measurement schema
              schema:
                type: string
        '400':
          content:
            application/json:
              examples:
                badNameExample:
                  description: The error returned when the name is invalid, such as too few or too many characters or the name contains non-printable ASCII or is not valid UTF-8.
                  summary: Invalid name
                  value:
                    code: invalid
                    message: name is invalid
                duplicateColumnNamesExample:
                  description: The error returned when the request body contains duplicate column names.
                  summary: Duplicate column names
                  value:
                    code: invalid
                    message: Duplicate column names
                missingColumnsExample:
                  description: The error returned when the request body is missing the columns property.
                  summary: Missing columns
                  value:
                    code: invalid
                    message: columns is required
                missingFieldExample:
                  description: The error returned when the request body is missing at least one field type column.
                  summary: Missing field
                  value:
                    code: invalid
                    message: At least one field column is required
                missingTimestampExample:
                  description: The error returned when the request body is missing a timestamp type column.
                  summary: Missing timestamp
                  value:
                    code: invalid
                    message: Timestamp column is required
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            '
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Create a measurement schema for a bucket
      tags:
      - Bucket Schemas
      x-codeSamples:
      - label: cURL
        lang: Shell
        source: "curl --request POST \"INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \\\n  --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n  --header \"Accept: application/json\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n      \"name\": \"temperature\",\n      \"column\": [\n        {\n          \"type\": \"tag\",\n          \"name\": \"location\"\n        },\n        {\n          \"type\": \"field\",\n          \"name\": \"value\",\n          \"dataType\": \"float\"\n        },\n        {\n          \"type\": \"timestamp\",\n          \"name\": \"time\"\n        }\n      ]\n    }'\n"
  /api/v2/buckets/{bucketID}/schema/measurements/{measurementID}:
    summary: Bucket Schema
    get:
      description: Retrieves an explicit measurement schema.
      operationId: getMeasurementSchema
      parameters:
      - description: 'Organization name.

          Specifies the organization that owns the schema.

          '
        in: query
        name: org
        schema:
          type: string
      - description: 'Organization ID.

          Specifies the organization that owns the schema.

          '
        in: query
        name: orgID
        schema:
          type: string
      - description: 'A bucket ID.

          Retrieves schemas for the specified bucket.

          '
        in: path
        name: bucketID
        required: true
        schema:
          type: string
      - description: 'The measurement schema ID.

          Specifies the measurement schema to retrieve.

          '
        in: path
        name: measurementID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchema'
          description: Schema definition for a single measurement
          headers:
            ETag:
              description: The current version of the measurement schema
              schema:
                type: string
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Retrieve a measurement schema
      tags:
      - Bucket Schemas
    patch:
      description: 'Updates a measurement schema.


        Use this endpoint to update the fields (`name`, `type`, and `dataType`) of a

        measurement schema.


        #### Limitations


        - You can''t update the `name` of a measurement.


        #### Related guides


        - Manage bucket schemas.

        - Using bucket schemas.'
      operationId: updateMeasurementSchema
      parameters:
      - description: 'An organization name.

          Specifies the organization that owns the schema.

          '
        in: query
        name: org
        schema:
          type: string
      - description: 'An organization ID.

          Specifies the organization that owns the schema.

          '
        in: query
        name: orgID
        schema:
          type: string
      - description: 'A bucket ID.

          Specifies the bucket to retrieve schemas for.

          '
        in: path
        name: bucketID
        required: true
        schema:
          type: string
      - description: 'A measurement schema ID.

          Retrieves the specified measurement schema.

          '
        in: path
        name: measurementID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementSchemaUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchema'
          description: 'Success.

            The response body contains the measurement schema.

            '
        '400':
          content:
            application/json:
              examples:
                missingColumnsExample:
                  description: The error returned when the request body does not contain all the columns from the source.
                  summary: Deleted columns
                  value:
                    code: invalid
                    message: Unable to delete columns from schema
              schema:
                $ref: '#/components/schemas/Error'
          description: 'Bad request.

            '
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update a measurement schema
      tags:
      - Bucket Schemas
      x-codeSamples:
      - label: cURL
        lang: Shell
        source: "curl --request PATCH \"INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \\\n  --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n  --header \"Accept: application/json\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n      \"column\": [\n        {\n          \"type\": \"tag\",\n          \"name\": \"location\"\n        },\n        {\n          \"type\": \"field\",\n          \"name\": \"value\",\n          \"dataType\": \"float\"\n        },\n        {\n          \"type\": \"timestamp\",\n          \"name\": \"time\"\n        }\n      ]\n    }'\n"
components:
  schemas:
    ColumnDataType:
      enum:
      - integer
      - float
      - boolean
      - string
      - unsigned
      type: string
    MeasurementSchemaUpdateRequest:
      description: Update an existing measurement schema
      example:
        columns:
        - format: unix timestamp
          name: time
          type: integer
        - name: host
          type: tag
        - name: region
          type: tag
        - dataType: float
          name: usage_user
          type: field
        - dataType: float
          name: usage_user
          type: field
      properties:
        columns:
          description: An ordered collection of column definitions
          items:
            $ref: '#/components/schemas/MeasurementSchemaColumn'
          type: array
      required:
      - columns
      type: object
    MeasurementSchema:
      description: Definition of a measurement schema.
      example:
        bucketID: ba3c5e7f9b0a0010
        columns:
        - format: unix timestamp
          name: time
          type: integer
        - name: host
          type: tag
        - name: region
          type: tag
        - dataType: float
          name: usage_user
          type: field
        - dataType: float
          name: usage_user
          type: field
        createdAt: '2021-01-21T00:48:40.993Z'
        id: 1a3c5e7f9b0a8642
        name: cpu
        orgID: 0a3c5e7f9b0a0001
        updatedAt: '2021-01-21T00:48:40.993Z'
      properties:
        bucketID:
          description: The ID of the bucket that the measurement schema is associated with.
          type: string
        columns:
          description: Ordered collection of column definitions.
          items:
            $ref: '#/components/schemas/MeasurementSchemaColumn'
          type: array
        createdAt:
          format: date-time
          readOnly: true
          type: string
        id:
          readOnly: true
          type: string
        name:
          type: string
        orgID:
          description: The ID of the organization.
          type: string
        updatedAt:
          format: date-time
          readOnly: true
          type: string
      required:
      - id
      - name
      - columns
      - createdAt
      - updatedAt
      type: object
    MeasurementSchemaList:
      description: A list of measurement schemas returning summary information
      example:
        measurementSchemas:
        - bucketID: ba3c5e7f9b0a0010
          createdAt: '2021-01-21T00:48:40.993Z'
          id: 1a3c5e7f9b0a8642
          name: cpu
          orgID: 0a3c5e7f9b0a0001
          updatedAt: '2021-01-21T00:48:40.993Z'
        - bucketID: ba3c5e7f9b0a0010
          createdAt: '2021-01-21T00:48:40.993Z'
          id: 1a3c5e7f9b0a8643
          name: memory
          orgID: 0a3c5e7f9b0a0001
          updatedAt: '2021-01-21T00:48:40.993Z'
        - bucketID: ba3c5e7f9b0a0010
          createdAt: '2021-01-21T00:48:40.993Z'
          id: 1a3c5e7f9b0a8644
          name: disk
          orgID: 0a3c5e7f9b0a0001
          updatedAt: '2021-01-21T00:48:40.993Z'
      properties:
        measurementSchemas:
          items:
            $ref: '#/components/schemas/MeasurementSchema'
          type: array
      required:
      - measurementSchemas
      type: object
    MeasurementSchemaCreateRequest:
      description: Create a new measurement schema.
      example:
        columns:
        - format: unix timestamp
          name: time
          type: integer
        - name: host
          type: tag
        - name: region
          type: tag
        - dataType: float
          name: usage_user
          type: field
        - dataType: float
          name: usage_user
          type: field
        name: cpu
      properties:
        columns:
          description: Ordered collection of column definitions.
          items:
            $ref: '#/components/schemas/MeasurementSchemaColumn'
          type: array
        name:
          description: 'The [measurement](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#measurement)

            name.

            '
          type: string
      required:
      - name
      - columns
      type: object
    MeasurementSchemaColumn:
      description: Definition of a measurement schema column.
      example:
        format: unix timestamp
        name: time
        type: integer
      properties:
        dataType:
          $ref: '#/components/schemas/ColumnDataType'
        name:
          type: string
        type:
          $ref: '#/components/schemas/ColumnSemanticType'
      required:
      - name
      - type
      type: object
    ErrorCode:
      description: code is the machine-readable error code.
      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
      readOnly: true
      type: string
    ColumnSemanticType:
      enum:
      - timestamp
      - tag
      - field
      type: string
    Error:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: code is the machine-readable error code.
          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
          readOnly: true
          type: string
        err:
          description: Stack of errors that occurred during processing of the request. Useful for debugging.
          readOnly: true
          type: string
        message:
          description: Human-readable message.
          readOnly: true
          type: string
        op:
          description: Describes the logical code operation when the error occurred. Useful for debugging.
          readOnly: true
          type: string
      required:
      - code
  responses:
    InternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: 'Internal server error.

        The server encountered an unexpected situation.

        '
    AuthorizationError:
      content:
        application/json:
          examples:
            tokenNotAuthorized:
              summary: Token is not authorized to access a resource
              value:
                code: unauthorized
                message: unauthorized access
          schema:
            properties:
              code:
                description: 'The HTTP status code description. Default is `unauthorized`.

                  '
                enum:
                - unauthorized
                readOnly: true
                type: string
              message:
                description: A human-readable message that may contain detail about the error.
                readOnly: true
                type: string
      description: "Unauthorized. The error may indicate one of the following:\n\n  * The `Authorization: Token` header is missing or malformed.\n  * The API token value is missing from the header.\n  * The token doesn't have sufficient permissions to write to this organization and bucket.\n"
    ResourceNotFoundError:
      content:
        application/json:
          examples:
            bucket-not-found:
              summary: Bucket name not found
              value:
                code: not found
                message: bucket "air_sensor" not found
            org-not-found:
              summary: Organization name not found
              value:
                code: not found
                message: organization name "my-org" not found
            orgID-not-found:
              summary: Organization ID not found
              value:
                code: not found
                message: organization not found
          schema:
            $ref: '#/components/schemas/Error'
      description: "Not found.\nA requested resource was not found.\nThe response body contains the requested resource type and the name value\n(if you passed it)--for example:\n\n- `\"organization name \\\"my-org\\\" not found\"`\n- `\"organization not found\"`: indicates you passed an ID that did not match\n   an organization.\n"
  securitySchemes:
    BasicAuthentication:
      description: "### Basic authentication scheme\n\nUse the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it:\n\n### Syntax\n\n`Authorization: Basic BASE64_ENCODED_CREDENTIALS`\n\nTo construct the `BASE64_ENCODED_CREDENTIALS`, combine the username and\nthe password with a colon (`USERNAME:PASSWORD`), and then encode the\nresulting string in [base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64).\nMany HTTP clients encode the credentials for you before sending the\nrequest.\n\n_**Warning**: Base64-encoding can easily be reversed to obtain the original\nusername and password. It is used to keep the data intact and does not provide\nsecurity. You should always use HTTPS when authenticating or sending a request with\nsensitive information._\n\n### Examples\n\nIn the examples, replace the following:\n\n- **`EMAIL_ADDRESS`**: InfluxDB Cloud username (the email address the user signed up with)\n- **`PASSWORD`**: InfluxDB Cloud [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)\n- **`INFLUX_URL`**: your InfluxDB Cloud URL\n\n#### Encode credentials with cURL\n\nThe following example shows how to use cURL to send an API request that uses Basic authentication.\nWith the `--user` option, cURL encodes the credentials and passes them\nin the `Authorization: Basic` header.\n\n```sh\ncurl --get \"INFLUX_URL/api/v2/signin\"\n    --user \"EMAIL_ADDRESS\":\"PASSWORD\"\n```\n\n#### Encode credentials with Flux\n\nThe Flux [`http.basicAuth()` function](https://docs.influxdata.com/flux/v0.x/stdlib/http/basicauth/) returns a Base64-encoded\nbasic authentication header using a specified username and password combination.\n\n#### Encode credentials with JavaScript\n\nThe following example shows how to use the JavaScript `btoa()` function\nto create a Base64-encoded string:\n\n```js\nbtoa('EMAIL_ADDRESS:PASSWORD')\n```\n\nThe output is the following:\n\n```js\n'VVNFUk5BTUU6UEFTU1dPUkQ='\n```\n\nOnce you have the Base64-encoded credentials, you can pass them in the\n`Authorization` header--for example:\n\n```sh\ncurl --get \"INFLUX_URL/api/v2/signin\"\n    --header \"Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ=\"\n```\n\nTo learn more about HTTP authentication, see\n[Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._\n"
      scheme: basic
      type: http
    TokenAuthentication:
      description: "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n     --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n  - *`INFLUX_URL`*: your InfluxDB Cloud URL\n  - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))\n\n### Related guides\n\n- [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication)\n- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/)\n"
      in: header
      name: Authorization
      type: apiKey
x-tagGroups:
- name: Overview
  tags:
  - Quick start
  - Authentication
  - Supported operations
  - Headers
  - Pagination
  - Response codes
- name: Popular endpoints
  tags:
  - Data I/O endpoints
  - Security and access endpoints
  - System information endpoints
- name: All endpoints
  tags: []