openapi: 3.0.0 info: title: InfluxDB Cloud API Service Authorizations (API tokens) Authorizations (API tokens) Buckets 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: Buckets description: 'Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets have a [retention period](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-period), a duration of time that each data point persists. InfluxDB drops all points with timestamps older than the bucket’s retention period. A bucket belongs to an organization. ### Related guides - [Manage buckets](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/) ' paths: /buckets: get: operationId: GetBuckets tags: - Buckets summary: List buckets description: "Lists [buckets](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#bucket).\n\nInfluxDB retrieves buckets owned by the\n[organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization)\nassociated with the authorization\n([API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)).\nTo limit which buckets are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all buckets up to the\ndefault `limit`.\n\n#### InfluxDB OSS\n\n- If you use an _[operator token](https://docs.influxdata.com/influxdb/cloud/security/tokens/#operator-token)_\n to authenticate your request, InfluxDB retrieves resources for _all\n organizations_ in the instance.\n To retrieve resources for only a specific organization, use the\n `org` parameter or the `orgID` parameter to specify the organization.\n\n#### Required permissions\n\n| Action | Permission required |\n|:--------------------------|:--------------------|\n| Retrieve _user buckets_ | `read-buckets` |\n| Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/cloud/reference/internals/system-buckets/) | `read-orgs` |\n\n#### Related Guides\n\n- [Manage buckets](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/After' - in: query name: org description: 'An organization name. #### InfluxDB Cloud - Doesn''t use the `org` parameter or `orgID` parameter. - Lists buckets for the organization associated with the authorization (API token). #### InfluxDB OSS - Lists buckets for the specified organization. ' schema: type: string - in: query name: orgID description: 'An organization ID. #### InfluxDB Cloud - Doesn''t use the `org` parameter or `orgID` parameter. - Lists buckets for the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or `orgID` parameter. - Lists buckets for the specified organization. ' schema: type: string - in: query name: name description: 'A bucket name. Only returns buckets with the specified name. ' schema: type: string - in: query name: id description: 'A bucket ID. Only returns the bucket with the specified ID. ' schema: type: string responses: '200': description: 'Success. The response body contains a list of `buckets`. ' content: application/json: schema: $ref: '#/components/schemas/Buckets' examples: successResponse: value: links: self: /api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID buckets: - id: 77ca9dace40a9bfc orgID: INFLUX_ORG_ID type: system schemaType: implicit description: System bucket for monitoring logs name: _monitoring retentionRules: - type: expire everySeconds: 604800 createdAt: '2022-03-15T17:22:33.72617939Z' updatedAt: '2022-03-15T17:22:33.726179487Z' links: labels: /api/v2/buckets/77ca9dace40a9bfc/labels members: /api/v2/buckets/77ca9dace40a9bfc/members org: /api/v2/orgs/INFLUX_ORG_ID owners: /api/v2/buckets/77ca9dace40a9bfc/owners self: /api/v2/buckets/77ca9dace40a9bfc write: /api/v2/write?org=ORG_ID&bucket=77ca9dace40a9bfc labels: [] '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: 'cURL: filter buckets by name' source: "curl --request GET \"http://localhost:8086/api/v2/buckets?name=_monitoring\" \\\n --header \"Authorization: Token INFLUX_TOKEN\" \\\n --header \"Accept: application/json\" \\\n --header \"Content-Type: application/json\"\n" post: operationId: PostBuckets tags: - Buckets summary: Create a bucket description: 'Creates a [bucket](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#bucket) and returns the bucket resource. The default data [retention period](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-period) is 30 days. #### InfluxDB OSS - A single InfluxDB OSS instance supports active writes or queries for approximately 20 buckets across all organizations at a given time. Reading or writing to more than 20 buckets at a time can adversely affect performance. #### Limitations - InfluxDB Cloud Free Plan allows users to create up to two buckets. Exceeding the bucket quota will result in an HTTP `403` status code. For additional information regarding InfluxDB Cloud offerings, see [InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). #### Related Guides - [Create a bucket](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/create-bucket/) - [Create bucket CLI reference](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/bucket/create) ' parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: The bucket to create. required: true content: application/json: schema: $ref: '#/components/schemas/PostBucketRequest' responses: '201': description: 'Success. The bucket is created. ' content: application/json: schema: $ref: '#/components/schemas/Bucket' examples: successResponse: value: id: 37407e232b3911d8 orgID: INFLUX_ORG_ID type: user schemaType: implicit description: A bucket holding air sensor data name: air_sensor retentionRules: - type: expire everySeconds: 2592000 createdAt: '2022-08-03T23:04:41.073704121Z' updatedAt: '2022-08-03T23:04:41.073704228Z' links: labels: /api/v2/buckets/37407e232b3911d8/labels members: /api/v2/buckets/37407e232b3911d8/members org: /api/v2/orgs/INFLUX_ORG_ID owners: /api/v2/buckets/37407e232b3911d8/owners self: /api/v2/buckets/37407e232b3911d8 write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 labels: [] '400': description: 'Bad request. ' content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/AuthorizationError' '403': description: 'Forbidden. The bucket quota is exceeded. ' headers: X-Platform-Error-Code: description: 'The reason for the error. ' schema: type: string example: forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: quotaExceeded: summary: Bucket quota exceeded value: code: forbidden message: creating bucket would exceed quota '422': description: 'Unprocessable Entity. The request body failed validation. ' content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: 'cURL: create a bucket with retention period' source: "curl --request POST \"http://localhost:8086/api/v2/buckets \\\n --header \"Authorization: Token INFLUX_TOKEN\" \\\n --header \"Accept: application/json\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"air_sensor\",\n \"description\": \"A bucket holding air sensor data\",\n \"orgID\": \"INFLUX_ORG_ID\",\n \"retentionRules\": [\n {\n \"type\": \"expire\",\n \"everySeconds\": 2592000,\n }\n ]\n }'\n" - lang: Shell label: cURL source: '' /buckets/{bucketID}: get: operationId: GetBucketsID tags: - Buckets summary: Retrieve a bucket description: 'Retrieves a bucket. Use this endpoint to retrieve information for a specific bucket. ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to retrieve. ' responses: '200': description: 'Success. The response body contains the bucket information. ' content: application/json: schema: $ref: '#/components/schemas/Bucket' examples: successResponse: value: id: 37407e232b3911d8 orgID: bea7ea952287f70d type: user schemaType: implicit description: bucket for air sensor data name: air-sensor retentionRules: - type: expire everySeconds: 2592000 createdAt: '2022-08-03T23:04:41.073704121Z' updatedAt: '2022-08-03T23:04:41.073704228Z' links: labels: /api/v2/buckets/37407e232b3911d8/labels members: /api/v2/buckets/37407e232b3911d8/members org: /api/v2/orgs/INFLUX_ORG_ID owners: /api/v2/buckets/37407e232b3911d8/owners self: /api/v2/buckets/37407e232b3911d8 write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 labels: [] '401': $ref: '#/components/responses/AuthorizationError' '404': description: 'Not found. Bucket not found. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: 'The requested bucket wasn''t found. ' value: code: not found message: bucket not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchBucketsID tags: - Buckets summary: Update a bucket description: 'Updates a bucket. Use this endpoint to update properties (`name`, `description`, and `retentionRules`) of a bucket. #### InfluxDB Cloud - Requires the `retentionRules` property in the request body. If you don''t provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. #### InfluxDB OSS - Doesn''t require `retentionRules`. #### Related Guides - [Update a bucket](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/update-bucket/) ' requestBody: description: The bucket update to apply. required: true content: application/json: schema: $ref: '#/components/schemas/PatchBucketRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: The bucket ID. responses: '200': description: An updated bucket content: application/json: schema: $ref: '#/components/schemas/Bucket' examples: successResponse: value: id: 37407e232b3911d8 orgID: INFLUX_ORG_ID type: user schemaType: implicit description: bucket holding air sensor data name: air_sensor retentionRules: - type: expire everySeconds: 2592000 createdAt: '2022-08-03T23:04:41.073704121Z' updatedAt: '2022-08-07T22:49:49.422962913Z' links: labels: /api/v2/buckets/37407e232b3911d8/labels members: /api/v2/buckets/37407e232b3911d8/members org: /api/v2/orgs/INFLUX_ORG_ID owners: /api/v2/buckets/37407e232b3911d8/owners self: /api/v2/buckets/37407e232b3911d8 write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 labels: [] '400': description: 'Bad Request. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidJSONStringValue: summary: Invalid JSON description: 'If the request body contains invalid JSON, InfluxDB returns `invalid` with detail about the problem. ' value: code: invalid message: 'invalid json: invalid character ''\'''' looking for beginning of value' '401': $ref: '#/components/responses/AuthorizationError' '403': description: 'Forbidden. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRetention: summary: 'The retention policy provided exceeds the max retention for the organization. ' value: code: forbidden message: provided retention exceeds orgs maximum retention duration '404': description: 'Not found. Bucket not found. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: 'The requested bucket wasn''t found. ' value: code: not found message: bucket not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: cURL source: "curl --request PATCH \"http://localhost:8086/api/v2/buckets/BUCKET_ID \\\n --header \"Authorization: Token INFLUX_TOKEN\" \\\n --header \"Accept: application/json\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"air_sensor\",\n \"description\": \"bucket holding air sensor data\",\n \"retentionRules\": [\n {\n \"type\": \"expire\",\n \"everySeconds\": 2592000\n }\n ]\n }'\n" delete: operationId: DeleteBucketsID tags: - Buckets summary: Delete a bucket description: "Deletes a bucket and all associated records.\n\n#### InfluxDB Cloud\n\n- Does the following when you send a delete request:\n\n 1. Validates the request and queues the delete.\n 2. Returns an HTTP `204` status code if queued; _error_ otherwise.\n 3. Handles the delete asynchronously.\n\n#### InfluxDB OSS\n\n- Validates the request, handles the delete synchronously,\nand then responds with success or failure.\n\n#### Limitations\n\n- Only one bucket can be deleted per request.\n\n#### Related Guides\n\n- [Delete a bucket](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'Bucket ID. The ID of the bucket to delete. ' responses: '204': description: "Success.\n\n#### InfluxDB Cloud\n - The bucket is queued for deletion.\n\n#### InfluxDB OSS\n - The bucket is deleted.\n" '400': description: 'Bad Request. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidID: summary: 'Invalid ID. ' value: code: invalid message: id must have a length of 16 bytes '401': $ref: '#/components/responses/AuthorizationError' '404': description: 'Not found. Bucket not found. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: 'The requested bucket was not found. ' value: code: not found message: bucket not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: cURL source: "curl --request DELETE \"http://localhost:8086/api/v2/buckets/BUCKET_ID\" \\\n --header \"Authorization: Token INFLUX_TOKEN\" \\\n --header 'Accept: application/json'\n" /buckets/{bucketID}/labels: get: operationId: GetBucketsIDLabels tags: - Buckets summary: List all labels for a bucket description: 'Lists all labels for a bucket. Labels are objects that contain `labelID`, `name`, `description`, and `color` key-value pairs. They may be used for grouping and filtering InfluxDB resources. Labels are also capable of grouping across different resources--for example, you can apply a label named `air_sensor` to a bucket and a task to quickly organize resources. #### Related guides - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/cloud/visualize-data/labels/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to retrieve labels for. ' responses: '200': description: 'Success. The response body contains a list of all labels for the bucket. ' content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' examples: successResponse: value: links: self: /api/v2/labels labels: - id: 09cbd068e7ebb000 orgID: INFLUX_ORG_ID name: production_buckets '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostBucketsIDLabels tags: - Buckets summary: Add a label to a bucket description: "Adds a label to a bucket and returns the new label information.\n\nLabels are objects that contain `labelID`, `name`, `description`, and `color`\nkey-value pairs. They may be used for grouping and filtering across one or\nmore kinds of **resources**--for example, you can apply a label named\n`air_sensor` to a bucket and a task to quickly organize resources.\n\n#### Limitations\n\n- Before adding a label to a bucket, you must create the label if you\n haven't already. To create a label with the InfluxDB API, send a `POST`\n request to the [`/api/v2/labels` endpoint](#operation/PostLabels)).\n\n#### Related guides\n\n- Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels.\n- [Manage labels in the InfluxDB UI](https://docs.influxdata.com/influxdb/cloud/visualize-data/labels/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'Bucket ID. The ID of the bucket to label. ' requestBody: description: An object that contains a _`labelID`_ to add to the bucket. required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: 'Success. The response body contains the label information. ' content: application/json: schema: $ref: '#/components/schemas/LabelResponse' examples: successResponse: value: links: self: /api/v2/labels label: id: 09cbd068e7ebb000 orgID: INFLUX_ORG_ID name: production_buckets '400': $ref: '#/components/responses/BadRequestError' examples: invalidRequest: summary: The `labelID` is missing from the request body. value: code: invalid message: label id is required '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '422': description: 'Unprocessable entity. Label already exists on the resource. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: conflictingResource: summary: 'Label already exists on the resource. ' value: code: conflict message: Cannot add label, label already exists on resource '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: cURL source: "curl --request POST \"http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \\\n --header \"Authorization: Token INFLUX_TOKEN\" \\\n --header \"Accept: application/json\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"labelID\": \"09cbd068e7ebb000\"\n }'\n" /buckets/{bucketID}/labels/{labelID}: delete: operationId: DeleteBucketsIDLabelsID tags: - Buckets summary: Delete a label from a bucket parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: The bucket ID. - in: path name: labelID schema: type: string required: true description: The ID of the label to delete. responses: '204': description: Delete has been accepted '404': description: Bucket not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /buckets/{bucketID}/members: get: operationId: GetBucketsIDMembers tags: - Buckets summary: List all users with member privileges for a bucket description: 'Lists all users for a bucket. InfluxDB [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#member) are users in an organization with access to the specified resource. Use this endpoint to retrieve all users with access to a bucket. #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/users/) - [Manage members](https://docs.influxdata.com/influxdb/cloud/organizations/members/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to retrieve users for. ' responses: '200': description: 'Success. The response body contains a list of all users for the bucket. ' content: application/json: schema: $ref: '#/components/schemas/ResourceMembers' examples: successResponse: value: links: self: /api/v2/buckets/37407e232b3911d8/members users: - role: member links: self: /api/v2/users/791df274afd48a83 id: 791df274afd48a83 name: example_user_1 status: active - role: owner links: self: /api/v2/users/09cfb87051cbe000 id: 09cfb87051cbe000 name: example_user_2 status: active '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostBucketsIDMembers tags: - Buckets summary: Add a member to a bucket description: 'Add a user to a bucket and return the new user information. InfluxDB [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) have permission to access InfluxDB. [Members](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#member) are users in an organization. Use this endpoint to give a user member privileges to a bucket. #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/users/) - [Manage members](https://docs.influxdata.com/influxdb/cloud/organizations/members/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to retrieve users for. ' requestBody: description: A user to add as a member to the bucket. required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: 'Success. The response body contains the user information. ' content: application/json: schema: $ref: '#/components/schemas/ResourceMember' examples: successResponse: value: role: member links: self: /api/v2/users/09cfb87051cbe000 id: 09cfb87051cbe000 name: example_user_1 status: active '400': $ref: '#/components/responses/BadRequestError' examples: invalidRequest: summary: The user `id` is missing from the request body. value: code: invalid message: user id missing or invalid '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: cURL source: "curl --request POST \"http://localhost:8086/api/v2/buckets/BUCKET_ID/members \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header \"Accept: application/json\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"id\": \"09cfb87051cbe000\"\n }\n" /buckets/{bucketID}/members/{userID}: delete: operationId: DeleteBucketsIDMembersID tags: - Buckets summary: Remove a member from a bucket description: 'Removes a member from a bucket. Use this endpoint to remove a user''s member privileges from a bucket. This removes the user''s `read` and `write` permissions for the bucket. #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/users/) - [Manage members](https://docs.influxdata.com/influxdb/cloud/organizations/members/) ' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: 'The ID of the user to remove. ' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to remove a user from. ' responses: '204': description: 'Success. The user is no longer a member of the bucket. ' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /buckets/{bucketID}/owners: get: operationId: GetBucketsIDOwners tags: - Buckets summary: List all owners of a bucket description: "Lists all [owners](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users](https://docs.influxdata.com/influxdb/cloud/users/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to retrieve owners for. ' responses: '200': description: 'Success. The response body contains a list of all owners for the bucket. ' content: application/json: schema: $ref: '#/components/schemas/ResourceOwners' examples: successResponse: value: links: self: /api/v2/buckets/BUCKET_ID/owners users: - role: owner links: self: /api/v2/users/d88d182d91b0950f id: d88d182d91b0950f name: example-owner status: active '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostBucketsIDOwners tags: - Buckets summary: Add an owner to a bucket description: "Adds an owner to a bucket and returns the [owners](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users](https://docs.influxdata.com/influxdb/cloud/users/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to add an owner for. ' requestBody: description: A user to add as an owner for the bucket. required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' examples: successResponse: value: role: owner links: self: /api/v2/users/d88d182d91b0950f id: d88d182d91b0950f name: example-user status: active responses: '201': description: 'Created. The bucket `owner` role is assigned to the user. The response body contains the resource owner with role and user detail. ' content: application/json: schema: $ref: '#/components/schemas/ResourceOwner' '400': $ref: '#/components/responses/BadRequestError' examples: invalidRequest: summary: The user `id` is missing from the request body. value: code: invalid message: user id missing or invalid '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: cURL source: "curl --request POST \"http://localhost:8086/api/v2/buckets/BUCKET_ID/owners \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header \"Accept: application/json\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"id\": \"09cfb87051cbe000\"\n }\n" /buckets/{bucketID}/owners/{userID}: delete: operationId: DeleteBucketsIDOwnersID tags: - Buckets summary: Remove an owner from a bucket description: "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users](https://docs.influxdata.com/influxdb/cloud/users/)\n" parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: 'The ID of the owner to remove. ' - in: path name: bucketID schema: type: string required: true description: 'The ID of the bucket to remove an owner from. ' responses: '204': description: 'Success. The user is no longer an owner of the bucket. ' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /sources/{sourceID}/buckets: get: operationId: GetSourcesIDBuckets tags: - Buckets summary: Get buckets in a source parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: sourceID schema: type: string required: true description: The source ID. - in: query name: org description: The name of the organization. schema: type: string responses: '200': description: A source content: application/json: schema: $ref: '#/components/schemas/Buckets' '404': description: Source not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RetentionRule: type: object properties: type: type: string default: expire enum: - expire everySeconds: type: integer format: int64 description: 'The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). 0 represents infinite retention. ' example: 86400 default: 2592000 minimum: 0 shardGroupDurationSeconds: type: integer format: int64 description: 'The shard group duration. The duration or interval (in seconds) that each shard group covers. #### InfluxDB Cloud - Does not use `shardGroupDurationsSeconds`. #### InfluxDB OSS - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). ' required: - everySeconds Bucket: properties: links: type: object readOnly: true example: labels: /api/v2/buckets/1/labels members: /api/v2/buckets/1/members org: /api/v2/orgs/2 owners: /api/v2/buckets/1/owners self: /api/v2/buckets/1 write: /api/v2/write?org=2&bucket=1 properties: labels: description: The URL to retrieve labels for this bucket. $ref: '#/components/schemas/Link' members: description: The URL to retrieve members that can read this bucket. $ref: '#/components/schemas/Link' org: description: The URL to retrieve parent organization for this bucket. $ref: '#/components/schemas/Link' owners: description: The URL to retrieve owners that can read and write to this bucket. $ref: '#/components/schemas/Link' self: description: The URL for this bucket. $ref: '#/components/schemas/Link' write: description: The URL to write line protocol to this bucket. $ref: '#/components/schemas/Link' id: readOnly: true type: string type: readOnly: true type: string default: user enum: - user - system name: type: string description: type: string orgID: type: string rp: type: string schemaType: $ref: '#/components/schemas/SchemaType' default: implicit createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true retentionRules: $ref: '#/components/schemas/RetentionRules' labels: $ref: '#/components/schemas/Labels' required: - name - retentionRules AddResourceMemberRequestBody: type: object properties: id: type: string description: 'The ID of the user to add to the resource. ' name: type: string description: 'The name of the user to add to the resource. ' required: - id Link: type: string format: uri readOnly: true description: URI of resource. ResourceMembers: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/ResourceMember' Links: type: object description: 'URI pointers for additional paged results. ' properties: next: $ref: '#/components/schemas/Link' self: $ref: '#/components/schemas/Link' prev: $ref: '#/components/schemas/Link' required: - self ResourceMember: allOf: - $ref: '#/components/schemas/UserResponse' - type: object properties: role: type: string default: member enum: - member PatchRetentionRule: type: object properties: type: type: string default: expire enum: - expire everySeconds: type: integer format: int64 description: 'The number of seconds to keep data. Default duration is `2592000` (30 days). `0` represents infinite retention. ' example: 86400 default: 2592000 minimum: 0 shardGroupDurationSeconds: type: integer format: int64 description: 'The [shard group duration](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#shard). The number of seconds that each shard group covers. #### InfluxDB Cloud - Doesn''t use `shardGroupDurationsSeconds`. #### InfluxDB OSS - Default value depends on the [bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). #### Related guides - InfluxDB [shards and shard groups](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/) ' required: - everySeconds SchemaType: type: string enum: - implicit - explicit Label: type: object properties: id: readOnly: true type: string orgID: readOnly: true type: string name: type: string properties: type: object additionalProperties: type: string description: 'Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. ' example: color: ffb3b3 description: this is a description ResourceOwners: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/ResourceOwner' RetentionRules: type: array description: 'Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-period). #### InfluxDB Cloud - `retentionRules` is required. #### InfluxDB OSS - `retentionRules` isn''t required. ' items: $ref: '#/components/schemas/RetentionRule' LabelMapping: type: object description: A _label mapping_ contains a `label` ID to attach to a resource. properties: labelID: description: 'A label ID. Specifies the label to attach. ' type: string required: - labelID Labels: type: array items: $ref: '#/components/schemas/Label' UserResponse: properties: id: readOnly: true type: string description: 'The user ID. ' name: type: string description: 'The user name. ' status: description: 'The status of a user. An inactive user can''t read or write resources. ' default: active type: string enum: - active - inactive links: type: object readOnly: true example: self: /api/v2/users/1 properties: self: type: string format: uri required: - name Buckets: type: object properties: links: readOnly: true $ref: '#/components/schemas/Links' buckets: type: array items: $ref: '#/components/schemas/Bucket' PatchBucketRequest: type: object description: 'An object that contains updated bucket properties to apply. ' properties: name: type: string description: 'The name of the bucket. ' description: description: 'A description of the bucket. ' type: string retentionRules: $ref: '#/components/schemas/PatchRetentionRules' ResourceOwner: allOf: - $ref: '#/components/schemas/UserResponse' - type: object properties: role: type: string default: owner enum: - owner LabelsResponse: type: object properties: labels: $ref: '#/components/schemas/Labels' links: $ref: '#/components/schemas/Links' PatchRetentionRules: type: array description: Updates to rules to expire or retain data. No rules means no updates. items: $ref: '#/components/schemas/PatchRetentionRule' PostBucketRequest: properties: orgID: description: 'The organization ID. Specifies the organization that owns the bucket. ' type: string name: description: 'The bucket name. ' type: string description: description: 'A description of the bucket. ' type: string rp: description: 'The retention policy for the bucket. For InfluxDB 1.x, specifies the duration of time that each data point in the retention policy persists. If you need compatibility with InfluxDB 1.x, specify a value for the `rp` property; otherwise, see the `retentionRules` property. [Retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is [retention period](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-period). The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. ' type: string default: '0' retentionRules: $ref: '#/components/schemas/RetentionRules' schemaType: description: 'The schema Type. Default is `implicit`. #### InfluxDB Cloud - Use `explicit` to enforce column names, tags, fields, and data types for your data. #### InfluxDB OSS - Doesn''t support `explicit` bucket schemas. ' $ref: '#/components/schemas/SchemaType' default: implicit required: - orgID - name LabelResponse: type: object properties: label: $ref: '#/components/schemas/Label' links: $ref: '#/components/schemas/Links' 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 InternalServerError: description: 'Internal server error. The server encountered an unexpected situation. ' content: application/json: schema: $ref: '#/components/schemas/Error' 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 BadRequestError: description: 'Bad request. The response body contains detail about the error. #### InfluxDB OSS - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. ' content: application/json: schema: $ref: '#/components/schemas/Error' examples: orgProvidedNotFound: summary: The org or orgID passed doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' parameters: Limit: in: query name: limit required: false description: 'Limits the number of records returned. Default is `20`. ' schema: type: integer minimum: 1 maximum: 100 default: 20 After: in: query name: after required: false schema: type: string description: 'A resource ID to seek from. Returns records created after the specified record; results don''t include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/cloud/api/#tag/Pagination). ' Offset: in: query name: offset required: false description: 'The offset for pagination. The number of records to skip. For more information about pagination parameters, see [Pagination](https://docs.influxdata.com/influxdb/cloud/api/#tag/Pagination). ' schema: type: integer minimum: 0 TraceSpan: in: header name: Zap-Trace-Span description: OpenTracing span context example: trace_id: '1' span_id: '1' baggage: key: value required: false schema: type: string 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: []