--- title: Bucket Schemas description: Manage explicit schemas for InfluxDB Cloud buckets to enforce column names and data types for measurement data. url: https://docs.influxdata.com/influxdb/cloud/api/bucket-schemas/ estimated_tokens: 15872 product: InfluxDB Cloud (TSM) version: cloud --- [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Manage explicit schemas for InfluxDB Cloud buckets to enforce column names and data types for measurement data. GET `/api/v2/buckets/{bucketID}/schema/measurements` ### List measurement schemas of a bucket Lists *explicit* [schemas](/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/) #### Parameters ##### Path parameters `bucketID` required string A bucket ID. Lists measurement schemas for the specified bucket. ##### Query parameters `org` string An organization name. Specifies the organization that owns the schema. `orgID` string An organization ID. Specifies the organization that owns the schema. `name` string A measurement name. Only returns measurement schemas with the specified name. Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 A list of measurement schemas returning summary information. `measurementSchemas` required object\[\] Example request body ```json { "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" } ] } ``` 400 Bad request. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: - The `Authorization: Token` header is missing or malformed. - The API token value is missing from the header. - The token doesn’t have sufficient permissions to write to this organization and bucket. `code` string The HTTP status code description. Default is `unauthorized`. Allowed: `unauthorized` `message` string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: - `"organization name \"my-org\" not found"` - `"organization not found"`: indicates you passed an ID that did not match an organization. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 500 Internal server error. The server encountered an unexpected situation. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. POST `/api/v2/buckets/{bucketID}/schema/measurements` ### Create a measurement schema for a bucket Creates an *explicit* measurement [schema](/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 “explicit” `schemaType` in order to use schemas. #### Related guides - [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). - [Create a bucket with an explicit schema](/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) #### Parameters ##### Path parameters `bucketID` required string A bucket ID. Adds a schema for the specified bucket. ##### Query parameters `org` string An organization name. Specifies the organization that owns the schema. `orgID` string An organization ID. Specifies the organization that owns the schema. #### Request body required Content-Type: `application/json` `columns` required object\[\] Ordered collection of column definitions. `name` required string The [measurement](/influxdb/cloud/reference/glossary/#measurement) name. Example request body ```json { "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" } ``` Example request [Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"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"}' ``` #### Responses 201 The current version of the measurement schema. `bucketID` string The ID of the bucket that the measurement schema is associated with. `columns` required object\[\] Ordered collection of column definitions. `createdAt` required string `id` required string `name` required string `orgID` string The ID of the organization. `updatedAt` required string Example request body ```json { "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" } ``` 400 Bad request. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: - The `Authorization: Token` header is missing or malformed. - The API token value is missing from the header. - The token doesn’t have sufficient permissions to write to this organization and bucket. `code` string The HTTP status code description. Default is `unauthorized`. Allowed: `unauthorized` `message` string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: - `"organization name \"my-org\" not found"` - `"organization not found"`: indicates you passed an ID that did not match an organization. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 500 Internal server error. The server encountered an unexpected situation. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. GET `/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}` ### Retrieve a measurement schema Retrieves an explicit measurement [schema](/influxdb/cloud/reference/glossary/#schema). #### Parameters ##### Path parameters `bucketID` required string A bucket ID. Retrieves schemas for the specified bucket. `measurementID` required string The measurement schema ID. Specifies the measurement schema to retrieve. ##### Query parameters `org` string Organization name. Specifies the organization that owns the schema. `orgID` string Organization ID. Specifies the organization that owns the schema. Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Schema definition for a single measurement `bucketID` string The ID of the bucket that the measurement schema is associated with. `columns` required object\[\] Ordered collection of column definitions. `createdAt` required string `id` required string `name` required string `orgID` string The ID of the organization. `updatedAt` required string Example request body ```json { "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" } ``` 401 Unauthorized. The error may indicate one of the following: - The `Authorization: Token` header is missing or malformed. - The API token value is missing from the header. - The token doesn’t have sufficient permissions to write to this organization and bucket. `code` string The HTTP status code description. Default is `unauthorized`. Allowed: `unauthorized` `message` string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: - `"organization name \"my-org\" not found"` - `"organization not found"`: indicates you passed an ID that did not match an organization. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 500 Internal server error. The server encountered an unexpected situation. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. PATCH `/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}` ### Update a measurement schema Updates a measurement [schema](/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](/influxdb/cloud/organizations/buckets/bucket-schema/). - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/). #### Parameters ##### Path parameters `bucketID` required string A bucket ID. Specifies the bucket to retrieve schemas for. `measurementID` required string A measurement schema ID. Retrieves the specified measurement schema. ##### Query parameters `org` string An organization name. Specifies the organization that owns the schema. `orgID` string An organization ID. Specifies the organization that owns the schema. #### Request body required Content-Type: `application/json` `columns` required object\[\] An ordered collection of column definitions Example request body ```json { "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" } ] } ``` Example request [Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/buckets/{bucketID}/schema/measurements/{measurementID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"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"}]}' ``` #### Responses 200 Success. The response body contains the measurement schema. `bucketID` string The ID of the bucket that the measurement schema is associated with. `columns` required object\[\] Ordered collection of column definitions. `createdAt` required string `id` required string `name` required string `orgID` string The ID of the organization. `updatedAt` required string Example request body ```json { "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" } ``` 400 Bad request. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 401 Unauthorized. The error may indicate one of the following: - The `Authorization: Token` header is missing or malformed. - The API token value is missing from the header. - The token doesn’t have sufficient permissions to write to this organization and bucket. `code` string The HTTP status code description. Default is `unauthorized`. Allowed: `unauthorized` `message` string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: - `"organization name \"my-org\" not found"` - `"organization not found"`: indicates you passed an ID that did not match an organization. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. 500 Internal server error. The server encountered an unexpected situation. `code` required string code is the machine-readable error code. Allowed: `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` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging.