Bucket Schemas

Download InfluxDB Cloud (TSM) API Spec
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 ("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.

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
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
{
  "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 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.

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 name.
Example request body
{
  "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
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 <date-time>
id required string
name required string
orgID string
The ID of the organization.
updatedAt required string <date-time>
Example request body
{
  "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.

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
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 <date-time>
id required string
name required string
orgID string
The ID of the organization.
updatedAt required string <date-time>
Example request body
{
  "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.

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.

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
{
  "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
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 <date-time>
id required string
name required string
orgID string
The ID of the organization.
updatedAt required string <date-time>
Example request body
{
  "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.

Was this page helpful?

Thank you for your feedback!