--- 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: 5050 product: InfluxDB Cloud (TSM) version: cloud publisher: InfluxData canonical: https://docs.influxdata.com/influxdb/cloud/api/bucket-schemas/ --- [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`requiredstring 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 200A list of measurement schemas returning summary information. `measurementSchemas`requiredobject[] 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" } ] } ``` 400Bad request. `code`requiredstring 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`requiredstring 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. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring 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`requiredstring 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 bodyrequired Content-Type:`application/json` `columns`requiredobject[] Ordered collection of column definitions. `name`requiredstring 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 201The current version of the measurement schema. `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ 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" } ``` 400Bad request. `code`requiredstring 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`requiredstring 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. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring 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`requiredstring A bucket ID. Retrieves schemas for the specified bucket. `measurementID`requiredstring 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 200Schema definition for a single measurement `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ 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`requiredstring 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. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring 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`requiredstring A bucket ID. Specifies the bucket to retrieve schemas for. `measurementID`requiredstring 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 bodyrequired Content-Type:`application/json` `columns`requiredobject[] 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 200Success. The response body contains the measurement schema. `bucketID`string The ID of the bucket that the measurement schema is associated with. `columns`requiredobject[] Ordered collection of column definitions. `createdAt`requiredstring \ `id`requiredstring `name`requiredstring `orgID`string The ID of the organization. `updatedAt`requiredstring \ 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" } ``` 400Bad request. `code`requiredstring 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`requiredstring 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. 500Internal server error. The server encountered an unexpected situation. `code`requiredstring 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.