openapi: 3.0.0
info:
  title: InfluxDB Cloud API Service Authorizations (API tokens) Authorizations (API tokens) Bucket Schemas API
  version: 2.0.1
  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
security:
- TokenAuthentication: []
tags:
- name: Bucket Schemas
paths:
  /buckets/{bucketID}/schema/measurements:
    summary: Bucket schemas
    get:
      summary: List measurement schemas of a bucket
      description: 'Lists _explicit_

        [schemas](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#schema)

        (`"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](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/)

        '
      operationId: getMeasurementSchemas
      parameters:
      - in: query
        name: org
        description: 'An organization name.

          Specifies the organization that owns the schema.

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

          Specifies the organization that owns the schema.

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

          Only returns measurement schemas with the specified name.

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

          Lists measurement schemas for the specified bucket.

          '
        schema:
          type: string
        required: true
      tags:
      - Bucket Schemas
      responses:
        '200':
          description: A list of measurement schemas returning summary information.
          headers:
            ETag:
              description: The current version of the bucket schema
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchemaList'
        '400':
          description: 'Bad request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidSchemaType:
                  summary: Invalid schema type.
                  value:
                    code: invalid
                    message: bucket schemaType must be explicit
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create a measurement schema for a bucket
      description: 'Creates an _explict_ measurement [schema](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#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](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/bucket-schema/).

        - [Create a bucket with an explicit schema](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema)

        '
      operationId: createMeasurementSchema
      parameters:
      - in: query
        name: org
        description: 'An organization name.

          Specifies the organization that owns the schema.

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

          Specifies the organization that owns the schema.

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

          Adds a schema for the specified bucket.

          '
        schema:
          type: string
        required: true
      tags:
      - Bucket Schemas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementSchemaCreateRequest'
      responses:
        '201':
          description: The current version of the measurement schema.
          headers:
            ETag:
              description: The current version of the measurement schema
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchema'
        '400':
          description: 'Bad request.

            '
          content:
            application/json:
              examples:
                badNameExample:
                  summary: Invalid name
                  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.
                  value:
                    code: invalid
                    message: name is invalid
                missingColumnsExample:
                  summary: Missing columns
                  description: The error returned when the request body is missing the columns property.
                  value:
                    code: invalid
                    message: columns is required
                missingTimestampExample:
                  summary: Missing timestamp
                  description: The error returned when the request body is missing a timestamp type column.
                  value:
                    code: invalid
                    message: Timestamp column is required
                duplicateColumnNamesExample:
                  summary: Duplicate column names
                  description: The error returned when the request body contains duplicate column names.
                  value:
                    code: invalid
                    message: Duplicate column names
                missingFieldExample:
                  summary: Missing field
                  description: The error returned when the request body is missing at least one field type column.
                  value:
                    code: invalid
                    message: At least one field column is required
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-codeSamples:
      - lang: Shell
        label: cURL
        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"
  /buckets/{bucketID}/schema/measurements/{measurementID}:
    summary: Bucket Schema
    get:
      summary: Retrieve a measurement schema
      description: 'Retrieves an explicit measurement [schema](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#schema).

        '
      operationId: getMeasurementSchema
      parameters:
      - in: query
        name: org
        description: 'Organization name.

          Specifies the organization that owns the schema.

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

          Specifies the organization that owns the schema.

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

          Retrieves schemas for the specified bucket.

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

          Specifies the measurement schema to retrieve.

          '
        schema:
          type: string
        required: true
      tags:
      - Bucket Schemas
      responses:
        '200':
          description: Schema definition for a single measurement
          headers:
            ETag:
              description: The current version of the measurement schema
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchema'
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      summary: Update a measurement schema
      description: 'Updates a measurement [schema](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#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](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/bucket-schema/).

        - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/).

        '
      operationId: updateMeasurementSchema
      parameters:
      - in: query
        name: org
        description: 'An organization name.

          Specifies the organization that owns the schema.

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

          Specifies the organization that owns the schema.

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

          Specifies the bucket to retrieve schemas for.

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

          Retrieves the specified measurement schema.

          '
        schema:
          type: string
        required: true
      tags:
      - Bucket Schemas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementSchemaUpdateRequest'
      responses:
        '200':
          description: 'Success.

            The response body contains the measurement schema.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementSchema'
        '400':
          description: 'Bad request.

            '
          content:
            application/json:
              examples:
                missingColumnsExample:
                  summary: Deleted columns
                  description: The error returned when the request body does not contain all the columns from the source.
                  value:
                    code: invalid
                    message: Unable to delete columns from schema
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/AuthorizationError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-codeSamples:
      - lang: Shell
        label: cURL
        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:
    MeasurementSchemaColumn:
      description: Definition of a measurement schema column.
      example:
        name: time
        type: integer
        format: unix timestamp
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/ColumnSemanticType'
        dataType:
          $ref: '#/components/schemas/ColumnDataType'
    MeasurementSchemaList:
      description: A list of measurement schemas returning summary information
      example:
        measurementSchemas:
        - id: 1a3c5e7f9b0a8642
          orgID: 0a3c5e7f9b0a0001
          bucketID: ba3c5e7f9b0a0010
          name: cpu
          createdAt: '2021-01-21T00:48:40.993Z'
          updatedAt: '2021-01-21T00:48:40.993Z'
        - id: 1a3c5e7f9b0a8643
          orgID: 0a3c5e7f9b0a0001
          bucketID: ba3c5e7f9b0a0010
          name: memory
          createdAt: '2021-01-21T00:48:40.993Z'
          updatedAt: '2021-01-21T00:48:40.993Z'
        - id: 1a3c5e7f9b0a8644
          orgID: 0a3c5e7f9b0a0001
          bucketID: ba3c5e7f9b0a0010
          name: disk
          createdAt: '2021-01-21T00:48:40.993Z'
          updatedAt: '2021-01-21T00:48:40.993Z'
      type: object
      required:
      - measurementSchemas
      properties:
        measurementSchemas:
          type: array
          items:
            $ref: '#/components/schemas/MeasurementSchema'
    MeasurementSchemaUpdateRequest:
      description: Update an existing measurement schema
      type: object
      example:
        columns:
        - name: time
          type: integer
          format: unix timestamp
        - name: host
          type: tag
        - name: region
          type: tag
        - name: usage_user
          type: field
          dataType: float
        - name: usage_user
          type: field
          dataType: float
      required:
      - columns
      properties:
        columns:
          description: An ordered collection of column definitions
          type: array
          items:
            $ref: '#/components/schemas/MeasurementSchemaColumn'
    ColumnSemanticType:
      type: string
      nullable: false
      enum:
      - timestamp
      - tag
      - field
    ColumnDataType:
      type: string
      enum:
      - integer
      - float
      - boolean
      - string
      - unsigned
    MeasurementSchema:
      description: Definition of a measurement schema.
      type: object
      example:
        id: 1a3c5e7f9b0a8642
        orgID: 0a3c5e7f9b0a0001
        bucketID: ba3c5e7f9b0a0010
        name: cpu
        columns:
        - name: time
          type: integer
          format: unix timestamp
        - name: host
          type: tag
        - name: region
          type: tag
        - name: usage_user
          type: field
          dataType: float
        - name: usage_user
          type: field
          dataType: float
        createdAt: '2021-01-21T00:48:40.993Z'
        updatedAt: '2021-01-21T00:48:40.993Z'
      required:
      - id
      - name
      - columns
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          readOnly: true
        orgID:
          type: string
          description: The ID of the organization.
        bucketID:
          type: string
          description: The ID of the bucket that the measurement schema is associated with.
        name:
          type: string
          nullable: false
        columns:
          description: Ordered collection of column definitions.
          type: array
          items:
            $ref: '#/components/schemas/MeasurementSchemaColumn'
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    MeasurementSchemaCreateRequest:
      description: Create a new measurement schema.
      type: object
      example:
        name: cpu
        columns:
        - name: time
          type: integer
          format: unix timestamp
        - name: host
          type: tag
        - name: region
          type: tag
        - name: usage_user
          type: field
          dataType: float
        - name: usage_user
          type: field
          dataType: float
      required:
      - name
      - columns
      properties:
        name:
          description: 'The [measurement](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#measurement)

            name.

            '
          type: string
        columns:
          description: Ordered collection of column definitions.
          type: array
          items:
            $ref: '#/components/schemas/MeasurementSchemaColumn'
    Error:
      properties:
        code:
          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
        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
  responses:
    AuthorizationError:
      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"
      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:
            tokenNotAuthorized:
              summary: Token is not authorized to access a resource
              value:
                code: unauthorized
                message: unauthorized access
    ResourceNotFoundError:
      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"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            org-not-found:
              summary: Organization name not found
              value:
                code: not found
                message: organization name "my-org" not found
            bucket-not-found:
              summary: Bucket name not found
              value:
                code: not found
                message: bucket "air_sensor" not found
            orgID-not-found:
              summary: Organization ID not found
              value:
                code: not found
                message: organization not found
    InternalServerError:
      description: 'Internal server error.

        The server encountered an unexpected situation.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    TokenAuthentication:
      type: apiKey
      name: Authorization
      in: header
      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"
    BasicAuthentication:
      type: http
      scheme: basic
      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"
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: []