InfluxData Buckets API

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:


# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/influxdata/refs/heads/main/openapi/influxdata-buckets-api-openapi.yml