openapi: 3.0.0 info: title: InfluxDB Cloud API Service 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 tags: - name: Authorizations (API tokens) description: | Create and manage authorizations (API tokens). An _authorization_ contains a list of `read` and `write` permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. We recommend the following for managing your tokens: - Create a generic user to create and manage tokens for writing data. - Store your tokens in a secure password vault for future access. ### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If the user signs in with username and password, creating a _user session_, the session carries the permissions granted by all the user's authorizations. For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/). To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints - [Signin](#tag/Signin) - [Signout](#tag/Signout) ### Related guides - [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication) - [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/) - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) - 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/) - name: DBRPs description: | The InfluxDB 1.x data model includes [databases](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#database) and [retention policies](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp). InfluxDB 2.x replaces databases and retention policies with buckets. To support InfluxDB 1.x query and write patterns in InfluxDB 2.x, databases and retention policies are mapped to buckets using the database and retention policy (DBRP) mapping service. The DBRP mapping service uses the database and retention policy specified in 1.x compatibility API requests to route operations to a bucket. ### Related guides - [Database and retention policy mapping](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/dbrp/) - name: Invokable Scripts description: | Store, manage, and execute scripts in InfluxDB. A script stores your custom Flux script and provides an invokable endpoint that accepts runtime parameters. In a script, you can specify custom runtime parameters (`params`)--for example, `params.myparameter`. Once you create a script, InfluxDB generates an [`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke) for your organization. You can run the script from API requests and tasks, defining parameter values for each run. When the script runs, InfluxDB replaces `params` references in the script with the runtime parameter values you define. Use the `/api/v2/scripts` endpoints to create and manage scripts. See related guides to learn how to define parameters and execute scripts. ### Related guides - [Invoke custom scripts](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) - name: Delete description: | Delete data from an InfluxDB bucket. - name: Organizations description: | Manage your [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). An organization is a workspace for a group of users. Organizations can be used to separate different environments, projects, teams or users within InfluxDB. Use the `/api/v2/orgs` endpoints to view and manage organizations. - name: Query description: | Retrieve data, analyze queries, and get query suggestions. - name: Tasks description: | Process and analyze your data with [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) in the InfluxDB task engine. Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs. To configure a task, provide the script and the schedule to run the task. For examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks). ### Properties A `task` object contains information about an InfluxDB task resource. The following table defines the properties that appear in this object: ### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/cloud/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/) - [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script) - name: Templates description: | Export and apply InfluxDB **templates**. Manage **stacks** of templated InfluxDB resources. InfluxDB templates are prepackaged configurations for resources. Use InfluxDB templates to configure a fresh instance of InfluxDB, back up your dashboard configuration, or share your configuration. Use the `/api/v2/templates` endpoints to export templates and apply templates. **InfluxDB stacks** are stateful InfluxDB templates that let you add, update, and remove installed template resources over time, avoid duplicating resources when applying the same or similar templates more than once, and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. Use the `/api/v2/stacks` endpoints to manage installed template resources. ### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) - name: Users description: | Retrieve specific users. InfluxDB Cloud lets you invite and collaborate with multiple users in your organization. To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI); you can't use the InfluxDB API to manage users in InfluxDB Cloud. Once a user is added to your organization, you can use the `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to view specific members. ### User sessions with authorizations Optionally, you can scope an authorization (and its API token) to a user. If a user signs in with username and password, creating a _user session_, the session carries the permissions granted by all the user's authorizations. To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) - name: Write description: | Write time series data to [buckets](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#bucket). - name: Authentication description: | Use one of the following schemes to authenticate to the InfluxDB API: - [Token authentication](#section/Authentication/TokenAuthentication) - [Basic authentication](#section/Authentication/BasicAuthentication) - [Querystring authentication](#section/Authentication/QuerystringAuthentication) x-traitTag: true - name: Quick start x-traitTag: true description: | See the [**API Quick Start**](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. [**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/cloud/api-guide/client-libraries/) are available for popular languages and ready to import into your application. - name: Supported operations x-traitTag: true description: "The following table shows the most common operations that the InfluxDB `/api/v2` API supports.\nSome resources may support other operations that perform functions more specific to those resources.\nFor example, you can use the `PATCH /api/v2/scripts` endpoint to update properties of a script\nresource.\n\n| Operation | |\n|:----------|:-----------------------------------------------------------------------|\n| Write | Writes (`POST`) data to a bucket. |\n| Run | Executes (`POST`) a query or script and returns the result. |\n| List |\tRetrieves (`GET`) a list of zero or more resources. |\n| Create |\tCreates (`POST`) a new resource and returns the resource. |\n| Update |\tModifies (`PUT`) an existing resource to reflect data in your request. |\n| Delete |\tRemoves (`DELETE`) a specific resource. |\n" - name: Headers x-traitTag: true description: | InfluxDB `/api/v2` API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB API endpoints. Some endpoints may use other headers that perform functions more specific to those endpoints--for example, the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body. | Header | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| | `Accept` | string | The content type that the client can understand. | | `Authorization` | string | The authorization scheme and credential. | | `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. | | `Content-Type` | string | The format of the data in the request body. | - name: Common parameters x-traitTag: true description: | To specify resources, some InfluxDB API endpoints require parameters or properties in the request--for example, writing to a `bucket` resource in an `org` (_organization_ resource). ### Common parameters | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| | `bucket` | string | The bucket name or ID ([find your bucket](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/view-buckets/). | | `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/view-buckets/). | | `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/). | | `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/). | - name: Pagination x-traitTag: true description: | Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results: | Query parameter | Value type | Description | |:------------------------ |:--------------------- |:-------------------------------------------| | `limit` | integer | The maximum number of records to return (after other parameters are applied). | | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). | | `after` | string (resource ID) | Only returns resources created after the specified resource. | ### Limitations - For specific endpoint parameters and examples, see the endpoint definition. - If you specify an `offset` parameter value greater than the total number of records, then InfluxDB returns an empty list in the response (given `offset` skips the specified number of records). The following example passes `offset=50` to skip the first 50 results, but the user only has 10 buckets: ```sh curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \ --header "Authorization: Token INFLUX_API_TOKEN" ``` The response contains the following: ```json { "links": { "prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID", "self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID" }, "buckets": [] } ``` - name: Response codes x-traitTag: true description: | InfluxDB `/api/v2` API endpoints use standard HTTP status codes for success and failure responses. The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation. API operations may return the following HTTP status codes: |  Code  | Status | Description | |:-----------:|:------------------------ |:--------------------- | | `200` | Success | | | `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. | | `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: | | `401` | Unauthorized | May indicate one of the following: | | `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. | | `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. | | `413` | Request entity too large | Request payload exceeds the size limit. | | `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. | | `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. | | `500` | Internal server error | | | `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. | 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: [] paths: /signin: post: operationId: PostSignin summary: Create a user session. description: | Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) for a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user), and then, if successful, generates a user session. To authenticate a user, pass the HTTP `Authorization` header with the `Basic` scheme and the base64-encoded username and password. For syntax and more information, see [Basic Authentication](#section/Authentication/BasicAuthentication) for syntax and more information. If authentication is successful, InfluxDB creates a new session for the user and then returns the session cookie in the `Set-Cookie` response header. InfluxDB stores user sessions in memory only. They expire within ten minutes and during restarts of the InfluxDB instance. #### User sessions with authorizations - In InfluxDB Cloud, a user session inherits all the user's permissions for the organization. - In InfluxDB OSS, a user session inherits all the user's permissions for all the organizations that the user belongs to. #### Related endpoints - [Signout](#tag/Signout) tags: - Security and access endpoints - Signin security: - BasicAuthentication: [] parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': description: | Success. The user is authenticated. The `Set-Cookie` response header contains the session cookie. '401': description: | Unauthorized. This error may be caused by one of the following problems: - The user doesn't have access. - The user passed incorrect credentials in the request. - The credentials are formatted incorrectly in the request. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden. The user account is disabled. content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unsuccessful authentication. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: 'cURL: signin with --user option encoding' source: | curl --request POST http://localhost:8086/api/v2/signin \ --user "USERNAME:PASSWORD" /signout: post: operationId: PostSignout summary: Expire a user session tags: - Security and access endpoints - Signout description: | Expires a user session specified by a session cookie. Use this endpoint to expire a user session that was generated when the user authenticated with the InfluxDB Developer Console (UI) or the `POST /api/v2/signin` endpoint. For example, the `POST /api/v2/signout` endpoint represents the third step in the following three-step process to authenticate a user, retrieve the `user` resource, and then expire the session: 1. Send a request with the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) to the `POST /api/v2/signin` endpoint to create a user session and generate a session cookie. 2. Send a request to the `GET /api/v2/me` endpoint, passing the stored session cookie from step 1 to retrieve user information. 3. Send a request to the `POST /api/v2/signout` endpoint, passing the stored session cookie to expire the session. _See the complete example in request samples._ InfluxDB stores user sessions in memory only. If a user doesn't sign out, then the user session automatically expires within ten minutes or during a restart of the InfluxDB instance. To learn more about cookies in HTTP requests, see [Mozilla Developer Network (MDN) Web Docs, HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). #### Related endpoints - [Signin](#tag/Signin) parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': description: Success. The session is expired. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' default: description: The session expiry is unsuccessful. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: 'cURL: sign in a user, verify the user session, and then end the session' source: | # The following example shows how to use cURL and the InfluxDB API # to do the following: # 1. Sign in a user with a username and password. # 2. Check that the user session exists for the user. # 3. Sign out the user to expire the session. # 4. Check that the session is no longer active. # 1. Send a request to `POST /api/v2/signin` to sign in the user. # In your request, pass the following: # # - `--user` option with basic authentication credentials. # - `-c` option with a file path where cURL will write cookies. curl --request POST \ -c ./cookie-file.tmp \ "$INFLUX_URL/api/v2/signin" \ --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}" # 2. To check that a user session exists for the user in step 1, # send a request to `GET /api/v2/me`. # In your request, pass the `-b` option with the session cookie file path from step 1. curl --request GET \ -b ./cookie-file.tmp \ "$INFLUX_URL/api/v2/me" # InfluxDB responds with the `user` resource. # 3. Send a request to `POST /api/v2/signout` to expire the user session. # In your request, pass the `-b` option with the session cookie file path from step 1. curl --request POST \ -b ./cookie-file.tmp \ "$INFLUX_URL/api/v2/signout" # If the user session is successfully expired, InfluxDB responds with an HTTP `204` status code. # 4. To check that the user session is expired, call `GET /api/v2/me` again, # passing the `-b` option with the cookie file path. curl --request GET \ -b ./cookie-file.tmp \ "$INFLUX_URL/api/v2/me" # If the user session is expired, InfluxDB responds with an HTTP `401` status code. /ping: get: operationId: GetPing summary: Get the status of the instance description: | Retrieves the status and InfluxDB version of the instance. Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP `204` status code to inform you the instance is available. #### InfluxDB Cloud - Isn't versioned and doesn't return `X-Influxdb-Version` in the headers. #### Related guides - [Influx ping](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/ping/) servers: - url: '' tags: - Ping - System information endpoints responses: '204': description: | Success. Headers contain InfluxDB version information. headers: X-Influxdb-Build: schema: type: string description: | The type of InfluxDB build. X-Influxdb-Version: schema: type: integer description: | The version of InfluxDB. #### InfluxDB Cloud - Doesn't return version. x-codeSamples: - lang: Shell label: cURL source: | curl --request GET "http://localhost:8086/ping" head: operationId: HeadPing summary: Get the status of the instance description: | Returns the status and InfluxDB version of the instance. Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP `204` status code to inform you the instance is available. #### InfluxDB Cloud - Isn't versioned and doesn't return `X-Influxdb-Version` in the headers. #### Related guides - [Influx ping](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/ping/) servers: - url: '' tags: - Ping responses: '204': description: | Success. Headers contain InfluxDB version information. headers: X-Influxdb-Build: schema: type: string description: The type of InfluxDB build. X-Influxdb-Version: schema: type: integer description: | The version of InfluxDB. #### InfluxDB Cloud - Doesn't return version. x-codeSamples: - lang: Shell label: cURL source: | curl --request HEAD "http://localhost:8086/ping" /: get: operationId: GetRoutes summary: List all top level routes description: | Retrieves all the top level routes for the InfluxDB API. #### Limitations - Only returns top level routes--for example, the response contains `"tasks":"/api/v2/tasks"`, and doesn't contain resource-specific routes for tasks (`/api/v2/tasks/TASK_ID/...`). tags: - Routes - System information endpoints parameters: - $ref: '#/components/parameters/TraceSpan' responses: '200': description: | Success. The response body contains key-value pairs with the resource name and top-level route. content: application/json: schema: $ref: '#/components/schemas/Routes' /dbrps: get: operationId: GetDBRPs tags: - DBRPs summary: List database retention policy mappings description: | Lists database retention policy (DBRP) mappings. #### Related guide - [Database and retention policy mapping](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/dbrp/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: orgID description: | An organization ID. Only returns DBRP mappings for the specified organization. schema: type: string - in: query name: org description: | An organization name. Only returns DBRP mappings for the specified organization. schema: type: string - in: query name: id description: | A DBPR mapping ID. Only returns the specified DBRP mapping. schema: type: string - in: query name: bucketID description: | A bucket ID. Only returns DBRP mappings that belong to the specified bucket. schema: type: string - in: query name: default description: Specifies filtering on default schema: type: boolean - in: query name: db description: | A database. Only returns DBRP mappings that belong to the 1.x database. schema: type: string - in: query name: rp description: | A [retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp). Specifies the 1.x retention policy to filter on. schema: type: string responses: '200': description: Success. The response body contains a list of database retention policy mappings. content: application/json: schema: $ref: '#/components/schemas/DBRPs' examples: successResponse: value: content: - id: 0a3cbb5dd526a000 database: example_database_1 retention_policy: autogen default: true orgID: bea7ea952287f70d bucketID: 4d4d9d5b61dee751 - id: 0a3cbcde20e38000 database: example_database_2 retention_policy: example_retention_policy default: false orgID: bea7ea952287f70d bucketID: 4d4d9d5b61dee751 '400': description: Bad request. The request has one or more invalid parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: description: | The query parameters contain invalid values. value: code: invalid message: invalid ID '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostDBRP tags: - DBRPs summary: Add a database retention policy mapping description: | Creates a database retention policy (DBRP) mapping and returns the mapping. Use this endpoint to add InfluxDB 1.x API compatibility to your InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a DBRP mapping in order to query and write using the InfluxDB 1.x API. object. #### Related guide - [Database and retention policy mapping](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/dbrp/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: | The database retention policy mapping to add. Note that _`retention_policy`_ is a required parameter in the request body. The value of _`retention_policy`_ can be any arbitrary `string` name or value, with the default value commonly set as `autogen`. The value of _`retention_policy`_ isn't a [retention_policy](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-policy-rp) required: true content: application/json: schema: $ref: '#/components/schemas/DBRPCreate' responses: '201': description: Created. The response body contains the database retention policy mapping. content: application/json: schema: $ref: '#/components/schemas/DBRP' examples: successResponse: value: id: 0a3cbb5dd526a000 database: example_database retention_policy: autogen default: true orgID: bea7ea952287f70d bucketID: 4d4d9d5b61dee751 '400': description: Bad request. The mapping in the request has one or more invalid IDs. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: description: | The query parameters contain invalid values. value: code: invalid message: invalid ID '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: create a database retention policy mapping' source: | curl --request POST \ "http://localhost:8086/api/v2/dbrp/" \ --header 'Content-type: application/json' \ --header "Authorization: Token INFLUXDB_TOKEN" \ --data-binary @- << EOF { \ "bucketID": "INFLUXDB_BUCKET_ID", \ "orgID": "INFLUXDB_ORG_ID", \ "database": "database_name", \ "default": true, \ "retention_policy": "example_retention_policy_name" \ } EOF '/dbrps/{dbrpID}': get: operationId: GetDBRPsID tags: - DBRPs summary: Retrieve a database retention policy mapping description: | Retrieves the specified retention policy (DBRP) mapping. #### Related guide - [Database and retention policy mapping](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/dbrp/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: orgID description: | An organization ID. Specifies the organization that owns the DBRP mapping. schema: type: string - in: query name: org description: | An organization name. Specifies the organization that owns the DBRP mapping. schema: type: string - in: path name: dbrpID schema: type: string required: true description: | A DBRP mapping ID. Specifies the DBRP mapping. responses: '200': description: Success. The response body contains the DBRP mapping. content: application/json: schema: $ref: '#/components/schemas/DBRPGet' examples: successResponse: value: content: id: 0a3cbb5dd526a000 database: example_database_1 retention_policy: autogen default: true orgID: bea7ea952287f70d bucketID: 4d4d9d5b61dee751 '400': description: Bad Request. Query parameters contain invalid values. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: description: | The query parameters contain invalid values. value: code: invalid message: invalid ID '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' patch: operationId: PatchDBRPID tags: - DBRPs summary: Update a database retention policy mapping requestBody: description: | Updates the database retention policy (DBRP) mapping and returns the mapping. Use this endpoint to modify the _retention policy_ (`retention_policy` property) of a DBRP mapping. #### Related guide - [Database and retention policy mapping](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/dbrp/) required: true content: application/json: schema: $ref: '#/components/schemas/DBRPUpdate' parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: orgID description: | An organization ID. Specifies the organization that owns the DBRP mapping. schema: type: string - in: query name: org description: | An organization name. Specifies the organization that owns the DBRP mapping. schema: type: string - in: path name: dbrpID schema: type: string required: true description: | A DBRP mapping ID. Specifies the DBRP mapping. responses: '200': description: An updated mapping content: application/json: schema: $ref: '#/components/schemas/DBRPGet' examples: successResponse: value: content: id: 0a3cbb5dd526a000 database: example_database retention_policy: example_retention_policy default: false orgID: bea7ea952287f70d bucketID: 4d4d9d5b61dee751 '400': description: Bad Request. Query parameters contain invalid values. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: description: | The query parameters contain invalid values. value: code: invalid message: invalid ID '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: Update a DBRP mapping' source: | curl --request PATCH \ "http://localhost:8086/api/v2/dbrp/DBRP_ID" \ --header 'Content-type: application/json' \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data-binary @- << EOF { "default": true, "retention_policy": "example_retention_policy_name" } EOF delete: operationId: DeleteDBRPID tags: - DBRPs summary: Delete a database retention policy description: | Deletes the specified database retention policy (DBRP) mapping. #### Related guide - [Database and retention policy mapping](https://docs.influxdata.com/influxdb/cloud/reference/api/influxdb-1x/dbrp/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: orgID description: | An organization ID. Specifies the organization that owns the DBRP mapping. schema: type: string - in: query name: org description: | An organization name. Specifies the organization that owns the DBRP mapping. schema: type: string - in: path name: dbrpID schema: type: string required: true description: | A DBRP mapping ID. Only returns the specified DBRP mapping. responses: '204': description: Success. The delete is accepted. '400': description: Bad Request. Query parameters contain invalid values. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: description: | The query parameters contain invalid values. value: code: invalid message: invalid ID '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' /telegraf/plugins: get: operationId: GetTelegrafPlugins tags: - Telegraf Plugins summary: List all Telegraf plugins parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: type description: The type of plugin desired. schema: type: string responses: '200': description: A list of Telegraf plugins. content: application/json: schema: $ref: '#/components/schemas/TelegrafPlugins' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /telegrafs: get: operationId: GetTelegrafs tags: - Telegrafs summary: List all Telegraf configurations parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: orgID description: The organization ID the Telegraf config belongs to. schema: type: string responses: '200': description: A list of Telegraf configurations content: application/json: schema: $ref: '#/components/schemas/Telegrafs' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostTelegrafs tags: - Telegrafs summary: Create a Telegraf configuration parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: Telegraf configuration to create required: true content: application/json: schema: $ref: '#/components/schemas/TelegrafPluginRequest' responses: '201': description: Telegraf configuration created content: application/json: schema: $ref: '#/components/schemas/Telegraf' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}': get: operationId: GetTelegrafsID tags: - Telegrafs summary: Retrieve a Telegraf configuration parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf configuration ID. - in: header name: Accept required: false schema: type: string default: application/toml enum: - application/toml - application/json - application/octet-stream responses: '200': description: Telegraf configuration details content: application/toml: example: |- [agent] interval = "10s" schema: type: string application/json: schema: $ref: '#/components/schemas/Telegraf' application/octet-stream: example: |- [agent] interval = "10s" schema: type: string default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' put: operationId: PutTelegrafsID tags: - Telegrafs summary: Update a Telegraf configuration parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. requestBody: description: Telegraf configuration update to apply required: true content: application/json: schema: $ref: '#/components/schemas/TelegrafPluginRequest' responses: '200': description: An updated Telegraf configurations content: application/json: schema: $ref: '#/components/schemas/Telegraf' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteTelegrafsID tags: - Telegrafs summary: Delete a Telegraf configuration parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf configuration ID. responses: '204': description: Delete has been accepted default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}/labels': get: operationId: GetTelegrafsIDLabels tags: - Telegrafs summary: List all labels for a Telegraf config parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. responses: '200': description: A list of all labels for a Telegraf config content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostTelegrafsIDLabels tags: - Telegrafs summary: Add a label to a Telegraf config parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. requestBody: description: Label to add required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: The label added to the Telegraf config content: application/json: schema: $ref: '#/components/schemas/LabelResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}/labels/{labelID}': delete: operationId: DeleteTelegrafsIDLabelsID tags: - Telegrafs summary: Delete a label from a Telegraf config parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. - in: path name: labelID schema: type: string required: true description: The label ID. responses: '204': description: Delete has been accepted '404': description: Telegraf config not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}/members': get: operationId: GetTelegrafsIDMembers tags: - Telegrafs summary: List all users with member privileges for a Telegraf config parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. responses: '200': description: A list of Telegraf config members content: application/json: schema: $ref: '#/components/schemas/ResourceMembers' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostTelegrafsIDMembers tags: - Telegrafs summary: Add a member to a Telegraf config parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. requestBody: description: User to add as member required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: Member added to Telegraf config content: application/json: schema: $ref: '#/components/schemas/ResourceMember' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}/members/{userID}': delete: operationId: DeleteTelegrafsIDMembersID tags: - Telegrafs summary: Remove a member from a Telegraf config parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the member to remove. - in: path name: telegrafID schema: type: string required: true description: The Telegraf config ID. responses: '204': description: Member removed default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}/owners': get: operationId: GetTelegrafsIDOwners tags: - Telegrafs summary: List all owners of a Telegraf configuration parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf configuration ID. responses: '200': description: Returns Telegraf configuration owners as a ResourceOwners list content: application/json: schema: $ref: '#/components/schemas/ResourceOwners' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostTelegrafsIDOwners tags: - Telegrafs summary: Add an owner to a Telegraf configuration parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: telegrafID schema: type: string required: true description: The Telegraf configuration ID. requestBody: description: User to add as owner required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. content: application/json: schema: $ref: '#/components/schemas/ResourceOwner' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/telegrafs/{telegrafID}/owners/{userID}': delete: operationId: DeleteTelegrafsIDOwnersID tags: - Telegrafs summary: Remove an owner from a Telegraf config 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: telegrafID schema: type: string required: true description: The Telegraf config ID. responses: '204': description: Owner removed default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/variables/{variableID}/labels': get: operationId: GetVariablesIDLabels tags: - Variables summary: List all labels for a variable parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID schema: type: string required: true description: The variable ID. responses: '200': description: A list of all labels for a variable content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostVariablesIDLabels tags: - Variables summary: Add a label to a variable parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID schema: type: string required: true description: The variable ID. requestBody: description: Label to add required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: The newly added label content: application/json: schema: $ref: '#/components/schemas/LabelResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/variables/{variableID}/labels/{labelID}': delete: operationId: DeleteVariablesIDLabelsID tags: - Variables summary: Delete a label from a variable parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID schema: type: string required: true description: The variable ID. - in: path name: labelID schema: type: string required: true description: The label ID to delete. responses: '204': description: Delete has been accepted '404': description: Variable not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /write: post: operationId: PostWrite tags: - Data I/O endpoints - Write summary: Write data description: | Writes data to a bucket. Use this endpoint to send data in [line protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud - Does the following when you send a write request: 1. Validates the request and queues the write. 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. 3. Handles the delete asynchronously and reaches eventual consistency. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP `2xx` status code) before you send the next request. Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response. #### InfluxDB OSS - Validates the request and handles the write synchronously. - If all points were written successfully, responds with HTTP `2xx` status code; otherwise, returns the first line that failed. #### Required permissions - `write-buckets` or `write-bucket BUCKET_ID`. *`BUCKET_ID`* is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) `write` rate limits apply. For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). #### Related guides - [Write data with the InfluxDB API](https://docs.influxdata.com/influxdb/cloud/write-data/developer-tools/api) - [Optimize writes to InfluxDB](https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/optimize-writes/) - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/) requestBody: description: | In the request body, provide data in [line protocol format](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/). To send compressed data, do the following: 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. 2. In your request, send the compressed data and the `Content-Encoding: gzip` header. #### Related guides - [Best practices for optimizing writes](https://docs.influxdata.com/influxdb/cloud/write-data/best-practices/optimize-writes/) required: true content: text/plain: schema: type: string format: byte examples: plain-utf8: value: | airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000 parameters: - $ref: '#/components/parameters/TraceSpan' - in: header name: Content-Encoding description: | The compression applied to the line protocol in the request payload. To send a GZIP payload, pass `Content-Encoding: gzip` header. schema: type: string description: | Content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. default: identity enum: - gzip - identity - in: header name: Content-Type description: | The format of the data in the request body. To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`. schema: type: string description: | `text/plain` is the content type for line protocol. `UTF-8` is the default character set. default: text/plain; charset=utf-8 enum: - text/plain - text/plain; charset=utf-8 - in: header name: Content-Length description: | The size of the entity-body, in bytes, sent to InfluxDB. If the length is greater than the `max body` configuration option, the server responds with status code `413`. schema: type: integer description: The length in decimal number of octets. - in: header name: Accept description: | The content type that the client can understand. Writes only return a response body if they fail--for example, due to a formatting problem or quota limit. #### InfluxDB Cloud - Returns only `application/json` for format and limit errors. - Returns only `text/html` for some quota limit errors. #### InfluxDB OSS - Returns only `application/json` for format and limit errors. #### Related guides - [Troubleshoot issues writing data](https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/) schema: type: string description: Error content type. default: application/json enum: - application/json - in: query name: org description: | An organization name or ID. #### InfluxDB Cloud - Doesn't use the `org` parameter or `orgID` parameter. - Writes data to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or the `orgID` parameter. - If you pass both `orgID` and `org`, they must both be valid. - Writes data to the bucket in the specified organization. required: true schema: type: string description: The organization name or ID. - in: query name: orgID description: | An organization ID. #### InfluxDB Cloud - Doesn't use the `org` parameter or `orgID` parameter. - Writes data to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or the `orgID` parameter. - If you pass both `orgID` and `org`, they must both be valid. - Writes data to the bucket in the specified organization. schema: type: string - in: query name: bucket description: | A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket. required: true schema: type: string description: The bucket name or ID. - in: query name: precision description: The precision for unix timestamps in the line protocol batch. schema: $ref: '#/components/schemas/WritePrecision' responses: '204': description: | Success. #### InfluxDB Cloud - Validated and queued the request. - Handles the write asynchronously - the write might not have completed yet. #### InfluxDB OSS - Successfully wrote all points in the batch. #### Related guides - [How to check for write errors](https://docs.influxdata.com/influxdb/cloud/write-data/troubleshoot/) '400': description: | Bad request. The response body contains detail about the error. InfluxDB returns this error if the line protocol data in the request is malformed. The response body contains the first malformed line in the data, and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your `_monitoring` bucket. #### InfluxDB Cloud - Returns this error for bucket schema conflicts. #### InfluxDB OSS - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. content: application/json: schema: $ref: '#/components/schemas/LineProtocolError' examples: measurementSchemaFieldTypeConflict: summary: (Cloud) field type conflict thrown by an explicit bucket schema value: code: invalid message: 'partial write error (2 written): unable to parse ''air_sensor,service=S1,sensor=L1 temperature="90.5",humidity=70.0 1632850122'': schema: field type for field "temperature" not permitted by schema; got String but expected Float' orgNotFound: summary: (OSS) organization not found value: code: invalid message: 'failed to decode request body: organization not found' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '413': description: | The request payload is too large. InfluxDB rejected the batch and did not write any data. #### InfluxDB Cloud: - Returns this error if the payload exceeds the 50MB size limit. - Returns `Content-Type: text/html` for this error. #### InfluxDB OSS: - Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. - Returns `Content-Type: application/json` for this error. content: application/json: schema: $ref: '#/components/schemas/LineProtocolLengthError' examples: dataExceedsSizeLimitOSS: summary: InfluxDB OSS response value: | {"code":"request too large","message":"unable to read data: points batch is too large"} text/html: schema: type: string examples: dataExceedsSizeLimit: summary: InfluxDB Cloud response value: | 413 Request Entity Too Large

413 Request Entity Too Large


nginx
'429': description: | Too many requests. #### InfluxDB Cloud - Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum [global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits). - For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. - For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header. Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. #### InfluxDB OSS - Doesn't return this error. headers: Retry-After: description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: type: integer format: int32 '500': $ref: '#/components/responses/InternalServerError' '503': description: | Service unavailable. - Returns this error if the server is temporarily unavailable to accept writes. - Returns a `Retry-After` header that describes when to try the write again. headers: Retry-After: description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: type: integer format: int32 default: $ref: '#/components/responses/GeneralServerError' /delete: post: operationId: PostDelete tags: - Data I/O endpoints - Delete summary: Delete data description: | Deletes data from a bucket. Use this endpoint to delete points from a bucket in a specified time range. #### InfluxDB Cloud - Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. 3. Handles the delete asynchronously and reaches eventual consistency. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP `2xx` status code) before you send the next request. Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response. #### InfluxDB OSS - Validates the request, handles the delete synchronously, and then responds with success or failure. #### Required permissions - `write-buckets` or `write-bucket BUCKET_ID`. *`BUCKET_ID`* is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) `write` rate limits apply. For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). #### Related guides - [Delete data](https://docs.influxdata.com/influxdb/cloud/write-data/delete-data/) - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). - Learn how InfluxDB handles [deleted tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). x-codeSamples: - lang: Shell label: cURL source: | curl --request POST INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "start": "2020-03-01T00:00:00Z", "stop": "2020-11-14T00:00:00Z", "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")" }' requestBody: description: | Time range parameters and an optional **delete predicate expression**. To select points to delete within the specified time range, pass a **delete predicate expression** in the `predicate` property of the request body. If you don't pass a `predicate`, InfluxDB deletes all data with timestamps in the specified time range. #### Related guides - [Delete data](https://docs.influxdata.com/influxdb/cloud/write-data/delete-data/) - Learn how to use [delete predicate syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). required: true content: application/json: schema: $ref: '#/components/schemas/DeletePredicateRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: org description: | An organization name or ID. #### InfluxDB Cloud - Doesn't use the `org` parameter or `orgID` parameter. - Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or the `orgID` parameter. - Deletes data from the bucket in the specified organization. - If you pass both `orgID` and `org`, they must both be valid. schema: type: string description: The organization name or ID. - in: query name: bucket description: | A bucket name or ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. schema: type: string description: The bucket name or ID. - in: query name: orgID description: | An organization ID. #### InfluxDB Cloud - Doesn't use the `org` parameter or `orgID` parameter. - Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or the `orgID` parameter. - Deletes data from the bucket in the specified organization. - If you pass both `orgID` and `org`, they must both be valid. schema: type: string description: The organization ID. - in: query name: bucketID description: | A bucket ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. schema: type: string description: The bucket ID. responses: '204': description: | Success. #### InfluxDB Cloud - Validated and queued the request. - Handles the delete asynchronously - the deletion might not have completed yet. An HTTP `2xx` status code acknowledges that the write or delete is queued. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request. Because writes are asynchronous, data might not yet be written when you receive the response. #### InfluxDB OSS - Deleted the data. '400': description: | Bad request. The response body contains detail about the error. #### InfluxDB OSS - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. content: application/json: schema: $ref: '#/components/schemas/Error' examples: orgNotFound: summary: Organization not found value: code: invalid message: 'failed to decode request body: organization not found' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' /labels: post: operationId: PostLabels tags: - Labels summary: Create a label requestBody: description: The label to create. required: true content: application/json: schema: $ref: '#/components/schemas/LabelCreateRequest' responses: '201': description: Success. The label was created. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' get: operationId: GetLabels tags: - Labels summary: List all labels parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: orgID description: The organization ID. schema: type: string responses: '200': description: Success. The response body contains a list of labels. content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/labels/{labelID}': get: operationId: GetLabelsID tags: - Labels summary: Retrieve a label parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: labelID schema: type: string required: true description: The ID of the label to update. responses: '200': description: Success. The response body contains the label. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' patch: operationId: PatchLabelsID tags: - Labels summary: Update a label requestBody: description: A label update. required: true content: application/json: schema: $ref: '#/components/schemas/LabelUpdate' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: labelID schema: type: string required: true description: The ID of the label to update. responses: '200': description: Success. The response body contains the updated label. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' delete: operationId: DeleteLabelsID tags: - Labels summary: Delete a label parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: labelID schema: type: string required: true description: The ID of the label to delete. responses: '204': description: Success. The delete was accepted. '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/dashboards/{dashboardID}': get: operationId: GetDashboardsID tags: - Dashboards summary: Retrieve a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. - in: query name: include required: false schema: type: string enum: - properties description: 'If `properties`, includes the cell view properties in the response.' responses: '200': description: Retrieve a single dashboard content: application/json: schema: oneOf: - $ref: '#/components/schemas/Dashboard' - $ref: '#/components/schemas/DashboardWithViewProperties' '404': description: Dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchDashboardsID tags: - Dashboards summary: Update a dashboard requestBody: description: Patching of a dashboard required: true content: application/json: schema: type: object title: PatchDashboardRequest properties: name: description: 'optional, when provided will replace the name' type: string description: description: 'optional, when provided will replace the description' type: string cells: description: 'optional, when provided will replace all existing cells with the cells provided' $ref: '#/components/schemas/CellWithViewProperties' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. responses: '200': description: Updated dashboard content: application/json: schema: $ref: '#/components/schemas/Dashboard' '404': description: Dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteDashboardsID tags: - Dashboards summary: Delete a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. responses: '204': description: Delete has been accepted '404': description: Dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/cells': put: operationId: PutDashboardsIDCells tags: - Cells - Dashboards summary: Replace cells in a dashboard description: Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Cells' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. responses: '201': description: Replaced dashboard cells content: application/json: schema: $ref: '#/components/schemas/Dashboard' '404': description: Dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostDashboardsIDCells tags: - Cells - Dashboards summary: Create a dashboard cell requestBody: description: Cell that will be added required: true content: application/json: schema: $ref: '#/components/schemas/CreateCell' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. responses: '201': description: Cell successfully added content: application/json: schema: $ref: '#/components/schemas/Cell' '404': description: Dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/cells/{cellID}': patch: operationId: PatchDashboardsIDCellsID tags: - Cells - Dashboards summary: Update the non-positional information related to a cell description: Updates the non positional information related to a cell. Updates to a single cell's positional data could cause grid conflicts. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CellUpdate' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. - in: path name: cellID schema: type: string required: true description: The ID of the cell to update. responses: '200': description: Updated dashboard cell content: application/json: schema: $ref: '#/components/schemas/Cell' '404': description: Cell or dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteDashboardsIDCellsID tags: - Cells - Dashboards summary: Delete a dashboard cell parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to delete. - in: path name: cellID schema: type: string required: true description: The ID of the cell to delete. responses: '204': description: Cell successfully deleted '404': description: Cell or dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/cells/{cellID}/view': get: operationId: GetDashboardsIDCellsIDView tags: - Cells - Dashboards - Views summary: Retrieve the view for a cell parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. - in: path name: cellID schema: type: string required: true description: The cell ID. responses: '200': description: A dashboard cells view content: application/json: schema: $ref: '#/components/schemas/View' '404': description: Cell or dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchDashboardsIDCellsIDView tags: - Cells - Dashboards - Views summary: Update the view for a cell requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/View' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The ID of the dashboard to update. - in: path name: cellID schema: type: string required: true description: The ID of the cell to update. responses: '200': description: Updated cell view content: application/json: schema: $ref: '#/components/schemas/View' '404': description: Cell or dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/labels': get: operationId: GetDashboardsIDLabels tags: - Dashboards summary: List all labels for a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. responses: '200': description: A list of all labels for a dashboard content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostDashboardsIDLabels tags: - Dashboards summary: Add a label to a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. requestBody: description: Label to add required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: The label added to the dashboard content: application/json: schema: $ref: '#/components/schemas/LabelResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/labels/{labelID}': delete: operationId: DeleteDashboardsIDLabelsID tags: - Dashboards summary: Delete a label from a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard 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: Dashboard not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/members': get: operationId: GetDashboardsIDMembers tags: - Dashboards summary: List all dashboard members parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. responses: '200': description: A list of users who have member privileges for a dashboard content: application/json: schema: $ref: '#/components/schemas/ResourceMembers' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostDashboardsIDMembers tags: - Dashboards summary: Add a member to a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. requestBody: description: User to add as member required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: Added to dashboard members content: application/json: schema: $ref: '#/components/schemas/ResourceMember' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/members/{userID}': delete: operationId: DeleteDashboardsIDMembersID tags: - Dashboards summary: Remove a member from a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the member to remove. - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. responses: '204': description: Member removed default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/owners': get: operationId: GetDashboardsIDOwners tags: - Dashboards summary: List all dashboard owners parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. responses: '200': description: A list of users who have owner privileges for a dashboard content: application/json: schema: $ref: '#/components/schemas/ResourceOwners' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostDashboardsIDOwners tags: - Dashboards summary: Add an owner to a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: dashboardID schema: type: string required: true description: The dashboard ID. requestBody: description: User to add as owner required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: Added to dashboard owners content: application/json: schema: $ref: '#/components/schemas/ResourceOwner' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/dashboards/{dashboardID}/owners/{userID}': delete: operationId: DeleteDashboardsIDOwnersID tags: - Dashboards summary: Remove an owner from a dashboard 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: dashboardID schema: type: string required: true description: The dashboard ID. responses: '204': description: Owner removed default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /query/ast: post: operationId: PostQueryAst tags: - Query summary: Generate a query Abstract Syntax Tree (AST) description: | Analyzes a Flux query and returns a complete package source [Abstract Syntax Tree (AST)](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#abstract-syntax-tree-ast) for the query. Use this endpoint for deep query analysis such as debugging unexpected query results. A Flux query AST provides a semantic, tree-like representation with contextual information about the query. The AST illustrates how the query is distributed into different components for execution. #### Limitations - The endpoint doesn't validate values in the query--for example: The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: ```js from(foo: "iot_center") |> range(start: -90d) |> filter(fn: (r) => r._measurement == "environment") ``` The following sample JSON shows how to pass the query in the request body: ```js from(foo: "iot_center") |> range(start: -90d) |> filter(fn: (r) => r._measurement == "environment") ``` The following code sample shows how to pass the query as JSON in the request body: ```json { "query": "from(foo: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")" } ``` Passing this to `/api/v2/query/ast` will return a successful response with a generated AST. parameters: - $ref: '#/components/parameters/TraceSpan' - in: header name: Content-Type schema: type: string enum: - application/json requestBody: description: The Flux query to analyze. content: application/json: schema: $ref: '#/components/schemas/LanguageRequest' x-codeSamples: - lang: Shell label: 'cURL: Analyze and generate AST for the query' source: | curl --request POST "http://localhost:8086/api/v2/query/ast" \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header "Authorization: Token INFLUX_TOKEN" \ --data-binary @- << EOL { "query": "from(bucket: \"INFLUX_BUCKET_NAME\")\ |> range(start: -5m)\ |> filter(fn: (r) => r._measurement == \"example-measurement\")" } EOL responses: '200': description: | Success. The response body contains an Abstract Syntax Tree (AST) of the Flux query. content: application/json: schema: $ref: '#/components/schemas/ASTResponse' examples: successResponse: value: ast: type: Package package: main files: - type: File location: start: line: 1 column: 1 end: line: 1 column: 109 source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' metadata: parser-type=rust package: null imports: null body: - type: ExpressionStatement location: start: line: 1 column: 1 end: line: 1 column: 109 source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' expression: type: PipeExpression location: start: line: 1 column: 1 end: line: 1 column: 109 source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' argument: type: PipeExpression location: start: line: 1 column: 1 end: line: 1 column: 47 source: 'from(bucket: "example-bucket") |> range(start: -5m)' argument: type: CallExpression location: start: line: 1 column: 1 end: line: 1 column: 26 source: 'from(bucket: "example-bucket")' callee: type: Identifier location: start: line: 1 column: 1 end: line: 1 column: 5 source: from name: from arguments: - type: ObjectExpression location: start: line: 1 column: 6 end: line: 1 column: 25 source: 'bucket: "example-bucket"' properties: - type: Property location: start: line: 1 column: 6 end: line: 1 column: 25 source: 'bucket: "example-bucket"' key: type: Identifier location: start: line: 1 column: 6 end: line: 1 column: 12 source: bucket name: bucket value: type: StringLiteral location: start: line: 1 column: 14 end: line: 1 column: 25 source: '"example-bucket"' value: example-bucket call: type: CallExpression location: start: line: 1 column: 30 end: line: 1 column: 47 source: 'range(start: -5m)' callee: type: Identifier location: start: line: 1 column: 30 end: line: 1 column: 35 source: range name: range arguments: - type: ObjectExpression location: start: line: 1 column: 36 end: line: 1 column: 46 source: 'start: -5m' properties: - type: Property location: start: line: 1 column: 36 end: line: 1 column: 46 source: 'start: -5m' key: type: Identifier location: start: line: 1 column: 36 end: line: 1 column: 41 source: start name: start value: type: UnaryExpression location: start: line: 1 column: 43 end: line: 1 column: 46 source: '-5m' operator: '-' argument: type: DurationLiteral location: start: line: 1 column: 44 end: line: 1 column: 46 source: 5m values: - magnitude: 5 unit: m call: type: CallExpression location: start: line: 1 column: 51 end: line: 1 column: 109 source: 'filter(fn: (r) => r._measurement == "example-measurement")' callee: type: Identifier location: start: line: 1 column: 51 end: line: 1 column: 57 source: filter name: filter arguments: - type: ObjectExpression location: start: line: 1 column: 58 end: line: 1 column: 108 source: 'fn: (r) => r._measurement == "example-measurement"' properties: - type: Property location: start: line: 1 column: 58 end: line: 1 column: 108 source: 'fn: (r) => r._measurement == "example-measurement"' key: type: Identifier location: start: line: 1 column: 58 end: line: 1 column: 60 source: fn name: fn value: type: FunctionExpression location: start: line: 1 column: 62 end: line: 1 column: 108 source: (r) => r._measurement == "example-measurement" params: - type: Property location: start: line: 1 column: 63 end: line: 1 column: 64 source: r key: type: Identifier location: start: line: 1 column: 63 end: line: 1 column: 64 source: r name: r value: null body: type: BinaryExpression location: start: line: 1 column: 69 end: line: 1 column: 108 source: r._measurement == "example-measurement" operator: '==' left: type: MemberExpression location: start: line: 1 column: 69 end: line: 1 column: 83 source: r._measurement object: type: Identifier location: start: line: 1 column: 69 end: line: 1 column: 70 source: r name: r property: type: Identifier location: start: line: 1 column: 71 end: line: 1 column: 83 source: _measurement name: _measurement right: type: StringLiteral location: start: line: 1 column: 87 end: line: 1 column: 108 source: '"example-measurement"' value: example-measurement '400': description: | Bad request. InfluxDB is unable to parse the request. The response body contains detail about the problem. headers: X-Platform-Error-Code: description: | The reason for the error. schema: type: string example: invalid content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidASTValue: summary: Invalid AST description: | If the request body contains a missing property key in `from()`, returns `invalid` and problem detail. value: code: invalid message: 'invalid AST: loc 1:6-1:19: missing property key' default: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' /query/suggestions: get: operationId: GetQuerySuggestions tags: - Query summary: List Flux query suggestions description: | Lists Flux query suggestions. Each suggestion contains a [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name and parameters. Use this endpoint to retrieve a list of Flux query suggestions used in the InfluxDB Flux Query Builder. #### Limitations - When writing a query, avoid using `_functionName()` helper functions exposed by this endpoint. Helper function names have an underscore (`_`) prefix and aren't meant to be used directly in queries--for example: - To sort on a column and keep the top n records, use the `top(n, columns=["_value"], tables=<-)` function instead of the `_sortLimit` helper function. `top` uses `_sortLimit`. #### Related Guides - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: '200': description: | Success. The response body contains a list of Flux query suggestions--function names used in the Flux Query Builder autocomplete suggestions. content: application/json: schema: $ref: '#/components/schemas/FluxSuggestions' examples: successResponse: value: funcs: - name: _fillEmpty params: createEmpty: bool tables: stream - name: _highestOrLowest params: _sortLimit: function column: invalid groupColumns: array 'n': invalid reducer: function tables: stream - name: _hourSelection params: location: object start: int stop: int tables: stream timeColumn: string - name: _sortLimit params: columns: array desc: bool 'n': int tables: stream - name: _window params: createEmpty: bool every: duration location: object offset: duration period: duration startColumn: string stopColumn: string tables: stream timeColumn: string - name: aggregateWindow params: column: invalid createEmpty: bool every: duration fn: function location: object offset: duration period: duration tables: stream timeDst: string timeSrc: string - name: bool params: v: invalid - name: bottom params: columns: array 'n': int tables: stream - name: buckets params: host: string org: string orgID: string token: string - name: bytes params: v: invalid - name: cardinality params: bucket: string bucketID: string host: string org: string orgID: string predicate: function start: invalid stop: invalid token: string - name: chandeMomentumOscillator params: columns: array 'n': int tables: stream - name: columns params: column: string tables: stream - name: contains params: set: array value: invalid - name: count params: column: string tables: stream - name: cov params: 'on': array pearsonr: bool x: invalid 'y': invalid - name: covariance params: columns: array pearsonr: bool tables: stream valueDst: string - name: cumulativeSum params: columns: array tables: stream - name: derivative params: columns: array initialZero: bool nonNegative: bool tables: stream timeColumn: string unit: duration - name: die params: msg: string - name: difference params: columns: array initialZero: bool keepFirst: bool nonNegative: bool tables: stream - name: display params: v: invalid - name: distinct params: column: string tables: stream - name: doubleEMA params: 'n': int tables: stream - name: drop params: columns: array fn: function tables: stream - name: duplicate params: as: string column: string tables: stream - name: duration params: v: invalid - name: elapsed params: columnName: string tables: stream timeColumn: string unit: duration - name: exponentialMovingAverage params: 'n': int tables: stream - name: fill params: column: string tables: stream usePrevious: bool value: invalid - name: filter params: fn: function onEmpty: string tables: stream - name: findColumn params: column: string fn: function tables: stream - name: findRecord params: fn: function idx: int tables: stream - name: first params: column: string tables: stream - name: float params: v: invalid - name: from params: bucket: string bucketID: string host: string org: string orgID: string token: string - name: getColumn params: column: string - name: getRecord params: idx: int - name: group params: columns: array mode: string tables: stream - name: highestAverage params: column: string groupColumns: array 'n': int tables: stream - name: highestCurrent params: column: string groupColumns: array 'n': int tables: stream - name: highestMax params: column: string groupColumns: array 'n': int tables: stream - name: histogram params: bins: array column: string countColumn: string normalize: bool tables: stream upperBoundColumn: string - name: histogramQuantile params: countColumn: string minValue: float quantile: float tables: stream upperBoundColumn: string valueColumn: string - name: holtWinters params: column: string interval: duration 'n': int seasonality: int tables: stream timeColumn: string withFit: bool - name: hourSelection params: location: object start: int stop: int tables: stream timeColumn: string - name: increase params: columns: array tables: stream - name: int params: v: invalid - name: integral params: column: string interpolate: string tables: stream timeColumn: string unit: duration - name: join params: method: string 'on': array tables: invalid - name: kaufmansAMA params: column: string 'n': int tables: stream - name: kaufmansER params: 'n': int tables: stream - name: keep params: columns: array fn: function tables: stream - name: keyValues params: keyColumns: array tables: stream - name: keys params: column: string tables: stream - name: last params: column: string tables: stream - name: length params: arr: array - name: limit params: 'n': int offset: int tables: stream - name: linearBins params: count: int infinity: bool start: float width: float - name: logarithmicBins params: count: int factor: float infinity: bool start: float - name: lowestAverage params: column: string groupColumns: array 'n': int tables: stream - name: lowestCurrent params: column: string groupColumns: array 'n': int tables: stream - name: lowestMin params: column: string groupColumns: array 'n': int tables: stream - name: map params: fn: function mergeKey: bool tables: stream - name: max params: column: string tables: stream - name: mean params: column: string tables: stream - name: median params: column: string compression: float method: string tables: stream - name: min params: column: string tables: stream - name: mode params: column: string tables: stream - name: movingAverage params: 'n': int tables: stream - name: now params: {} - name: pearsonr params: 'on': array x: invalid 'y': invalid - name: pivot params: columnKey: array rowKey: array tables: stream valueColumn: string - name: quantile params: column: string compression: float method: string q: float tables: stream - name: range params: start: invalid stop: invalid tables: stream - name: reduce params: fn: function identity: invalid tables: stream - name: relativeStrengthIndex params: columns: array 'n': int tables: stream - name: rename params: columns: invalid fn: function tables: stream - name: sample params: column: string 'n': int pos: int tables: stream - name: set params: key: string tables: stream value: string - name: skew params: column: string tables: stream - name: sort params: columns: array desc: bool tables: stream - name: spread params: column: string tables: stream - name: stateCount params: column: string fn: function tables: stream - name: stateDuration params: column: string fn: function tables: stream timeColumn: string unit: duration - name: stateTracking params: countColumn: string durationColumn: string durationUnit: duration fn: function tables: stream timeColumn: string - name: stddev params: column: string mode: string tables: stream - name: string params: v: invalid - name: sum params: column: string tables: stream - name: tableFind params: fn: function tables: stream - name: tail params: 'n': int offset: int tables: stream - name: time params: v: invalid - name: timeShift params: columns: array duration: duration tables: stream - name: timeWeightedAvg params: tables: stream unit: duration - name: timedMovingAverage params: column: string every: duration period: duration tables: stream - name: to params: bucket: string bucketID: string fieldFn: function host: string measurementColumn: string org: string orgID: string tables: stream tagColumns: array timeColumn: string token: string - name: toBool params: tables: stream - name: toFloat params: tables: stream - name: toInt params: tables: stream - name: toString params: tables: stream - name: toTime params: tables: stream - name: toUInt params: tables: stream - name: today params: {} - name: top params: columns: array 'n': int tables: stream - name: tripleEMA params: 'n': int tables: stream - name: tripleExponentialDerivative params: 'n': int tables: stream - name: truncateTimeColumn params: tables: stream timeColumn: invalid unit: duration - name: uint params: v: invalid - name: union params: tables: array - name: unique params: column: string tables: stream - name: wideTo params: bucket: string bucketID: string host: string org: string orgID: string tables: stream token: string - name: window params: createEmpty: bool every: duration location: object offset: duration period: duration startColumn: string stopColumn: string tables: stream timeColumn: string - name: yield params: name: string tables: stream '301': description: | Moved Permanently. InfluxData has moved the URL of the endpoint. Use `/api/v2/query/suggestions` (without a trailing slash). content: text/html: schema: properties: body: readOnly: true description: Response message with URL of requested resource. type: string examples: movedPermanently: summary: Invalid URL description: | The URL has been permanently moved. Use `/api/v2/query/suggestions`. value: | Moved Permanently default: description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: Shell label: cURL source: | curl --request GET "INFLUX_URL/api/v2/query/suggestions" \ --header "Accept: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" '/query/suggestions/{name}': get: operationId: GetQuerySuggestionsName tags: - Query summary: Retrieve a query suggestion for a branching suggestion description: | Retrieves a query suggestion that contains the name and parameters of the requested function. Use this endpoint to pass a branching suggestion (a Flux function name) and retrieve the parameters of the requested function. #### Limitations - Use `/api/v2/query/suggestions/{name}` (without a trailing slash). `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a HTTP `301 Moved Permanently` status. - The function `name` must exist and must be spelled correctly. #### Related Guides - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: name schema: type: string required: true description: | A [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name. responses: '200': description: | Success. The response body contains the function name and parameters. content: application/json: schema: $ref: '#/components/schemas/FluxSuggestion' examples: successResponse: value: name: sum params: column: string tables: stream '500': description: | Internal server error. The value passed for _`name`_ may have been misspelled. content: application/json: schema: $ref: '#/components/schemas/Error' examples: internalError: summary: Invalid function description: | The requested function doesn't exist. value: code: internal error message: An internal error has occurred x-codeSamples: - lang: Shell label: cURL source: | curl --request GET "INFLUX_URL/api/v2/query/suggestions/sum/" \ --header "Accept: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" /query/analyze: post: operationId: PostQueryAnalyze tags: - Query summary: Analyze a Flux query description: | Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax errors and returns the list of errors. In the following sample query, `from()` is missing the property key. ```json { "query": "from(: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")", "type": "flux" } ``` If you pass this in a request to the `/api/v2/analyze` endpoint, InfluxDB returns an `errors` list that contains an error object for the missing key. #### Limitations - The endpoint doesn't validate values in the query--for example: - The following sample query has correct syntax, but contains an incorrect `from()` property key: ```json { "query": "from(foo: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")", "type": "flux" } ``` If you pass this in a request to the `/api/v2/analyze` endpoint, InfluxDB returns an empty `errors` list. parameters: - $ref: '#/components/parameters/TraceSpan' - in: header name: Content-Type schema: type: string enum: - application/json requestBody: description: Flux query to analyze content: application/json: schema: $ref: '#/components/schemas/Query' responses: '200': description: | Success. The response body contains the list of `errors`. If the query syntax is valid, the endpoint returns an empty `errors` list. content: application/json: schema: $ref: '#/components/schemas/AnalyzeQueryResponse' examples: missingQueryPropertyKey: summary: Missing property key error description: | Returns an error object if the Flux query is missing a property key. The following sample query is missing the _`bucket`_ property key: ```json { "query": "from(: \"iot_center\")\ ... } ``` value: errors: - line: 1 column: 6 character: 0 message: missing property key '400': description: | Bad request. InfluxDB is unable to parse the request. The response body contains detail about the problem. headers: X-Platform-Error-Code: description: | The reason for the error. schema: type: string example: invalid content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidJSONStringValue: summary: Invalid JSON description: 'If the request body contains invalid JSON, returns `invalid` and problem detail.' value: code: invalid message: 'invalid json: invalid character ''\'''' looking for beginning of value' default: description: Internal server error headers: X-Platform-Error-Code: description: The reason for the error. schema: type: string example: internal error X-Influx-Error: description: A string that describes the problem. schema: type: string X-Influx-Reference: description: The numeric reference code for the error type. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: emptyJSONObject: summary: Empty JSON object in request body description: | If the request body contains an empty JSON object, returns `internal error`. value: code: internal error message: An internal error has occurred - check server logs x-codeSamples: - lang: Shell label: 'cURL: Analyze a Flux query' source: | curl -v --request POST \ "http://localhost:8086/api/v2/query/analyze" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header 'Content-type: application/json' \ --header 'Accept: application/json' \ --data-binary @- << EOF { "query": "from(bucket: \"iot_center\")\ |> range(start: -90d)\ |> filter(fn: (r) => r._measurement == \"environment\")", "type": "flux" } EOF /query: post: operationId: PostQuery tags: - Data I/O endpoints - Query summary: Query data description: | Retrieves data from buckets. Use this endpoint to send a Flux query request and retrieve data from a bucket. #### Rate limits (with InfluxDB Cloud) `read` rate limits apply. For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). #### Related guides - [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-api/) - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: header name: Accept-Encoding description: The content encoding (usually a compression algorithm) that the client can understand. schema: type: string description: 'The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.' default: identity enum: - gzip - identity - in: header name: Content-Type schema: type: string enum: - application/json - application/vnd.flux - in: query name: org description: | An organization name or ID. #### InfluxDB Cloud - Doesn't use the `org` parameter or `orgID` parameter. - Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or `orgID` parameter. - Queries the bucket in 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. - Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - Requires either the `org` parameter or `orgID` parameter. - Queries the bucket in the specified organization. schema: type: string x-codeSamples: - lang: Shell label: cURL source: | curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ --header 'Content-Type: application/vnd.flux' \ --header 'Accept: application/csv \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --data 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' requestBody: description: Flux query or specification to execute content: application/json: schema: $ref: '#/components/schemas/Query' application/vnd.flux: schema: type: string example: | from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement") responses: '200': description: Success. The response body contains query results. headers: Content-Encoding: description: Lists encodings (usually compression algorithms) that have been applied to the response payload. schema: type: string description: | The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. default: identity enum: - gzip - identity Trace-Id: description: 'The trace ID, if generated, of the request.' schema: type: string description: Trace ID of a request. content: application/csv: schema: type: string example: | result,table,_start,_stop,_time,region,host,_value mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 '400': description: | Bad request. The response body contains detail about the error. #### InfluxDB OSS - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. content: application/json: schema: $ref: '#/components/schemas/Error' examples: orgNotFound: summary: Organization not found value: code: invalid message: 'failed to decode request body: organization not found' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '429': description: | #### InfluxDB Cloud: - returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas) or if a **delete** request exceeds the maximum [global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits) - returns `Retry-After` header that describes when to try the write again. #### InfluxDB OSS: - doesn't return this error. headers: Retry-After: description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: type: integer format: int32 '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' /buckets: get: operationId: GetBuckets tags: - Buckets summary: List buckets description: | Lists [buckets](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#bucket). InfluxDB retrieves buckets owned by the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) associated with the authorization ([API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token)). To limit which buckets are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all buckets up to the default `limit`. #### InfluxDB OSS - If you use an _[operator token](https://docs.influxdata.com/influxdb/cloud/security/tokens/#operator-token)_ to authenticate your request, InfluxDB retrieves resources for _all organizations_ in the instance. To retrieve resources for only a specific organization, use the `org` parameter or the `orgID` parameter to specify the organization. #### Required permissions | Action | Permission required | |:--------------------------|:--------------------| | Retrieve _user buckets_ | `read-buckets` | | Retrieve [_system buckets_](https://docs.influxdata.com/influxdb/cloud/reference/internals/system-buckets/) | `read-orgs` | #### Related Guides - [Manage buckets](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/) 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" \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" 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 \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "name": "air_sensor", "description": "A bucket holding air sensor data", "orgID": "INFLUX_ORG_ID", "retentionRules": [ { "type": "expire", "everySeconds": 2592000, } ] }' - 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 \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "name": "air_sensor", "description": "bucket holding air sensor data", "retentionRules": [ { "type": "expire", "everySeconds": 2592000 } ] }' delete: operationId: DeleteBucketsID tags: - Buckets summary: Delete a bucket description: | Deletes a bucket and all associated records. #### InfluxDB Cloud - Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. Returns an HTTP `204` status code if queued; _error_ otherwise. 3. Handles the delete asynchronously. #### InfluxDB OSS - Validates the request, handles the delete synchronously, and then responds with success or failure. #### Limitations - Only one bucket can be deleted per request. #### Related Guides - [Delete a bucket](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) 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. #### InfluxDB Cloud - The bucket is queued for deletion. #### InfluxDB OSS - The bucket is deleted. '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" \ --header "Authorization: Token INFLUX_TOKEN" \ --header 'Accept: application/json' '/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. Labels are objects that contain `labelID`, `name`, `description`, and `color` key-value pairs. They may be used for grouping and filtering across one or more kinds of **resources**--for example, you can apply a label named `air_sensor` to a bucket and a task to quickly organize resources. #### Limitations - Before adding a label to a bucket, you must create the label if you haven't already. To create a label with the InfluxDB API, send a `POST` request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). #### 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: | 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 \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "labelID": "09cbd068e7ebb000" }' '/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 \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "id": "09cfb87051cbe000" } '/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) of a bucket. Bucket owners have permission to delete buckets and remove user and member permissions from the bucket. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Owner permissions are separate from API token permissions. - Owner permissions are used in the context of the InfluxDB UI. #### Required permissions - `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a list of owners for. #### Related endpoints - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/users/) 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) with role and user detail. Use this endpoint to create a _resource owner_ for the bucket. Bucket owners have permission to delete buckets and remove user and member permissions from the bucket. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Owner permissions are separate from API token permissions. - Owner permissions are used in the context of the InfluxDB UI. #### Required permissions - `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. #### Related endpoints - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/users/) 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 \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "id": "09cfb87051cbe000" } '/buckets/{bucketID}/owners/{userID}': delete: operationId: DeleteBucketsIDOwnersID tags: - Buckets summary: Remove an owner from a bucket description: | Removes an owner from a bucket. Use this endpoint to remove a user's `owner` role for a bucket. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Owner permissions are separate from API token permissions. - Owner permissions are used in the context of the InfluxDB UI. #### Required permissions - `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related endpoints - [Authorizations](#tag/Authorizations-(API-tokens)) #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/users/) 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' /orgs: get: operationId: GetOrgs tags: - Organizations - Security and access endpoints summary: List organizations description: | Lists [organizations](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization/). To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. #### InfluxDB Cloud - Only returns the organization that owns the token passed in the request. #### Related guides - [View organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Descending' - in: query name: org schema: type: string description: | An organization name. Only returns the specified organization. - in: query name: orgID schema: type: string description: | An organization ID. Only returns the specified organization. - in: query name: userID schema: type: string description: | A user ID. Only returns organizations where the specified user is a member or owner. responses: '200': description: Success. The response body contains a list of organizations. content: application/json: schema: $ref: '#/components/schemas/Organizations' examples: successResponse: value: links: self: /api/v2/orgs orgs: - links: buckets: /api/v2/buckets?org=INFLUX_ORG dashboards: /api/v2/dashboards?org=INFLUX_ORG labels: /api/v2/orgs/INFLUX_ORG_ID/labels logs: /api/v2/orgs/INFLUX_ORG_ID/logs members: /api/v2/orgs/INFLUX_ORG_ID/members owners: /api/v2/orgs/INFLUX_ORG_ID/owners secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets self: /api/v2/orgs/INFLUX_ORG_ID tasks: /api/v2/tasks?org=InfluxData id: INFLUX_ORG_ID name: INFLUX_ORG description: Example InfluxDB organization createdAt: '2022-07-17T23:00:30.778487Z' updatedAt: '2022-07-17T23:00:30.778487Z' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' post: operationId: PostOrgs tags: - Organizations summary: Create an organization description: | Creates an [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) and returns the newly created organization. #### InfluxDB Cloud - Doesn't allow you to use this endpoint to create organizations. #### Related guides - [Manage organizations](https://docs.influxdata.com/influxdb/cloud/organizations) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: The organization to create. required: true content: application/json: schema: $ref: '#/components/schemas/PostOrganizationRequest' responses: '201': description: Created. The response body contains the organization information. content: application/json: schema: $ref: '#/components/schemas/Organization' examples: successResponse: value: links: buckets: /api/v2/buckets?org=INFLUX_ORG dashboards: /api/v2/dashboards?org=INFLUX_ORG labels: /api/v2/orgs/INFLUX_ORG_ID/labels logs: /api/v2/orgs/INFLUX_ORG_ID/logs members: /api/v2/orgs/INFLUX_ORG_ID/members owners: /api/v2/orgs/INFLUX_ORG_ID/owners secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets self: /api/v2/orgs/INFLUX_ORG_ID tasks: /api/v2/tasks?org=INFLUX_ORG id: INFLUX_ORG_ID name: INFLUX_ORG description: '' createdAt: '2022-08-24T23:05:52.881317Z' updatedAt: '2022-08-24T23:05:52.881318Z' '400': $ref: '#/components/responses/BadRequestError' examples: invalidRequest: summary: The `name` field is missing from the request body. value: code: invalid message: org name is empty '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/orgs \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "name": "INFLUX_ORG", "description: "Example InfluxDB organization" }' '/orgs/{orgID}': get: operationId: GetOrgsID tags: - Organizations - Security and access endpoints summary: Retrieve an organization description: | Retrieves an organization. Use this endpoint to retrieve information for a specific organization. #### Related guides - [View organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: | The ID of the organization to retrieve. responses: '200': description: | Success. The response body contains the organization information. content: application/json: schema: $ref: '#/components/schemas/Organization' '401': $ref: '#/components/responses/AuthorizationError' '404': description: | Not found. Organization not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The requested organization wasn't found. value: code: not found message: organization not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchOrgsID tags: - Organizations summary: Update an organization description: | Updates an organization. Use this endpoint to update properties (`name`, `description`) of an organization. Updating an organization’s name affects all resources that reference the organization by name, including the following: - Queries - Dashboards - Tasks - Telegraf configurations - Templates If you change an organization name, be sure to update the organization name in these resources as well. #### Related Guides - [Update an organization](https://docs.influxdata.com/influxdb/cloud/organizations/update-org/) requestBody: description: The organization update to apply. required: true content: application/json: schema: $ref: '#/components/schemas/PatchOrganizationRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: | The ID of the organization to update. responses: '200': description: Success. The response body contains the updated organization. content: application/json: schema: $ref: '#/components/schemas/Organization' '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' delete: operationId: DeleteOrgsID tags: - Organizations summary: Delete an organization description: | Deletes an organization. Deleting an organization from InfluxDB Cloud can't be undone. Once deleted, all data associated with the organization is removed. #### InfluxDB Cloud - Does the following when you send a delete request: 1. Validates the request and queues the delete. 2. Returns an HTTP `204` status code if queued; _error_ otherwise. 3. Handles the delete asynchronously. #### InfluxDB OSS - Validates the request, handles the delete synchronously, and then responds with success or failure. #### Limitations - Only one organization can be deleted per request. #### Related guides - [Delete organizations](https://docs.influxdata.com/influxdb/cloud/organizations/delete-orgs/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: | The ID of the organization to delete. responses: '204': description: | Success. #### InfluxDB Cloud - The organization is queued for deletion. #### InfluxDB OSS - The organization is deleted. '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': description: | Not found. InfluxDB can't find the organization. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The requested organization was not found. value: code: not found message: org not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/orgs/{orgID}/secrets': get: operationId: GetOrgsIDSecrets tags: - Secrets - Security and access endpoints summary: List all secret keys for an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. responses: '200': description: A list of all secret keys content: application/json: schema: $ref: '#/components/schemas/SecretKeysResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchOrgsIDSecrets tags: - Secrets summary: Update secrets in an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. requestBody: description: Secret key value pairs to update/add required: true content: application/json: schema: $ref: '#/components/schemas/Secrets' responses: '204': description: Keys successfully patched default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/orgs/{orgID}/members': get: operationId: GetOrgsIDMembers tags: - Organizations - Security and access endpoints summary: List all members of an organization description: | Lists all users that belong to an organization. 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 within the organization. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Member permissions are separate from API token permissions. - Member permissions are used in the context of the InfluxDB UI. #### Required permissions - `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve members for. #### 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: orgID schema: type: string required: true description: | The ID of the organization to retrieve users for. responses: '200': description: | Success. The response body contains a list of all users within the organization. content: application/json: schema: $ref: '#/components/schemas/ResourceMembers' examples: successResponse: value: links: self: /api/v2/orgs/055aa4783aa38398/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': description: | Not found. InfluxDB can't find the organization. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The requested organization wasn't found. value: code: not found message: 404 page not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostOrgsIDMembers tags: - Organizations summary: Add a member to an organization description: | Add a user to an organization. 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 within the organization. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Member permissions are separate from API token permissions. - Member permissions are used in the context of the InfluxDB UI. #### Required permissions - `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to. #### 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: orgID schema: type: string required: true description: | The ID of the organization. requestBody: description: | The user to add to the organization. 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/orgs/INFLUX_ORG_ID/members \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "id": "09cfb87051cbe000" }' '/orgs/{orgID}/members/{userID}': delete: operationId: DeleteOrgsIDMembersID tags: - Organizations - Security and access endpoints summary: Remove a member from an organization description: | Removes a member from an organization. Use this endpoint to remove a user's member privileges for an organization. Removing member privileges removes the user's `read` and `write` permissions from the organization. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Member permissions are separate from API token permissions. - Member permissions are used in the context of the InfluxDB UI. #### Required permissions - `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related guides - [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: orgID schema: type: string required: true description: The ID of the organization to remove a user from. responses: '204': description: | Success. The user is no longer a member of the organization. '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' '/orgs/{orgID}/owners': get: operationId: GetOrgsIDOwners tags: - Organizations - Security and access endpoints summary: List all owners of an organization description: | Lists all owners of an organization. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions - `read-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a list of owners from. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: | The ID of the organization to list owners for. responses: '200': description: A list of organization owners content: application/json: schema: $ref: '#/components/schemas/ResourceOwners' examples: successResponse: value: links: self: /api/v2/orgs/055aa4783aa38398/owners users: - role: owner links: self: /api/v2/users/09cfb87051cbe000 id: 09cfb87051cbe000 name: example_user_2 status: active '404': description: Organization not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostOrgsIDOwners tags: - Organizations summary: Add an owner to an organization description: | Adds an owner to an organization. Use this endpoint to assign the organization `owner` role to a user. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Required permissions - `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. #### Related endpoints - [Authorizations](#tag/Authorizations-(API-tokens)) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The ID of the organization that you want to add an owner for. requestBody: description: The user to add as an owner of the organization. required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' examples: successResponse: value: role: owner links: self: /api/v2/users/09cfb87051cbe000 id: 09cfb87051cbe000 name: example_user_1 status: active responses: '201': description: | Success. The user is an owner of the organization. The response body contains the owner with role and user detail. content: application/json: schema: $ref: '#/components/schemas/ResourceOwner' '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' x-codeSamples: - lang: Shell label: cURL source: | curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "id": "09cfb87051cbe000" }' '/orgs/{orgID}/owners/{userID}': delete: operationId: DeleteOrgsIDOwnersID tags: - Organizations - Security and access endpoints summary: Remove an owner from an organization description: | Removes an [owner](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#owner) from the organization. Organization owners have permission to delete organizations and remove user and member permissions from the organization. #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. #### Limitations - Owner permissions are separate from API token permissions. - Owner permissions are used in the context of the InfluxDB UI. #### Required permissions - `write-orgs INFLUX_ORG_ID` *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner from. #### Related endpoints - [Authorizations](#tag/Authorizations-(API-tokens)) 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: orgID schema: type: string required: true description: | The ID of the organization to remove an owner from. responses: '204': description: | Success. The user is no longer an owner of the organization. '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' '/orgs/{orgID}/secrets/delete': post: deprecated: true operationId: PostOrgsIDSecrets tags: - Secrets - Security and access endpoints summary: Delete secrets from an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. requestBody: description: Secret key to delete required: true content: application/json: schema: $ref: '#/components/schemas/SecretKeys' responses: '204': description: Keys successfully patched default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/orgs/{orgID}/secrets/{secretID}': delete: operationId: DeleteOrgsIDSecretsID tags: - Secrets - Security and access endpoints summary: Delete a secret from an organization parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: orgID schema: type: string required: true description: The organization ID. - in: path name: secretID schema: type: string required: true description: The secret ID. responses: '204': description: Keys successfully deleted default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' /resources: get: operationId: GetResources tags: - Resources - System information endpoints summary: List all known resources parameters: - $ref: '#/components/parameters/TraceSpan' responses: '200': description: All resources targets content: application/json: schema: type: array items: type: string default: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /stacks: get: operationId: ListStacks tags: - Templates summary: List installed stacks description: | Lists installed InfluxDB stacks. To limit stacks in the response, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all installed stacks for the organization. #### Related guides - [View InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/). parameters: - in: query name: orgID required: true schema: type: string description: | An organization ID. Only returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). #### InfluxDB Cloud - Doesn't require this parameter; InfluxDB only returns resources allowed by the API token. - in: query name: name schema: type: string description: | A stack name. Finds stack `events` with this name and returns the stacks. Repeatable. To filter for more than one stack name, repeat this parameter with each name--for example: - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` examples: findStackByName: summary: Find stacks with the event name value: project-stack-0 - in: query name: stackID schema: type: string description: | A stack ID. Only returns the specified stack. Repeatable. To filter for more than one stack ID, repeat this parameter with each ID--for example: - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` examples: findStackByID: summary: Find a stack with the ID value: 09bd87cd33be3000 responses: '200': description: Success. The response body contains the list of stacks. content: application/json: schema: type: object properties: stacks: type: array items: $ref: '#/components/schemas/Stack' '400': 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: orgIdMissing: summary: The orgID query parameter is missing value: code: invalid message: 'organization id[""] is invalid: id must have a length of 16 bytes' 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' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: CreateStack tags: - Templates summary: Create a stack description: | Creates or initializes a stack. Use this endpoint to _manually_ initialize a new stack with the following optional information: - Stack name - Stack description - URLs for template manifest files To automatically create a stack when applying templates, use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). #### Required permissions - `write` permission for the organization #### Related guides - [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/init/). - [Use InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). requestBody: description: The stack to create. required: true content: application/json: schema: type: object title: PostStackRequest properties: orgID: type: string name: type: string description: type: string urls: type: array items: type: string responses: '201': description: Success. Returns the newly created stack. content: application/json: schema: $ref: '#/components/schemas/Stack' '401': $ref: '#/components/responses/AuthorizationError' '422': description: | Unprocessable entity. The error may indicate one of the following problems: - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. 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' '/stacks/{stack_id}': get: operationId: ReadStack tags: - Templates summary: Retrieve a stack parameters: - in: path name: stack_id required: true schema: type: string description: The identifier of the stack. responses: '200': description: Returns the stack. content: application/json: schema: $ref: '#/components/schemas/Stack' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: UpdateStack tags: - Templates summary: Update a stack parameters: - in: path name: stack_id required: true schema: type: string description: The identifier of the stack. requestBody: description: The stack to update. required: true content: application/json: schema: type: object title: PatchStackRequest properties: name: type: string nullable: true description: type: string nullable: true templateURLs: type: array items: type: string nullable: true additionalResources: type: array items: type: object properties: resourceID: type: string kind: type: string templateMetaName: type: string required: - kind - resourceID responses: '200': description: Returns the updated stack. content: application/json: schema: $ref: '#/components/schemas/Stack' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteStack tags: - Templates summary: Delete a stack and associated resources parameters: - in: path name: stack_id required: true schema: type: string description: The identifier of the stack. - in: query name: orgID required: true schema: type: string description: The identifier of the organization. responses: '204': description: The stack and its associated resources were deleted. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/stacks/{stack_id}/uninstall': post: operationId: UninstallStack tags: - Templates summary: Uninstall a stack parameters: - in: path name: stack_id required: true schema: type: string description: The identifier of the stack. responses: '200': description: Returns the uninstalled stack. content: application/json: schema: $ref: '#/components/schemas/Stack' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /templates/apply: post: operationId: ApplyTemplate tags: - Templates summary: Apply or dry-run a template description: | Applies a template to create or update a [stack](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) of InfluxDB [resources](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/export/all/#resources). The response contains the diff of changes and the stack ID. Use this endpoint to install an InfluxDB template to an organization. Provide template URLs or template objects in your request. To customize which template resources are installed, use the `actions` parameter. By default, when you apply a template, InfluxDB installs the template to create and update stack resources and then generates a diff of the changes. If you pass `dryRun: true` in the request body, InfluxDB validates the template and generates the resource diff, but doesn’t make any changes to your instance. #### Custom values for templates - Some templates may contain [environment references](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. To provide custom values for environment references, pass the _`envRefs`_ property in the request body. For more information and examples, see how to [define environment references](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#define-environment-references). - Some templates may contain queries that use [secrets](https://docs.influxdata.com/influxdb/cloud/security/secrets/). To provide custom secret values, pass the _`secrets`_ property in the request body. Don't expose secret values in templates. For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template). #### Required permissions - `write` permissions for resource types in the template. #### Rate limits (with InfluxDB Cloud) - Adjustable service quotas apply. For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/). #### Related guides - [Use templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/) - [Stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) requestBody: required: true description: | Parameters for applying templates. content: application/json: schema: $ref: '#/components/schemas/TemplateApply' examples: skipKindAction: summary: Skip all bucket and task resources in the provided templates value: orgID: INFLUX_ORG_ID actions: - action: skipKind properties: kind: Bucket - action: skipKind properties: kind: Task templates: - contents: - '[object Object]': null skipResourceAction: summary: Skip specific resources in the provided templates value: orgID: INFLUX_ORG_ID actions: - action: skipResource properties: kind: Label resourceTemplateName: foo-001 - action: skipResource properties: kind: Bucket resourceTemplateName: bar-020 - action: skipResource properties: kind: Bucket resourceTemplateName: baz-500 templates: - contents: - apiVersion: influxdata.com/v2alpha1 kind: Bucket metadata: name: baz-500 templateObjectEnvRefs: summary: envRefs for template objects value: orgID: INFLUX_ORG_ID envRefs: linux-cpu-label: MY_CPU_LABEL docker-bucket: MY_DOCKER_BUCKET docker-spec-1: MY_DOCKER_SPEC templates: - contents: - apiVersion: influxdata.com/v2alpha1 kind: Label metadata: name: envRef: key: linux-cpu-label spec: color: '#326BBA' name: inputs.cpu - contents: - apiVersion: influxdata.com/v2alpha1 kind: Bucket metadata: name: envRef: key: docker-bucket application/x-jsonnet: schema: $ref: '#/components/schemas/TemplateApply' text/yml: schema: $ref: '#/components/schemas/TemplateApply' x-codeSamples: - lang: Shell label: 'cURL: Dry run with a remote template' source: | curl --request POST "http://localhost:8086/api/v2/templates/apply" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data @- << EOF { "dryRun": true, "orgID": "INFLUX_ORG_ID", "remotes": [ { "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml" } ] } EOF - lang: Shell label: 'cURL: Apply with secret values' source: | curl "http://localhost:8086/api/v2/templates/apply" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data @- << EOF | jq . { "orgID": "INFLUX_ORG_ID", "secrets": { "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL" }, "remotes": [ { "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml" } ] } EOF - lang: Shell label: 'cURL: Apply template objects with environment references' source: | curl --request POST "http://localhost:8086/api/v2/templates/apply" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data @- << EOF { "orgID": "INFLUX_ORG_ID", "envRefs": { "linux-cpu-label": "MY_CPU_LABEL", "docker-bucket": "MY_DOCKER_BUCKET", "docker-spec-1": "MY_DOCKER_SPEC" }, "templates": [ { "contents": [{ "apiVersion": "influxdata.com/v2alpha1", "kind": "Label", "metadata": { "name": { "envRef": { "key": "linux-cpu-label" } } }, "spec": { "color": "#326BBA", "name": "inputs.cpu" } }] }, "templates": [ { "contents": [{ "apiVersion": "influxdata.com/v2alpha1", "kind": "Label", "metadata": { "name": { "envRef": { "key": "linux-cpu-label" } } }, "spec": { "color": "#326BBA", "name": "inputs.cpu" } }] }, { "contents": [{ "apiVersion": "influxdata.com/v2alpha1", "kind": "Bucket", "metadata": { "name": { "envRef": { "key": "docker-bucket" } } } }] } ] } EOF responses: '200': description: | Success. The template dry run succeeded. The response body contains a resource diff of changes that the template would have made if installed. No resources were created or updated. The diff and summary won't contain IDs for resources that didn't exist at the time of the dry run. content: application/json: schema: $ref: '#/components/schemas/TemplateSummary' '201': description: | Success. The template applied successfully. The response body contains the stack ID, a diff, and a summary. The diff compares the initial state to the state after the template installation. The summary contains newly created resources. content: application/json: schema: $ref: '#/components/schemas/TemplateSummary' '422': description: | Unprocessable entity. The error may indicate one of the following problems: - The template failed validation. - You passed a parameter combination that InfluxDB doesn't support. content: application/json: schema: allOf: - $ref: '#/components/schemas/TemplateSummary' - type: object required: - message - code properties: message: type: string code: type: string '500': description: | Internal server error. #### InfluxDB Cloud - Returns this error if creating one of the template resources (bucket, dashboard, task, user) exceeds your plan’s adjustable service quotas. content: application/json: schema: $ref: '#/components/schemas/Error' examples: createExceedsQuota: summary: 'InfluxDB Cloud: Creating resource would exceed quota.' value: code: internal error message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\"" default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /templates/export: post: operationId: ExportTemplate tags: - Templates summary: Export a new template requestBody: description: Export resources as an InfluxDB template. required: false content: application/json: schema: oneOf: - $ref: '#/components/schemas/TemplateExportByID' - $ref: '#/components/schemas/TemplateExportByName' responses: '200': description: The template was created successfully. Returns the newly created template. content: application/json: schema: $ref: '#/components/schemas/Template' application/x-yaml: schema: $ref: '#/components/schemas/Template' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/tasks/{taskID}/runs': get: operationId: GetTasksIDRuns tags: - Tasks summary: List runs for a task description: | Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/cloud/process-data/). To limit which task runs are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: | The ID of the task to get runs for. Only returns runs for this task. - in: query name: after schema: type: string description: A task run ID. Only returns runs created after this run. - in: query name: limit schema: type: integer minimum: 1 maximum: 500 default: 100 description: | Limits the number of task runs returned. Default is `100`. - in: query name: afterTime schema: type: string format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after this time. - in: query name: beforeTime schema: type: string format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before this time. responses: '200': description: Success. The response body contains the list of task runs. content: application/json: schema: $ref: '#/components/schemas/Runs' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' post: operationId: PostTasksIDRuns tags: - Data I/O endpoints - Tasks summary: 'Start a task run, overriding the schedule' description: | Schedules a task run to start immediately, ignoring scheduled runs. Use this endpoint to manually start a task run. Scheduled runs will continue to run as scheduled. This may result in concurrently running tasks. To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/RunManually' responses: '201': description: Success. The run is scheduled to start. content: application/json: schema: $ref: '#/components/schemas/Run' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/tasks/{taskID}/runs/{runID}': get: operationId: GetTasksIDRunsID tags: - Tasks summary: Retrieve a run for a task. description: | Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to retrieve runs for. - in: path name: runID schema: type: string required: true description: The ID of the run to retrieve. responses: '200': description: Success. The response body contains the task run. content: application/json: schema: $ref: '#/components/schemas/Run' examples: runSuccess: summary: A successful task run. value: links: logs: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs retry: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 task: /api/v2/tasks/0996e56b2f378000 id: 09b070dadaa7d000 taskID: 0996e56b2f378000 status: success scheduledFor: '2022-07-18T14:46:06Z' startedAt: '2022-07-18T14:46:07.16222Z' finishedAt: '2022-07-18T14:46:07.308254Z' requestedAt: '2022-07-18T14:46:06Z' log: - runID: 09b070dadaa7d000 time: '2022-07-18T14:46:07.101231Z' message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 time: '2022-07-18T14:46:07.242859Z' message: Completed(success) '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' delete: operationId: DeleteTasksIDRunsID tags: - Tasks summary: Cancel a running task description: | Cancels a running [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud - Doesn't support this operation. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to cancel. - in: path name: runID schema: type: string required: true description: The ID of the task run to cancel. responses: '204': description: | Success. The `DELETE` is accepted and the run will be cancelled. #### InfluxDB Cloud - Doesn't support this operation. - Doesn't return this status. '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '405': description: | Method not allowed. #### InfluxDB Cloud - Always returns this error; doesn't support cancelling tasks. #### InfluxDB OSS - Doesn't return this error. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/tasks/{taskID}/runs/{runID}/retry': post: operationId: PostTasksIDRunsIDRetry tags: - Tasks summary: Retry a task run description: | Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to retry and returns the scheduled run. To manually start a _new_ task run, use the [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - The task must be _active_ (`status: "active"`). requestBody: content: application/json; charset=utf-8: schema: type: object parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to retry. - in: path name: runID schema: type: string required: true description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the [`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns) to list task runs. responses: '200': description: Success. The response body contains the queued run. content: application/json: schema: $ref: '#/components/schemas/Run' examples: retryTaskRun: summary: A task run scheduled to retry value: links: logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 task: /api/v2/tasks/09a776832f381000 id: 09d60ffe08738000 taskID: 09a776832f381000 status: scheduled scheduledFor: '2022-08-15T00:00:00Z' requestedAt: '2022-08-16T20:05:11.84145Z' '400': description: | Bad request. The response body contains detail about the error. InfluxDB may return this error for the following reasons: - The task has `status: inactive`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: inactiveTask: summary: Can't retry an inactive task value: code: invalid message: 'failed to retry run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/tasks/{taskID}/logs': get: operationId: GetTasksIDLogs tags: - Tasks summary: Retrieve all logs for a task description: | Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). When an InfluxDB task runs, a “run” record is created in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. Use this endpoint to retrieve only the log events for a task, without additional task metadata. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The task ID. responses: '200': description: | Success. The response body contains an `events` list with logs for the task. Each log event `message` contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure. content: application/json: schema: $ref: '#/components/schemas/Logs' examples: taskSuccess: summary: Events for a successful task run. value: events: - runID: 09b070dadaa7d000 time: '2022-07-18T14:46:07.101231Z' message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: summary: Events for a failed task run. value: events: - runID: 09a946fc3167d000 time: '2022-07-13T07:06:54.198167Z' message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 time: '2022-07-13T07:07:13.104037Z' message: Completed(failed) - runID: 09a946fc3167d000 time: '2022-07-13T08:24:37.115323Z' message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/tasks/{taskID}/runs/{runID}/logs': get: operationId: GetTasksIDRunsIDLogs tags: - Tasks summary: Retrieve all logs for a run description: | Retrieves all logs for a task run. A log is a list of run events with `runID`, `time`, and `message` properties. Use this endpoint to help analyze task performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to get logs for. - in: path name: runID schema: type: string required: true description: The ID of the run to get logs for. responses: '200': description: | Success. The response body contains an `events` list with logs for the task run. Each log event `message` contains detail about the event. If a run fails, InfluxDB logs an event with the reason for the failure. content: application/json: schema: $ref: '#/components/schemas/Logs' examples: taskSuccess: summary: Events for a successful task run. value: events: - runID: 09b070dadaa7d000 time: '2022-07-18T14:46:07.101231Z' message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: summary: Events for a failed task. value: events: - runID: 09a946fc3167d000 time: '2022-07-13T07:06:54.198167Z' message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 time: '2022-07-13T07:07:13.104037Z' message: Completed(failed) - runID: 09a946fc3167d000 time: '2022-07-13T08:24:37.115323Z' message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/tasks/{taskID}/labels': get: operationId: GetTasksIDLabels tags: - Tasks summary: List labels for a task description: | Retrieves a list of all labels for a task. Labels may be used for grouping and filtering tasks. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to retrieve labels for. responses: '200': description: Success. The response body contains a list of all labels for the task. content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' post: operationId: PostTasksIDLabels tags: - Tasks summary: Add a label to a task description: | Adds a label to a task. Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to label. requestBody: description: An object that contains a _`labelID`_ to add to the task. required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: Success. The response body contains a list of all labels for the task. content: application/json: schema: $ref: '#/components/schemas/LabelResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' '/tasks/{taskID}/labels/{labelID}': delete: operationId: DeleteTasksIDLabelsID tags: - Tasks summary: Delete a label from a task description: | Deletes a label from a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to delete the label from. - in: path name: labelID schema: type: string required: true description: The ID of the label to delete. responses: '204': description: Success. The label is deleted. '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' /flags: get: operationId: GetFlags tags: - Config summary: Retrieve feature flags description: | Retrieves the feature flag key-value pairs configured for the InfluxDB instance. _Feature flags_ are configuration options used to develop and test experimental InfluxDB features and are intended for internal use only. This endpoint represents the first step in the following three-step process to configure feature flags: 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve feature flags and their values. 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/cloud/reference/config-options/#feature-flags). 3. **Optional**: To confirm that your change is applied, do one of the following: - Send a request to this endpoint to retrieve the current feature flag values. - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the current runtime server configuration. #### Related guides - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: '200': description: Success. The response body contains feature flags. content: application/json: schema: $ref: '#/components/schemas/Flags' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /me: get: operationId: GetMe tags: - Users summary: Retrieve the currently authenticated user parameters: - $ref: '#/components/parameters/TraceSpan' responses: '200': description: Success. The response body contains the currently authenticated user. content: application/json: schema: $ref: '#/components/schemas/UserResponse' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' /me/password: put: operationId: PutMePassword tags: - Users summary: Update a password description: | Updates the password for the signed-in [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). This endpoint represents the third step in the following three-step process to let a user with a user session update their password: 1. Pass the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) to the `POST /api/v2/signin` endpoint to create a user session and generate a session cookie. 2. From the response in the first step, extract the session cookie (`Set-Cookie`) header. 3. Pass the following in a request to the `PUT /api/v2/me/password` endpoint: - The `Set-Cookie` header from the second step - The `Authorization Basic` header with the user's _Basic authentication_ credentials - `{"password": "NEW_PASSWORD"}` in the request body #### InfluxDB Cloud - Doesn't let you manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update your password. #### Related endpoints - [Signin](#tag/Signin) - [Signout](#tag/Signout) - [Users](#tag/Users) #### Related guides - [InfluxDB Cloud - Change your password](https://docs.influxdata.com/influxdb/cloud/account-management/change-password/) - [InfluxDB OSS - Change your password](https://docs.influxdata.com/influxdb/latest/users/change-password/) security: - BasicAuthentication: [] parameters: - $ref: '#/components/parameters/TraceSpan' - name: influxdb-oss-session in: cookie schema: type: string required: true description: | The user session cookie for the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). #### Related guides - [Manage users]({{% INFLUXDB_DOCS_URL%}}/users/) example: influxdb-oss-session=19aaaZZZGOvP2GGryXVT2qYftlFKu3bIopurM6AGFow1yF1abhtOlbHfsc-d8gozZFC_6WxmlQIAwLMW5xs523w== requestBody: description: The new password. required: true content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' responses: '204': description: Success. The password is updated. '400': description: | Bad request. #### InfluxDB Cloud - Doesn't let you manage user passwords through the API; always responds with this status. #### InfluxDB OSS - Doesn't understand a value passed in the request. '401': $ref: '#/components/responses/AuthorizationError' default: description: Unsuccessful authentication content: application/json: schema: $ref: '#/components/schemas/Error' '/tasks/{taskID}/members': get: operationId: GetTasksIDMembers deprecated: true tags: - Tasks summary: List all task members description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Lists all users that have the `member` role for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The task ID. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. content: application/json: schema: $ref: '#/components/schemas/ResourceMembers' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostTasksIDMembers deprecated: true tags: - Tasks summary: Add a member to a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Adds a user to members of a task and returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The task ID. requestBody: description: A user to add as a member of the task. required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: Created. The user is added to task members. content: application/json: schema: $ref: '#/components/schemas/ResourceMember' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/tasks/{taskID}/members/{userID}': delete: operationId: DeleteTasksIDMembersID deprecated: true tags: - Tasks summary: Remove a member from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Removes a member from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the member to remove. - in: path name: taskID schema: type: string required: true description: The task ID. responses: '204': description: Member removed default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/tasks/{taskID}/owners': get: operationId: GetTasksIDOwners deprecated: true tags: - Tasks summary: List all owners of a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Retrieves all users that have owner permission for a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The ID of the task to retrieve owners for. responses: '200': description: | Success. The response contains a list of `users` that have the `owner` role for the task. If the task has no owners, the response contains an empty `users` array. content: application/json: schema: $ref: '#/components/schemas/ResourceOwners' '401': $ref: '#/components/responses/AuthorizationError' '422': description: | Unprocessable entity. The error may indicate one of the following problems: - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. 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' post: operationId: PostTasksIDOwners deprecated: true tags: - Tasks summary: Add an owner for a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. Assigns a task `owner` role to a user. Use this endpoint to create a _resource owner_ for the task. A _resource owner_ is a user with `role: owner` for a specific resource. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: The task ID. requestBody: description: A user to add as an owner of the task. required: true content: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': description: | Created. The task `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' examples: createdOwner: summary: User has the owner role for the resource value: role: owner links: logs: /api/v2/users/0772396d1f411000/logs self: /api/v2/users/0772396d1f411000 id: 0772396d1f411000 name: USER_NAME status: active '401': $ref: '#/components/responses/AuthorizationError' '422': description: | Unprocessable entity. The error may indicate one of the following problems: - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. 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' '/tasks/{taskID}/owners/{userID}': delete: operationId: DeleteTasksIDOwnersID deprecated: true tags: - Tasks summary: Remove an owner from a task description: | **Deprecated**: Tasks don't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. 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: taskID schema: type: string required: true description: The task ID. responses: '204': description: Owner removed default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/users/{userID}/password': post: operationId: PostUsersIDPassword tags: - Security and access endpoints - Users summary: Update a password description: | Updates a user password. #### InfluxDB Cloud - Doesn't allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password. #### Related guides - [InfluxDB Cloud - Change your password](https://docs.influxdata.com/influxdb/cloud/account-management/change-password/) - [InfluxDB OSS - Change your password](https://docs.influxdata.com/influxdb/latest/users/change-password/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the user to set the password for. requestBody: description: The new password to set for the user. required: true content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' responses: '204': description: Success. The password is updated. '400': description: | Bad request. #### InfluxDB Cloud - Doesn't allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS - Doesn't understand a value passed in the request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: updatePasswordNotAllowed: summary: Cloud API can't update passwords value: code: invalid message: passwords cannot be changed through the InfluxDB Cloud API default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' x-codeSamples: - lang: Shell label: 'cURL: use HTTP POST to update the user password' source: | curl --request POST \ "http://localhost:8086/api/v2/users/USER_ID/password" \ --header 'Content-type: application/json' \ --header "Authorization: Token INFLUX_TOKEN" \ --data-binary @- << EOF {"password": "NEW_USER_PASSWORD"} EOF put: operationId: PutUsersIDPassword tags: - Security and access endpoints - Users summary: Update a password description: | Updates a user password. Use this endpoint to let a user authenticate with [Basic authentication credentials](#section/Authentication/BasicAuthentication) and set a new password. #### InfluxDB Cloud - Doesn't allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password. #### Related guides - [InfluxDB Cloud - Change your password](https://docs.influxdata.com/influxdb/cloud/account-management/change-password/) - [InfluxDB OSS - Change your password](https://docs.influxdata.com/influxdb/latest/users/change-password/) security: - BasicAuthentication: [] parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: The ID of the user to set the password for. requestBody: description: The new password to set for the user. required: true content: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' responses: '204': description: Success. The password is updated. '400': description: | Bad request. #### InfluxDB Cloud - Doesn't allow you to manage passwords through the API; always responds with this status. #### InfluxDB OSS - Doesn't understand a value passed in the request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: updatePasswordNotAllowed: summary: Cloud API can't update passwords value: code: invalid message: passwords cannot be changed through the InfluxDB Cloud API default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' x-codeSamples: - lang: Shell label: 'cURL: use Basic auth to update the user password' source: | curl -c ./cookie-file.tmp --request POST \ "http://localhost:8086/api/v2/signin" \ --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}" curl -b ./cookie-file.tmp --request PUT \ "http://localhost:8086/api/v2/users/USER_ID/password" \ --header 'Content-type: application/json' \ --data-binary @- << EOF {"password": "NEW_USER_PASSWORD"} EOF /checks: get: operationId: GetChecks tags: - Checks summary: List all checks parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - in: query name: orgID required: true description: Only show checks that belong to a specific organization ID. schema: type: string responses: '200': description: A list of checks content: application/json: schema: $ref: '#/components/schemas/Checks' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: CreateCheck tags: - Checks summary: Add new check requestBody: description: Check to create required: true content: application/json: schema: $ref: '#/components/schemas/PostCheck' responses: '201': description: Check created content: application/json: schema: $ref: '#/components/schemas/Check' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/checks/{checkID}': get: operationId: GetChecksID tags: - Checks summary: Retrieve a check parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. responses: '200': description: The check requested content: application/json: schema: $ref: '#/components/schemas/Check' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' put: operationId: PutChecksID tags: - Checks summary: Update a check requestBody: description: Check update to apply required: true content: application/json: schema: $ref: '#/components/schemas/Check' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. responses: '200': description: An updated check content: application/json: schema: $ref: '#/components/schemas/Check' '404': description: The check was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchChecksID tags: - Checks summary: Update a check requestBody: description: Check update to apply required: true content: application/json: schema: $ref: '#/components/schemas/CheckPatch' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. responses: '200': description: An updated check content: application/json: schema: $ref: '#/components/schemas/Check' '404': description: The check was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteChecksID tags: - Checks summary: Delete a check parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. responses: '204': description: Delete has been accepted '404': description: The check was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/checks/{checkID}/labels': get: operationId: GetChecksIDLabels tags: - Checks summary: List all labels for a check parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. responses: '200': description: A list of all labels for a check content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostChecksIDLabels tags: - Checks summary: Add a label to a check parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. requestBody: description: Label to add required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: The label was added to the check content: application/json: schema: $ref: '#/components/schemas/LabelResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/checks/{checkID}/labels/{labelID}': delete: operationId: DeleteChecksIDLabelsID tags: - Checks summary: Delete label from a check parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check 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: Check or label not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /notificationRules: get: operationId: GetNotificationRules tags: - NotificationRules summary: List all notification rules parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - in: query name: orgID required: true description: Only show notification rules that belong to a specific organization ID. schema: type: string - in: query name: checkID description: Only show notifications that belong to the specific check ID. schema: type: string - in: query name: tag description: Only return notification rules that "would match" statuses which contain the tag key value pairs provided. schema: type: string pattern: '^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$' example: 'env:prod' responses: '200': description: A list of notification rules content: application/json: schema: $ref: '#/components/schemas/NotificationRules' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: CreateNotificationRule tags: - NotificationRules summary: Add a notification rule requestBody: description: Notification rule to create required: true content: application/json: schema: $ref: '#/components/schemas/PostNotificationRule' responses: '201': description: Notification rule created content: application/json: schema: $ref: '#/components/schemas/NotificationRule' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/checks/{checkID}/query': get: operationId: GetChecksIDQuery tags: - Checks summary: Retrieve a check query parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: checkID schema: type: string required: true description: The check ID. responses: '200': description: The check query requested content: application/json: schema: $ref: '#/components/schemas/FluxResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Check not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationRules/{ruleID}': get: operationId: GetNotificationRulesID tags: - NotificationRules summary: Retrieve a notification rule parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. responses: '200': description: The notification rule requested content: application/json: schema: $ref: '#/components/schemas/NotificationRule' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' put: operationId: PutNotificationRulesID tags: - NotificationRules summary: Update a notification rule requestBody: description: Notification rule update to apply required: true content: application/json: schema: $ref: '#/components/schemas/NotificationRule' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. responses: '200': description: An updated notification rule content: application/json: schema: $ref: '#/components/schemas/NotificationRule' '404': description: The notification rule was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchNotificationRulesID tags: - NotificationRules summary: Update a notification rule requestBody: description: Notification rule update to apply required: true content: application/json: schema: $ref: '#/components/schemas/NotificationRuleUpdate' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. responses: '200': description: An updated notification rule content: application/json: schema: $ref: '#/components/schemas/NotificationRule' '404': description: The notification rule was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteNotificationRulesID tags: - NotificationRules summary: Delete a notification rule parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. responses: '204': description: Delete has been accepted '404': description: The check was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationRules/{ruleID}/labels': get: operationId: GetNotificationRulesIDLabels tags: - NotificationRules summary: List all labels for a notification rule parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. responses: '200': description: A list of all labels for a notification rule content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostNotificationRuleIDLabels tags: - NotificationRules summary: Add a label to a notification rule parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. requestBody: description: Label to add required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: The label was added to the notification rule content: application/json: schema: $ref: '#/components/schemas/LabelResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationRules/{ruleID}/labels/{labelID}': delete: operationId: DeleteNotificationRulesIDLabelsID tags: - NotificationRules summary: Delete label from a notification rule parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule 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: Rule or label not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationRules/{ruleID}/query': get: operationId: GetNotificationRulesIDQuery tags: - Rules summary: Retrieve a notification rule query parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: ruleID schema: type: string required: true description: The notification rule ID. responses: '200': description: The notification rule query requested content: application/json: schema: $ref: '#/components/schemas/FluxResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Notification rule not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /notificationEndpoints: get: operationId: GetNotificationEndpoints tags: - NotificationEndpoints summary: List all notification endpoints parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - in: query name: orgID required: true description: Only show notification endpoints that belong to specific organization ID. schema: type: string responses: '200': description: A list of notification endpoints content: application/json: schema: $ref: '#/components/schemas/NotificationEndpoints' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: CreateNotificationEndpoint tags: - NotificationEndpoints summary: Add a notification endpoint requestBody: description: Notification endpoint to create required: true content: application/json: schema: $ref: '#/components/schemas/PostNotificationEndpoint' responses: '201': description: Notification endpoint created content: application/json: schema: $ref: '#/components/schemas/NotificationEndpoint' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationEndpoints/{endpointID}': get: operationId: GetNotificationEndpointsID tags: - NotificationEndpoints summary: Retrieve a notification endpoint parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint ID. responses: '200': description: The notification endpoint requested content: application/json: schema: $ref: '#/components/schemas/NotificationEndpoint' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' put: operationId: PutNotificationEndpointsID tags: - NotificationEndpoints summary: Update a notification endpoint requestBody: description: A new notification endpoint to replace the existing endpoint with required: true content: application/json: schema: $ref: '#/components/schemas/NotificationEndpoint' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint ID. responses: '200': description: An updated notification endpoint content: application/json: schema: $ref: '#/components/schemas/NotificationEndpoint' '404': description: The notification endpoint was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: operationId: PatchNotificationEndpointsID tags: - NotificationEndpoints summary: Update a notification endpoint requestBody: description: Check update to apply required: true content: application/json: schema: $ref: '#/components/schemas/NotificationEndpointUpdate' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint ID. responses: '200': description: An updated notification endpoint content: application/json: schema: $ref: '#/components/schemas/NotificationEndpoint' '404': description: The notification endpoint was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' delete: operationId: DeleteNotificationEndpointsID tags: - NotificationEndpoints summary: Delete a notification endpoint parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint ID. responses: '204': description: Delete has been accepted '404': description: The endpoint was not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationEndpoints/{endpointID}/labels': get: operationId: GetNotificationEndpointsIDLabels tags: - NotificationEndpoints summary: List all labels for a notification endpoint parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint ID. responses: '200': description: A list of all labels for a notification endpoint content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostNotificationEndpointIDLabels tags: - NotificationEndpoints summary: Add a label to a notification endpoint parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint ID. requestBody: description: Label to add required: true content: application/json: schema: $ref: '#/components/schemas/LabelMapping' responses: '201': description: The label was added to the notification endpoint content: application/json: schema: $ref: '#/components/schemas/LabelResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' '/notificationEndpoints/{endpointID}/labels/{labelID}': delete: operationId: DeleteNotificationEndpointsIDLabelsID tags: - NotificationEndpoints summary: Delete a label from a notification endpoint parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: endpointID schema: type: string required: true description: The notification endpoint 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: Endpoint or label not found content: application/json: schema: $ref: '#/components/schemas/Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /authorizations: get: operationId: GetAuthorizations tags: - Authorizations (API tokens) - Security and access endpoints summary: List authorizations description: | Lists authorizations. To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. #### InfluxDB Cloud - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in `GET /api/v2/authorizations` responses; returns `token: redacted` for all authorizations. #### Required permissions To retrieve an authorization, the request must use an API token that has the following permissions: - `read-authorizations` - `read-user` for the user that the authorization is scoped to #### Related guides - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: userID schema: type: string description: | A user ID. Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - in: query name: user schema: type: string description: | A user name. Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - in: query name: orgID schema: type: string description: 'An organization ID. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization).' - in: query name: org schema: type: string description: | An organization name. Only returns authorizations that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). - in: query name: token schema: type: string description: | An API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) value. Specifies an authorization by its `token` property value and returns the authorization. #### InfluxDB OSS - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, applies other parameters, and then returns the result. #### Limitations - The parameter is non-repeatable. If you specify more than one, only the first one is used. If a resource with the specified property value doesn't exist, then the response body contains an empty list. responses: '200': description: | Success. The response body contains a list of authorizations. If the response body is missing authorizations that you expect, check that the API token used in the request has `read-user` permission for the users (`userID` property value) in those authorizations. #### InfluxDB OSS - **Warning**: The response body contains authorizations with their [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in clear text. - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, InfluxDB OSS returns authorizations for all organizations in the instance. content: application/json: schema: $ref: '#/components/schemas/Authorizations' '400': description: Invalid request $ref: '#/components/responses/GeneralServerError' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' post: operationId: PostAuthorizations tags: - Authorizations (API tokens) - Security and access endpoints summary: Create an authorization description: | Creates an authorization and returns the authorization with the generated API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). Use this endpoint to create an authorization, which generates an API token with permissions to `read` or `write` to a specific resource or `type` of resource. The API token is the authorization's `token` property value. To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens. - InfluxDB allows access to the API token value immediately after the authorization is created. - You can’t change access (read/write) permissions for an API token after it’s created. - Tokens stop working when the user who created the token is deleted. We recommend the following for managing your tokens: - Create a generic user to create and manage tokens for writing data. - Store your tokens in a secure password vault for future access. #### Required permissions - `write-authorizations` - `write-user` for the user that the authorization is scoped to #### Related guides - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: The authorization to create. required: true content: application/json: schema: $ref: '#/components/schemas/AuthorizationPostRequest' examples: AuthorizationPostRequest: $ref: '#/components/examples/AuthorizationPostRequest' AuthorizationWithResourcePostRequest: $ref: '#/components/examples/AuthorizationWithResourcePostRequest' AuthorizationWithUserPostRequest: $ref: '#/components/examples/AuthorizationWithUserPostRequest' responses: '201': description: | Success. The authorization is created. The response body contains the authorization. content: application/json: schema: $ref: '#/components/schemas/Authorization' '400': description: Invalid request $ref: '#/components/responses/GeneralServerError' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' '/authorizations/{authID}': get: operationId: GetAuthorizationsID tags: - Authorizations (API tokens) - Security and access endpoints summary: Retrieve an authorization description: | Retrieves an authorization. Use this endpoint to retrieve information about an API token, including the token's permissions and the user that the token is scoped to. #### InfluxDB OSS - InfluxDB OSS returns [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) values in authorizations. - If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_, InfluxDB OSS returns authorizations for all organizations in the instance. #### Related guides - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) externalDocs: url: 'https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/' description: View tokens parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: authID schema: type: string required: true description: An authorization ID. Specifies the authorization to retrieve. responses: '200': description: Success. The response body contains the authorization. content: application/json: schema: $ref: '#/components/schemas/Authorization' '400': description: | Bad request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The specified resource ID is invalid. value: code: invalid message: id must have a length of 16 bytes '401': $ref: '#/components/responses/AuthorizationError' '404': description: | Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The requested authorization doesn't exist. value: code: not found message: authorization not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' patch: operationId: PatchAuthorizationsID tags: - Authorizations (API tokens) - Security and access endpoints summary: Update an API token to be active or inactive description: | Updates an authorization. Use this endpoint to set an API token's status to be _active_ or _inactive_. InfluxDB rejects requests that use inactive API tokens. requestBody: description: 'In the request body, provide the authorization properties to update.' required: true content: application/json: schema: $ref: '#/components/schemas/AuthorizationUpdateRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: authID schema: type: string required: true description: An authorization ID. Specifies the authorization to update. responses: '200': description: Success. The response body contains the updated authorization. content: application/json: schema: $ref: '#/components/schemas/Authorization' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' delete: operationId: DeleteAuthorizationsID tags: - Authorizations (API tokens) - Security and access endpoints summary: Delete an authorization description: | Deletes an authorization. Use the endpoint to delete an API token. If you want to disable an API token instead of delete it, [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: authID schema: type: string required: true description: An authorization ID. Specifies the authorization to delete. responses: '204': description: Success. The authorization is deleted. '400': description: | Bad request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The specified resource ID is invalid. value: code: invalid message: id must have a length of 16 bytes '401': $ref: '#/components/responses/AuthorizationError' '404': description: | Not found. content: application/json: schema: $ref: '#/components/schemas/Error' examples: notFound: summary: | The requested authorization doesn't exist. value: code: not found message: authorization not found '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' /users: get: operationId: GetUsers tags: - Security and access endpoints - Users summary: List users description: | Lists [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). To limit which users are returned, pass query parameters in your request. #### InfluxDB Cloud - InfluxDB Cloud doesn't allow listing all users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action | Permission required | Restriction | |:-------|:--------------------|:------------| | List all users | Operator token | InfluxData internal use only | | List a specific user | `read-users` or `read-user USER_ID` | *`USER_ID`* is the ID of the user that you want to retrieve. #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name schema: type: string description: | A user name. Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - in: query name: id schema: type: string description: | A user id. Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). responses: '200': description: | Success. The response contains a list of `users`. #### InfluxDB Cloud - Returns an empty `users` list if you don't pass _`id`_ or _`name`_ parameters and don't use an _operator token_. Only InfluxData can access InfluxDB Cloud operator tokens. content: application/json: schema: $ref: '#/components/schemas/Users' '401': description: | Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: | Unprocessable entity. The error may indicate one of the following problems: - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' post: operationId: PostUsers tags: - Users summary: Create a user description: | (InfluxData internal use only) Creates and returns a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that can access InfluxDB. #### InfluxDB Cloud - InfluxDB Cloud Doesn't let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action | Permission required | Restriction | |:-------|:--------------------|:------------| | Create user | Operator token | InfluxData internal use only | #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: 'In the request body, provide the user.' required: true content: application/json: schema: $ref: '#/components/schemas/User' responses: '201': description: | Success. The response body contains the user. content: application/json: schema: $ref: '#/components/schemas/UserResponse' '401': description: | Unauthorized. #### InfluxDB Cloud - Returns this error if the request doesn't use an _operator token_. Only InfluxData can access InfluxDB Cloud operator tokens. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: | Unprocessable entity. The error may indicate one of the following problems: - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalServerError' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' '/users/{userID}': get: operationId: GetUsersID tags: - Users summary: Retrieve a user description: | Retrieves a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: | A user ID. Retrieves the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). responses: '200': description: Success. The response body contains the user. content: application/json: schema: $ref: '#/components/schemas/UserResponse' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' patch: operationId: PatchUsersID tags: - Users summary: Update a user description: | (InfluxData internal use only) Updates a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) and returns the user. #### InfluxDB Cloud - Doesn't let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions for InfluxDB Cloud | Action | Permission required | Restriction | |:-------|:--------------------|:------------| | Update user | Operator token | InfluxData internal use only | #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) requestBody: description: The user update to apply. required: true content: application/json: schema: $ref: '#/components/schemas/User' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: | A user ID. Updates the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). responses: '200': description: Success. The response body contains the updated user. content: application/json: schema: $ref: '#/components/schemas/UserResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' delete: operationId: DeleteUsersID tags: - Users summary: Delete a user description: | (InfluxData internal use only) Deletes a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). For security purposes, once an InfluxDB user account is deleted from an organization, the user (and their token) cannot be reactivated. #### InfluxDB Cloud - Doesn't let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information. #### Required permissions | Action | Permission required | Restriction | |:-------|:--------------------|:------------| | Delete user | Operator token | InfluxData internal use only | #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: userID schema: type: string required: true description: | A user ID. Deletes the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). responses: '204': description: Success. The user is deleted. '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' /setup: get: operationId: GetSetup tags: - Setup summary: Retrieve setup status description: 'Check if setup is allowed. Returns `true` if no default user, organization, or bucket have been created.' parameters: - $ref: '#/components/parameters/TraceSpan' responses: '200': description: 'Setup is allowed, true or false' content: application/json: schema: $ref: '#/components/schemas/IsOnboarding' post: operationId: PostSetup tags: - Setup summary: 'Create an initial user, organization, and bucket' description: 'Post an onboarding request to create an initial user, organization, and bucket.' parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: Source to create required: true content: application/json: schema: $ref: '#/components/schemas/OnboardingRequest' responses: '201': description: 'The created default user, bucket, and organization' content: application/json: schema: $ref: '#/components/schemas/OnboardingResponse' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' /setup/user: post: operationId: PostSetupUser tags: - Setup summary: 'Create a new user, organization, and bucket' description: 'Post an onboarding request to create a new user, organization, and bucket.' requestBody: description: Source to create required: true content: application/json: schema: $ref: '#/components/schemas/OnboardingRequest' responses: '201': description: 'The created default user, bucket, and organization.' content: application/json: schema: $ref: '#/components/schemas/OnboardingResponse' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' /variables: get: operationId: GetVariables tags: - Variables summary: List all variables parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: org description: The name of the organization. schema: type: string - in: query name: orgID description: The organization ID. schema: type: string responses: '200': description: A list of variables for an organization. content: application/json: schema: $ref: '#/components/schemas/Variables' '400': description: Invalid request $ref: '#/components/responses/GeneralServerError' default: description: Internal server error $ref: '#/components/responses/GeneralServerError' post: operationId: PostVariables summary: Create a variable tags: - Variables parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: Variable to create required: true content: application/json: schema: $ref: '#/components/schemas/Variable' responses: '201': description: Variable created content: application/json: schema: $ref: '#/components/schemas/Variable' default: description: Internal server error $ref: '#/components/responses/GeneralServerError' '/variables/{variableID}': get: operationId: GetVariablesID tags: - Variables summary: Retrieve a variable parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID required: true schema: type: string description: The variable ID. responses: '200': description: Variable found content: application/json: schema: $ref: '#/components/schemas/Variable' '404': description: Variable not found $ref: '#/components/responses/GeneralServerError' default: description: Internal server error $ref: '#/components/responses/GeneralServerError' delete: operationId: DeleteVariablesID tags: - Variables summary: Delete a variable parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID required: true schema: type: string description: The variable ID. responses: '204': description: Variable deleted default: description: Internal server error $ref: '#/components/responses/GeneralServerError' patch: operationId: PatchVariablesID summary: Update a variable tags: - Variables parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID required: true schema: type: string description: The variable ID. requestBody: description: Variable update to apply required: true content: application/json: schema: $ref: '#/components/schemas/Variable' responses: '200': description: Variable updated content: application/json: schema: $ref: '#/components/schemas/Variable' default: description: Internal server error $ref: '#/components/responses/GeneralServerError' put: operationId: PutVariablesID summary: Replace a variable tags: - Variables parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: variableID required: true schema: type: string description: The variable ID. requestBody: description: Variable to replace required: true content: application/json: schema: $ref: '#/components/schemas/Variable' responses: '200': description: Variable updated content: application/json: schema: $ref: '#/components/schemas/Variable' default: description: Internal server error $ref: '#/components/responses/GeneralServerError' '/buckets/{bucketID}/schema/measurements': summary: Bucket schemas get: summary: List measurement schemas of a bucket description: | Lists _explicit_ [schemas](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#schema) (`"schemaType": "explicit"`) for a bucket. _Explicit_ schemas are used to enforce column names, tags, fields, and data types for your data. By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`) that conforms to your data. #### Related guides - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/) operationId: getMeasurementSchemas parameters: - in: query name: org description: | An organization name. Specifies the organization that owns the schema. schema: type: string - in: query name: orgID description: | An organization ID. Specifies the organization that owns the schema. schema: type: string - in: query name: name description: | A measurement name. Only returns measurement schemas with the specified name. schema: type: string - in: path name: bucketID description: | A bucket ID. Lists measurement schemas for the specified bucket. schema: type: string required: true tags: - Bucket Schemas responses: '200': description: A list of measurement schemas returning summary information. headers: ETag: description: The current version of the bucket schema schema: type: string content: application/json: schema: $ref: '#/components/schemas/MeasurementSchemaList' '400': description: | Bad request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidSchemaType: summary: Invalid schema type. value: code: invalid message: bucket schemaType must be explicit '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' post: summary: Create a measurement schema for a bucket description: | Creates an _explict_ measurement [schema](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#schema) for a bucket. _Explicit_ schemas are used to enforce column names, tags, fields, and data types for your data. By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`) that conforms to your data. Use this endpoint to create schemas that prevent non-conforming write requests. #### Limitations - Buckets must be created with the "explict" `schemaType` in order to use schemas. #### Related guides - [Manage bucket schemas](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/bucket-schema/). - [Create a bucket with an explicit schema](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) operationId: createMeasurementSchema parameters: - in: query name: org description: | An organization name. Specifies the organization that owns the schema. schema: type: string - in: query name: orgID description: | An organization ID. Specifies the organization that owns the schema. schema: type: string - in: path name: bucketID description: | A bucket ID. Adds a schema for the specified bucket. schema: type: string required: true tags: - Bucket Schemas requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MeasurementSchemaCreateRequest' responses: '201': description: The current version of the measurement schema. headers: ETag: description: The current version of the measurement schema schema: type: string content: application/json: schema: $ref: '#/components/schemas/MeasurementSchema' '400': description: | Bad request. content: application/json: examples: badNameExample: summary: Invalid name description: 'The error returned when the name is invalid, such as too few or too many characters or the name contains non-printable ASCII or is not valid UTF-8.' value: code: invalid message: name is invalid missingColumnsExample: summary: Missing columns description: The error returned when the request body is missing the columns property. value: code: invalid message: columns is required missingTimestampExample: summary: Missing timestamp description: The error returned when the request body is missing a timestamp type column. value: code: invalid message: Timestamp column is required duplicateColumnNamesExample: summary: Duplicate column names description: The error returned when the request body contains duplicate column names. value: code: invalid message: Duplicate column names missingFieldExample: summary: Missing field description: The error returned when the request body is missing at least one field type column. value: code: invalid message: At least one field column is required schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: Shell label: cURL source: | curl --request POST "INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "name": "temperature", "column": [ { "type": "tag", "name": "location" }, { "type": "field", "name": "value", "dataType": "float" }, { "type": "timestamp", "name": "time" } ] }' '/buckets/{bucketID}/schema/measurements/{measurementID}': summary: Bucket Schema get: summary: Retrieve a measurement schema description: | Retrieves an explicit measurement [schema](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#schema). operationId: getMeasurementSchema parameters: - in: query name: org description: | Organization name. Specifies the organization that owns the schema. schema: type: string - in: query name: orgID description: | Organization ID. Specifies the organization that owns the schema. schema: type: string - in: path name: bucketID description: | A bucket ID. Retrieves schemas for the specified bucket. schema: type: string required: true - in: path name: measurementID description: | The measurement schema ID. Specifies the measurement schema to retrieve. schema: type: string required: true tags: - Bucket Schemas responses: '200': description: Schema definition for a single measurement headers: ETag: description: The current version of the measurement schema schema: type: string content: application/json: schema: $ref: '#/components/schemas/MeasurementSchema' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' patch: summary: Update a measurement schema description: | Updates a measurement [schema](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#schema). Use this endpoint to update the fields (`name`, `type`, and `dataType`) of a measurement schema. #### Limitations - You can't update the `name` of a measurement. #### Related guides - [Manage bucket schemas](https://docs.influxdata.com/influxdb/cloud/organizations/buckets/bucket-schema/). - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/). operationId: updateMeasurementSchema parameters: - in: query name: org description: | An organization name. Specifies the organization that owns the schema. schema: type: string - in: query name: orgID description: | An organization ID. Specifies the organization that owns the schema. schema: type: string - in: path name: bucketID description: | A bucket ID. Specifies the bucket to retrieve schemas for. schema: type: string required: true - in: path name: measurementID description: | A measurement schema ID. Retrieves the specified measurement schema. schema: type: string required: true tags: - Bucket Schemas requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MeasurementSchemaUpdateRequest' responses: '200': description: | Success. The response body contains the measurement schema. content: application/json: schema: $ref: '#/components/schemas/MeasurementSchema' '400': description: | Bad request. content: application/json: examples: missingColumnsExample: summary: Deleted columns description: The error returned when the request body does not contain all the columns from the source. value: code: invalid message: Unable to delete columns from schema schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' x-codeSamples: - lang: Shell label: cURL source: | curl --request PATCH "INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ "column": [ { "type": "tag", "name": "location" }, { "type": "field", "name": "value", "dataType": "float" }, { "type": "timestamp", "name": "time" } ] }' '/orgs/{orgID}/limits': get: tags: - Limits summary: Retrieve limits for an organization operationId: GetOrgLimitsID parameters: - in: path name: orgID description: The ID of the organization. required: true schema: type: string responses: '200': description: Limits defined for the organization. content: application/json: schema: type: object description: These are org limits similar to those configured in/by quartz. properties: links: $ref: '#/components/schemas/Links' limits: $ref: '#/components/schemas/Limit' default: description: unexpected error $ref: '#/components/responses/GeneralServerError' '/orgs/{orgID}/usage': get: tags: - Usage summary: Retrieve usage for an organization operationId: GetOrgUsageID parameters: - in: path name: orgID description: The ID of the organization. required: true schema: type: string - in: query name: start description: | Earliest time to include in results. For more information about timestamps, see [Manipulate timestamps with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/flux/manipulate-timestamps/). required: true schema: type: integer format: unix timestamp - in: query name: stop description: | Latest time to include in results. For more information about timestamps, see [Manipulate timestamps with Flux](https://docs.influxdata.com/influxdb/cloud/query-data/flux/manipulate-timestamps/). required: false schema: type: integer format: unix timestamp - in: query name: raw description: return raw usage data required: false schema: type: boolean default: false responses: '200': description: Usage data headers: Content-Encoding: description: Lists any encodings (usually compression algorithms) that have been applied to the response payload. schema: type: string description: 'The content coding. `gzip` for compressed data or `identity` for unmodified, uncompressed data.' default: identity enum: - gzip - identity content: text/csv: schema: type: string example: | #group,false,false,true,true,false,false,true,true,true,true #datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string #default,_result,,,,,,,,, ,result,table,_start,_stop,_time,_value,_field,_measurement,bucket_id,org_id ,,0,2021-05-10T14:25:10.865702397Z,2021-05-10T15:25:10.865702397Z,2021-05-10T15:00:00Z,5434066,gauge,storage_usage_bucket_bytes,2f6ba0cf9a2fdcbb,cec6fc1d2176dc11 ,,1,2021-05-10T14:25:10.865702397Z,2021-05-10T15:25:10.865702397Z,2021-05-10T15:00:00Z,9924053.966666665,gauge,storage_usage_bucket_bytes,8af67bcaf69d9daf,cec6fc1d2176dc11 default: description: unexpected error $ref: '#/components/responses/GeneralServerError' /dashboards: post: operationId: PostDashboards tags: - Dashboards summary: Create a dashboard parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: Dashboard to create required: true content: application/json: schema: $ref: '#/components/schemas/CreateDashboardRequest' responses: '201': description: Success. The dashboard is created. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Dashboard' - $ref: '#/components/schemas/DashboardWithViewProperties' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' get: operationId: GetDashboards tags: - Dashboards summary: List dashboards description: | Lists [dashboards](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#dashboard). #### Related guides - [Manage dashboards](https://docs.influxdata.com/influxdb/cloud/visualize-data/dashboards/). parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Descending' - in: query name: limit schema: type: integer minimum: -1 maximum: 100 default: 20 description: | The maximum number of [dashboards](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#dashboard) to return. Default is `20`. The minimum is `-1` and the maximum is `100`. - in: query name: owner description: 'A user ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#dashboard) where the specified user has the `owner` role.' schema: type: string - in: query name: sortBy description: The column to sort by. schema: type: string enum: - ID - CreatedAt - UpdatedAt - in: query name: id description: | A list of dashboard IDs. Returns only the specified [dashboards](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#dashboard). If you specify `id` and `owner`, only `id` is used. schema: type: array items: type: string - in: query name: orgID description: | An organization ID. Only returns [dashboards](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#dashboard) that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). schema: type: string - in: query name: org description: | An organization name. Only returns [dashboards](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#dashboard) that belong to the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). schema: type: string responses: '200': description: Success. The response body contains dashboards. content: application/json: schema: $ref: '#/components/schemas/Dashboards' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /tasks: get: operationId: GetTasks tags: - Data I/O endpoints - Tasks summary: List all tasks description: | Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) name. Only returns tasks with the specified name. Different tasks may have the same name. schema: type: string - in: query name: after schema: type: string description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. Only returns tasks created after the specified task. - in: query name: user schema: type: string description: | A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. Only returns tasks owned by the specified user. - in: query name: org schema: type: string description: | An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. Only returns tasks owned by the specified organization. - in: query name: orgID schema: type: string description: | An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. Only returns tasks owned by the specified organization. - in: query name: status schema: type: string enum: - active - inactive description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) status. Only returns tasks that have the specified status (`active` or `inactive`). - in: query name: limit schema: type: integer minimum: -1 maximum: 500 default: 100 description: | The maximum number of [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to return. Default is `100`. The minimum is `1` and the maximum is `500`. To reduce the payload size, combine _`type=basic`_ and _`limit`_ (see _Request samples_). For more information about the `basic` response, see the _`type`_ parameter. examples: minPaginated: summary: Return a maximum of 50 tasks. value: '50' all: summary: 'Return all tasks, without pagination.' value: '-1' - in: query name: offset required: false schema: type: integer minimum: 0 default: 0 description: The number of records to skip. - in: query name: sortBy description: | The sort field. Only `name` is supported. Specifies the field used to sort records in the list. required: false schema: type: string enum: - name - in: query name: type description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) type (`basic` or `system`). Default is `system`. Specifies the level of detail for tasks in the response. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). required: false schema: default: '' type: string enum: - basic - system - in: query name: scriptID description: | A [script](#tag/Invokable-Scripts) ID. Only returns tasks that use the specified invokable script. schema: type: string responses: '200': description: | Success. The response body contains the list of tasks. content: application/json: schema: $ref: '#/components/schemas/Tasks' examples: basicTypeTaskOutput: summary: Basic output description: | A sample response body for the `?type=basic` parameter. `type=basic` omits some task fields (`createdAt` and `updatedAt`) and field values (`org`, `flux`) in the response. value: links: self: /api/v2/tasks?limit=100 tasks: - links: labels: /api/v2/tasks/09956cbb6d378000/labels logs: /api/v2/tasks/09956cbb6d378000/logs members: /api/v2/tasks/09956cbb6d378000/members owners: /api/v2/tasks/09956cbb6d378000/owners runs: /api/v2/tasks/09956cbb6d378000/runs self: /api/v2/tasks/09956cbb6d378000 labels: [] id: 09956cbb6d378000 orgID: 48c88459ee424a04 org: '' ownerID: 0772396d1f411000 name: task1 status: active flux: '' every: 30m latestCompleted: '2022-06-30T15:00:00Z' lastRunStatus: success systemTypeTaskOutput: summary: System output description: | A sample response body for the `?type=system` parameter. `type=system` returns all task fields. value: links: self: /api/v2/tasks?limit=100 tasks: - links: labels: /api/v2/tasks/09956cbb6d378000/labels logs: /api/v2/tasks/09956cbb6d378000/logs members: /api/v2/tasks/09956cbb6d378000/members owners: /api/v2/tasks/09956cbb6d378000/owners runs: /api/v2/tasks/09956cbb6d378000/runs self: /api/v2/tasks/09956cbb6d378000 labels: [] id: 09956cbb6d378000 orgID: 48c88459ee424a04 org: my-iot-center ownerID: 0772396d1f411000 name: task1 description: IoT Center 90-day environment average. status: active flux: |- option task = {name: "task1", every: 30m} from(bucket: "iot_center") |> range(start: -90d) |> filter(fn: (r) => r._measurement == "environment") |> aggregateWindow(every: 1h, fn: mean) every: 30m latestCompleted: '2022-06-30T15:00:00Z' lastRunStatus: success createdAt: '2022-06-27T15:09:06Z' updatedAt: '2022-06-28T18:10:15Z' '401': $ref: '#/components/responses/AuthorizationError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' x-codeSamples: - lang: Shell label: 'cURL: all tasks, basic output' source: | curl INFLUX_URL/api/v2/tasks/?limit=-1&type=basic \ --header 'Content-Type: application/json' \ --header 'Authorization: Token INFLUX_API_TOKEN' post: operationId: PostTasks tags: - Data I/O endpoints - Tasks summary: Create a task description: | Creates a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a Flux script. #### InfluxDB Cloud - You can use either `flux` or `scriptID` to provide the task script. - `flux`: a string of "raw" Flux that contains task options and the script--for example: ```json { "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "status": "active", "description": "This task downsamples CPU data every hour" } ``` - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body--for example: ```json { "name": "CPU Total 1 Hour New", "description": "This task downsamples CPU data every hour", "every": "1h", "scriptID": "SCRIPT_ID", "scriptParameters": { "rangeStart": "-1h", "bucket": "telegraf", "filterField": "cpu-total" } } ``` #### Limitations: - You can't use `flux` and `scriptID` for the same task. #### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/cloud/process-data/get-started/) - [Create a task](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/) - [Common tasks](https://docs.influxdata.com/influxdb/cloud/process-data/common-tasks/) - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: description: The task to create required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' responses: '201': description: Success. The response body contains a `tasks` list with the new task. content: application/json: schema: $ref: '#/components/schemas/Task' '400': description: | Bad request. The response body contains detail about the error. #### InfluxDB Cloud - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_. - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_. content: application/json: schema: $ref: '#/components/schemas/Error' examples: fluxAndScriptError: summary: The request body can't contain both flux and scriptID value: code: invalid message: 'failed to decode request: can not provide both scriptID and flux' missingFluxError: summary: The request body requires either a flux parameter or scriptID parameter value: code: invalid message: 'failed to decode request: flux required' '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: create a Flux script task' source: | curl INFLUX_URL/api/v2/tasks \ --header "Content-type: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data-binary @- << EOF { "orgID": "INFLUX_ORG_ID", "description": "IoT Center 30d environment average.", "flux": "option task = {name: \"iot-center-task-1\", every: 30m}\ from(bucket: \"iot_center\")\ |> range(start: -30d)\ |> filter(fn: (r) => r._measurement == \"environment\")\ |> aggregateWindow(every: 1h, fn: mean)" } EOF - lang: Shell label: 'cURL: create a Flux script reference task' source: | curl INFLUX_URL/api/v2/tasks \ --header "Content-type: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --data-binary @- << EOF { "orgID": "INFLUX_ORG_ID", "description": "IoT Center 30d environment average.", "scriptID": "085138a111448000", "scriptParameters": { "rangeStart": "-30d", "bucket": "air_sensor", "filterField": "temperature", "groupColumn": "_time" } } EOF '/tasks/{taskID}': get: operationId: GetTasksID tags: - Data I/O endpoints - Tasks summary: Retrieve a task description: | Retrieves a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to retrieve. responses: '200': description: Success. The response body contains the task. content: application/json: schema: $ref: '#/components/schemas/Task' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' patch: operationId: PatchTasksID tags: - Tasks summary: Update a task description: | Updates a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), and then cancels all scheduled runs of the task. Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. To update a task, pass an object that contains the updated key-value pairs. To activate or inactivate a task, set the `status` property. _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. #### InfluxDB Cloud - Use either `flux` or `scriptID` to provide the task script. - `flux`: a string of "raw" Flux that contains task options and the script--for example: ```json { "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", "status": "active", "description": "This task downsamples CPU data every hour" } ``` - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body--for example: ```json { "name": "CPU Total 1 Hour New", "description": "This task downsamples CPU data every hour", "every": "1h", "scriptID": "SCRIPT_ID", "scriptParameters": { "rangeStart": "-1h", "bucket": "telegraf", "filterField": "cpu-total" } } ``` #### Limitations: - You can't use `flux` and `scriptID` for the same task. requestBody: description: An task update to apply. required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: | A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to update. responses: '200': description: Success. The response body contains the updated task. content: application/json: schema: $ref: '#/components/schemas/Task' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' delete: operationId: DeleteTasksID tags: - Tasks summary: Delete a task description: | Deletes a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and associated records. Use this endpoint to delete a task and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task. If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path name: taskID schema: type: string required: true description: 'A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to delete.' responses: '204': description: Success. The task and task runs are deleted. Scheduled runs are canceled. '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' components: parameters: 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 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 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 Descending: in: query name: descending required: false schema: type: boolean default: false SortBy: in: query name: sortBy required: false schema: type: string 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). schemas: LanguageRequest: description: Flux query to be analyzed. type: object required: - query properties: query: description: | The Flux query script to be analyzed. type: string Query: description: Query InfluxDB with the Flux language type: object required: - query properties: extern: $ref: '#/components/schemas/File' query: description: The query script to execute. type: string type: description: The type of query. Must be "flux". type: string enum: - flux params: type: object additionalProperties: true description: | Key-value pairs passed as parameters during query execution. To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: ```json query: "from(bucket: params.mybucket)\ |> range(start: params.rangeStart) |> limit(n:1)" ``` and pass _`params`_ with the key-value pairs--for example: ```json params: { "mybucket": "environment", "rangeStart": "-30d" } ``` During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. #### Limitations - If you use _`params`_, you can't use _`extern`_. dialect: $ref: '#/components/schemas/Dialect' now: description: | Specifies the time that should be reported as `now` in the query. Default is the server `now` time. type: string format: date-time Package: description: Represents a complete package source tree. type: object properties: type: $ref: '#/components/schemas/NodeType' path: description: Package import path type: string package: description: Package name type: string files: description: Package files type: array items: $ref: '#/components/schemas/File' File: description: Represents a source from a single file type: object properties: type: $ref: '#/components/schemas/NodeType' name: description: The name of the file. type: string package: $ref: '#/components/schemas/PackageClause' imports: description: A list of package imports type: array items: $ref: '#/components/schemas/ImportDeclaration' body: description: List of Flux statements type: array items: $ref: '#/components/schemas/Statement' PackageClause: description: Defines a package identifier type: object properties: type: $ref: '#/components/schemas/NodeType' name: $ref: '#/components/schemas/Identifier' ImportDeclaration: description: Declares a package import type: object properties: type: $ref: '#/components/schemas/NodeType' as: $ref: '#/components/schemas/Identifier' path: $ref: '#/components/schemas/StringLiteral' DeletePredicateRequest: description: The delete predicate request. type: object required: - start - stop properties: start: description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. type: string format: date-time stop: description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. type: string format: date-time predicate: description: | An expression in [delete predicate syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string Node: oneOf: - $ref: '#/components/schemas/Expression' - $ref: '#/components/schemas/Block' NodeType: description: Type of AST node type: string Block: description: A set of statements type: object properties: type: $ref: '#/components/schemas/NodeType' body: description: Block body type: array items: $ref: '#/components/schemas/Statement' Statement: oneOf: - $ref: '#/components/schemas/BadStatement' - $ref: '#/components/schemas/VariableAssignment' - $ref: '#/components/schemas/MemberAssignment' - $ref: '#/components/schemas/ExpressionStatement' - $ref: '#/components/schemas/ReturnStatement' - $ref: '#/components/schemas/OptionStatement' - $ref: '#/components/schemas/BuiltinStatement' - $ref: '#/components/schemas/TestStatement' BadStatement: description: A placeholder for statements for which no correct statement nodes can be created type: object properties: type: $ref: '#/components/schemas/NodeType' text: description: Raw source text type: string VariableAssignment: description: Represents the declaration of a variable type: object properties: type: $ref: '#/components/schemas/NodeType' id: $ref: '#/components/schemas/Identifier' init: $ref: '#/components/schemas/Expression' MemberAssignment: description: Object property assignment type: object properties: type: $ref: '#/components/schemas/NodeType' member: $ref: '#/components/schemas/MemberExpression' init: $ref: '#/components/schemas/Expression' ExpressionStatement: description: May consist of an expression that doesn't return a value and is executed solely for its side-effects type: object properties: type: $ref: '#/components/schemas/NodeType' expression: $ref: '#/components/schemas/Expression' ReturnStatement: description: Defines an expression to return type: object properties: type: $ref: '#/components/schemas/NodeType' argument: $ref: '#/components/schemas/Expression' OptionStatement: description: A single variable declaration type: object properties: type: $ref: '#/components/schemas/NodeType' assignment: oneOf: - $ref: '#/components/schemas/VariableAssignment' - $ref: '#/components/schemas/MemberAssignment' BuiltinStatement: description: Declares a builtin identifier and its type type: object properties: type: $ref: '#/components/schemas/NodeType' id: $ref: '#/components/schemas/Identifier' TestStatement: description: Declares a Flux test case type: object properties: type: $ref: '#/components/schemas/NodeType' assignment: $ref: '#/components/schemas/VariableAssignment' Expression: oneOf: - $ref: '#/components/schemas/ArrayExpression' - $ref: '#/components/schemas/DictExpression' - $ref: '#/components/schemas/FunctionExpression' - $ref: '#/components/schemas/BinaryExpression' - $ref: '#/components/schemas/CallExpression' - $ref: '#/components/schemas/ConditionalExpression' - $ref: '#/components/schemas/LogicalExpression' - $ref: '#/components/schemas/MemberExpression' - $ref: '#/components/schemas/IndexExpression' - $ref: '#/components/schemas/ObjectExpression' - $ref: '#/components/schemas/ParenExpression' - $ref: '#/components/schemas/PipeExpression' - $ref: '#/components/schemas/UnaryExpression' - $ref: '#/components/schemas/BooleanLiteral' - $ref: '#/components/schemas/DateTimeLiteral' - $ref: '#/components/schemas/DurationLiteral' - $ref: '#/components/schemas/FloatLiteral' - $ref: '#/components/schemas/IntegerLiteral' - $ref: '#/components/schemas/PipeLiteral' - $ref: '#/components/schemas/RegexpLiteral' - $ref: '#/components/schemas/StringLiteral' - $ref: '#/components/schemas/UnsignedIntegerLiteral' - $ref: '#/components/schemas/Identifier' ArrayExpression: description: Used to create and directly specify the elements of an array object type: object properties: type: $ref: '#/components/schemas/NodeType' elements: description: Elements of the array type: array items: $ref: '#/components/schemas/Expression' DictExpression: description: Used to create and directly specify the elements of a dictionary type: object properties: type: $ref: '#/components/schemas/NodeType' elements: description: Elements of the dictionary type: array items: $ref: '#/components/schemas/DictItem' DictItem: description: A key-value pair in a dictionary. type: object properties: type: $ref: '#/components/schemas/NodeType' key: $ref: '#/components/schemas/Expression' val: $ref: '#/components/schemas/Expression' FunctionExpression: description: Function expression type: object properties: type: $ref: '#/components/schemas/NodeType' params: description: Function parameters type: array items: $ref: '#/components/schemas/Property' body: $ref: '#/components/schemas/Node' BinaryExpression: description: uses binary operators to act on two operands in an expression type: object properties: type: $ref: '#/components/schemas/NodeType' operator: type: string left: $ref: '#/components/schemas/Expression' right: $ref: '#/components/schemas/Expression' CallExpression: description: Represents a function call type: object properties: type: $ref: '#/components/schemas/NodeType' callee: $ref: '#/components/schemas/Expression' arguments: description: Function arguments type: array items: $ref: '#/components/schemas/Expression' ConditionalExpression: description: 'Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test`' type: object properties: type: $ref: '#/components/schemas/NodeType' test: $ref: '#/components/schemas/Expression' alternate: $ref: '#/components/schemas/Expression' consequent: $ref: '#/components/schemas/Expression' LogicalExpression: description: Represents the rule conditions that collectively evaluate to either true or false type: object properties: type: $ref: '#/components/schemas/NodeType' operator: type: string left: $ref: '#/components/schemas/Expression' right: $ref: '#/components/schemas/Expression' MemberExpression: description: Represents accessing a property of an object type: object properties: type: $ref: '#/components/schemas/NodeType' object: $ref: '#/components/schemas/Expression' property: $ref: '#/components/schemas/PropertyKey' IndexExpression: description: Represents indexing into an array type: object properties: type: $ref: '#/components/schemas/NodeType' array: $ref: '#/components/schemas/Expression' index: $ref: '#/components/schemas/Expression' ObjectExpression: description: Allows the declaration of an anonymous object within a declaration type: object properties: type: $ref: '#/components/schemas/NodeType' properties: description: Object properties type: array items: $ref: '#/components/schemas/Property' ParenExpression: description: Represents an expression wrapped in parenthesis type: object properties: type: $ref: '#/components/schemas/NodeType' expression: $ref: '#/components/schemas/Expression' PipeExpression: description: Call expression with pipe argument type: object properties: type: $ref: '#/components/schemas/NodeType' argument: $ref: '#/components/schemas/Expression' call: $ref: '#/components/schemas/CallExpression' UnaryExpression: description: Uses operators to act on a single operand in an expression type: object properties: type: $ref: '#/components/schemas/NodeType' operator: type: string argument: $ref: '#/components/schemas/Expression' BooleanLiteral: description: Represents boolean values type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: boolean DateTimeLiteral: description: 'Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp).' type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: string format: date-time DurationLiteral: description: Represents the elapsed time between two instants as an int64 nanosecond count with syntax of golang's time.Duration type: object properties: type: $ref: '#/components/schemas/NodeType' values: description: Duration values type: array items: $ref: '#/components/schemas/Duration' FloatLiteral: description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: number IntegerLiteral: description: Represents integer numbers type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: string PipeLiteral: description: 'Represents a specialized literal value, indicating the left hand value of a pipe expression' type: object properties: type: $ref: '#/components/schemas/NodeType' RegexpLiteral: description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: string StringLiteral: description: Expressions begin and end with double quote marks type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: string UnsignedIntegerLiteral: description: Represents integer numbers type: object properties: type: $ref: '#/components/schemas/NodeType' value: type: string Duration: description: A pair consisting of length of time and the unit of time measured. It is the atomic unit from which all duration literals are composed. type: object properties: type: $ref: '#/components/schemas/NodeType' magnitude: type: integer unit: type: string Property: description: The value associated with a key type: object properties: type: $ref: '#/components/schemas/NodeType' key: $ref: '#/components/schemas/PropertyKey' value: $ref: '#/components/schemas/Expression' PropertyKey: oneOf: - $ref: '#/components/schemas/Identifier' - $ref: '#/components/schemas/StringLiteral' Identifier: description: A valid Flux identifier type: object properties: type: $ref: '#/components/schemas/NodeType' name: type: string Dialect: description: | Options for tabular data output. Default output is [annotated CSV](https://docs.influxdata.com/influxdb/cloud/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). type: object properties: header: description: 'If true, the results contain a header row.' type: boolean default: true delimiter: description: 'The separator used between cells. Default is a comma (`,`).' type: string default: ',' maxLength: 1 minLength: 1 annotations: description: | Annotation rows to include in the results. An _annotation_ is metadata associated with an object (column) in the data model. #### Related guides - See [Annotated CSV annotations](https://docs.influxdata.com/influxdb/cloud/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). type: array uniqueItems: true items: type: string enum: - group - datatype - default commentPrefix: description: The character prefixed to comment strings. Default is a number sign (`#`). type: string default: '#' maxLength: 1 minLength: 0 dateTimeFormat: description: | The format for timestamps in results. Default is [`RFC3339` date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. #### Example formatted date/time values | Format | Value | |:------------|:----------------------------| | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | | `RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | type: string default: RFC3339 enum: - RFC3339 - RFC3339Nano Authorization: required: - orgID - permissions allOf: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - type: object properties: createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true orgID: type: string description: | The organization ID. Specifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that the authorization is scoped to. permissions: type: array minItems: 1 description: | The list of permissions. An authorization must have at least one permission. items: $ref: '#/components/schemas/Permission' id: readOnly: true type: string description: The authorization ID. token: readOnly: true type: string description: | The API token. The token value is unique to the authorization. [API tokens](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) are used to authenticate and authorize InfluxDB API requests and `influx` CLI commands--after receiving the request, InfluxDB checks that the token is valid and that the `permissions` allow the requested action(s). userID: readOnly: true type: string description: 'The user ID. Specifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization.' user: readOnly: true type: string description: | The user name. Specifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the authorization. If the authorization is _scoped_ to a user, the user; otherwise, the creator of the authorization. org: readOnly: true type: string description: | The organization name. Specifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that the token is scoped to. links: type: object readOnly: true example: self: /api/v2/authorizations/1 user: /api/v2/users/12 properties: self: readOnly: true $ref: '#/components/schemas/Link' user: readOnly: true $ref: '#/components/schemas/Link' Authorizations: type: object properties: links: readOnly: true $ref: '#/components/schemas/Links' authorizations: type: array items: $ref: '#/components/schemas/Authorization' AuthorizationPostRequest: required: - orgID - permissions allOf: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - type: object properties: orgID: type: string description: | An organization ID. Specifies the organization that owns the authorization. userID: type: string description: | A user ID. Specifies the user that the authorization is scoped to. When a user authenticates with username and password, InfluxDB generates a _user session_ with all the permissions specified by all the user's authorizations. permissions: type: array minItems: 1 description: | A list of permissions for an authorization. In the list, provide at least one `permission` object. In a `permission`, the `resource.type` property grants access to all resources of the specified type. To grant access to only a specific resource, specify the `resource.id` property. items: $ref: '#/components/schemas/Permission' AuthorizationUpdateRequest: properties: status: description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' default: active type: string enum: - active - inactive description: type: string description: A description of the token. 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 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 Buckets: type: object properties: links: readOnly: true $ref: '#/components/schemas/Links' buckets: type: array items: $ref: '#/components/schemas/Bucket' 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' 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' PatchRetentionRules: type: array description: Updates to rules to expire or retain data. No rules means no updates. items: $ref: '#/components/schemas/PatchRetentionRule' 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 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 Link: type: string format: uri readOnly: true description: URI of resource. 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 Logs: type: object properties: events: readOnly: true type: array items: $ref: '#/components/schemas/LogEvent' LogEvent: type: object properties: time: readOnly: true description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp)) that the event occurred.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' message: readOnly: true description: A description of the event that occurred. type: string example: Halt and catch fire runID: readOnly: true description: The ID of the task run that generated the event. type: string Organization: properties: links: type: object readOnly: true example: self: /api/v2/orgs/1 members: /api/v2/orgs/1/members owners: /api/v2/orgs/1/owners labels: /api/v2/orgs/1/labels secrets: /api/v2/orgs/1/secrets buckets: /api/v2/buckets?org=myorg tasks: /api/v2/tasks?org=myorg dashboards: /api/v2/dashboards?org=myorg properties: self: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' secrets: $ref: '#/components/schemas/Link' buckets: $ref: '#/components/schemas/Link' tasks: $ref: '#/components/schemas/Link' dashboards: $ref: '#/components/schemas/Link' id: readOnly: true type: string name: type: string defaultStorageType: description: Discloses whether the organization uses TSM or IOx. type: string enum: - tsm - iox description: type: string createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true status: description: 'If inactive, the organization is inactive.' default: active type: string enum: - active - inactive required: - name Organizations: type: object properties: links: $ref: '#/components/schemas/Links' orgs: type: array items: $ref: '#/components/schemas/Organization' PostOrganizationRequest: type: object properties: name: type: string description: | The name of the organization. description: type: string description: | The description of the organization. required: - name PatchOrganizationRequest: type: object description: | An object that contains updated organization properties to apply. properties: name: type: string description: | The name of the organization. description: type: string description: | The description of the organization. TemplateApply: type: object properties: dryRun: type: boolean description: | Only applies a dry run of the templates passed in the request. - Validates the template and generates a resource diff and summary. - Doesn't install templates or make changes to the InfluxDB instance. orgID: type: string description: | Organization ID. InfluxDB applies templates to this organization. The organization owns all resources created by the template. To find your organization, see how to [view organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/). stackID: type: string description: | ID of the stack to update. To apply templates to an existing stack in the organization, use the `stackID` parameter. If you apply templates without providing a stack ID, InfluxDB initializes a new stack with all new resources. To find a stack ID, use the InfluxDB [`/api/v2/stacks` API endpoint](#operation/ListStacks) to list stacks. #### Related guides - [Stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [View stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/view/) template: type: object description: | A template object to apply. A template object has a `contents` property with an array of InfluxDB resource configurations. Pass `template` to apply only one template object. If you use `template`, you can't use the `templates` parameter. If you want to apply multiple template objects, use `templates` instead. properties: contentType: type: string sources: type: array items: type: string contents: $ref: '#/components/schemas/Template' templates: type: array description: | A list of template objects to apply. A template object has a `contents` property with an array of InfluxDB resource configurations. Use the `templates` parameter to apply multiple template objects. If you use `templates`, you can't use the `template` parameter. items: type: object properties: contentType: type: string sources: type: array items: type: string contents: $ref: '#/components/schemas/Template' envRefs: type: object description: | An object with key-value pairs that map to **environment references** in templates. Environment references in templates are `envRef` objects with an `envRef.key` property. To substitute a custom environment reference value when applying templates, pass `envRefs` with the `envRef.key` and the value. When you apply a template, InfluxDB replaces `envRef` objects in the template with the values that you provide in the `envRefs` parameter. For more examples, see how to [define environment references](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: - `metadata.name` - `spec.endpointName` - `spec.associations.name` For more information about including environment references in template fields, see how to [include user-definable resource names](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names). additionalProperties: oneOf: - type: string - type: integer - type: number - type: boolean secrets: type: object description: | An object with key-value pairs that map to **secrets** in queries. Queries may reference secrets stored in InfluxDB--for example, the following Flux script retrieves `POSTGRES_USERNAME` and `POSTGRES_PASSWORD` secrets and then uses them to connect to a PostgreSQL database: ```js import "sql" import "influxdata/influxdb/secrets" username = secrets.get(key: "POSTGRES_USERNAME") password = secrets.get(key: "POSTGRES_PASSWORD") sql.from( driverName: "postgres", dataSourceName: "postgresql://${username}:${password}@localhost:5432", query: "SELECT * FROM example_table", ) ``` To define secret values in your `/api/v2/templates/apply` request, pass the `secrets` parameter with key-value pairs--for example: ```json { ... "secrets": { "POSTGRES_USERNAME": "pguser", "POSTGRES_PASSWORD": "foo" } ... } ``` InfluxDB stores the key-value pairs as secrets that you can access with `secrets.get()`. Once stored, you can't view secret values in InfluxDB. #### Related guides - [How to pass secrets when installing a template](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template) additionalProperties: type: string remotes: type: array description: | A list of URLs for template files. To apply a template manifest file located at a URL, pass `remotes` with an array that contains the URL. items: type: object properties: url: type: string contentType: type: string required: - url actions: type: array description: | A list of `action` objects. Actions let you customize how InfluxDB applies templates in the request. You can use the following actions to prevent creating or updating resources: - A `skipKind` action skips template resources of a specified `kind`. - A `skipResource` action skips template resources with a specified `metadata.name` and `kind`. items: oneOf: - type: object properties: action: type: string enum: - skipKind properties: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' required: - kind - type: object properties: action: type: string enum: - skipResource properties: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' resourceTemplateName: type: string required: - kind - resourceTemplateName TemplateKind: type: string enum: - Bucket - Check - CheckDeadman - CheckThreshold - Dashboard - Label - NotificationEndpoint - NotificationEndpointHTTP - NotificationEndpointPagerDuty - NotificationEndpointSlack - NotificationRule - Task - Telegraf - Variable TemplateExportByID: type: object properties: stackID: type: string orgIDs: type: array items: type: object properties: orgID: type: string resourceFilters: type: object properties: byLabel: type: array items: type: string byResourceKind: type: array items: $ref: '#/components/schemas/TemplateKind' resources: type: array items: type: object properties: id: type: string kind: $ref: '#/components/schemas/TemplateKind' name: type: string description: 'if defined with id, name is used for resource exported by id. if defined independently, resources strictly matching name are exported' required: - id - kind TemplateExportByName: type: object properties: stackID: type: string orgIDs: type: array items: type: object properties: orgID: type: string resourceFilters: type: object properties: byLabel: type: array items: type: string byResourceKind: type: array items: $ref: '#/components/schemas/TemplateKind' resources: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' name: type: string required: - name - kind Template: type: array items: type: object description: | A template entry. Defines an InfluxDB resource in a template. properties: apiVersion: type: string example: influxdata.com/v2alpha1 kind: $ref: '#/components/schemas/TemplateKind' metadata: type: object description: | Metadata properties used for the resource when the template is applied. properties: name: type: string spec: type: object description: | Configuration properties used for the resource when the template is applied. Key-value pairs map to the specification for the resource. The following code samples show `spec` configurations for template resources: - A bucket: ```json { "spec": { "name": "iot_center", "retentionRules": [{ "everySeconds": 2.592e+06, "type": "expire" }] } } ``` - A variable: ```json { "spec": { "language": "flux", "name": "Node_Service", "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", tag: \"service\")", "type": "query" } } ``` TemplateEnvReferences: type: array items: type: object properties: resourceField: type: string description: Field the environment reference corresponds too envRefKey: type: string description: Key identified as environment reference and is the key identified in the template value: description: Value provided to fulfill reference oneOf: - type: string nullable: true - type: integer nullable: true - type: number nullable: true - type: boolean nullable: true defaultValue: description: Default value that will be provided for the reference when no value is provided oneOf: - type: string nullable: true - type: integer nullable: true - type: number nullable: true - type: boolean nullable: true required: - resourceField - envRefKey TemplateSummary: type: object properties: sources: type: array items: type: string stackID: type: string summary: type: object properties: buckets: type: array items: type: object properties: id: type: string orgID: type: string kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string name: type: string description: type: string retentionPeriod: type: integer labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' checks: type: array items: allOf: - $ref: '#/components/schemas/CheckDiscriminator' - type: object properties: kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' dashboards: type: array items: type: object properties: id: type: string orgID: type: string kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string name: type: string description: type: string labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' charts: type: array items: $ref: '#/components/schemas/TemplateChart' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' labels: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' labelMappings: type: array items: type: object properties: status: type: string resourceTemplateMetaName: type: string resourceName: type: string resourceID: type: string resourceType: type: string labelTemplateMetaName: type: string labelName: type: string labelID: type: string missingEnvRefs: type: array items: type: string missingSecrets: type: array items: type: string notificationEndpoints: type: array items: allOf: - $ref: '#/components/schemas/NotificationEndpointDiscriminator' - type: object properties: kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' notificationRules: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string name: type: string description: type: string endpointTemplateMetaName: type: string endpointID: type: string endpointType: type: string every: type: string offset: type: string messageTemplate: type: string status: type: string statusRules: type: array items: type: object properties: currentLevel: type: string previousLevel: type: string tagRules: type: array items: type: object properties: key: type: string value: type: string operator: type: string labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' tasks: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string id: type: string name: type: string cron: type: string description: type: string every: type: string offset: type: string query: type: string status: type: string envReferences: $ref: '#/components/schemas/TemplateEnvReferences' telegrafConfigs: type: array items: allOf: - $ref: '#/components/schemas/TelegrafRequest' - type: object properties: kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' variables: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string id: type: string orgID: type: string name: type: string description: type: string arguments: $ref: '#/components/schemas/VariableProperties' labelAssociations: type: array items: $ref: '#/components/schemas/TemplateSummaryLabel' envReferences: $ref: '#/components/schemas/TemplateEnvReferences' diff: type: object properties: buckets: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: type: object properties: name: type: string description: type: string retentionRules: $ref: '#/components/schemas/RetentionRules' old: type: object properties: name: type: string description: type: string retentionRules: $ref: '#/components/schemas/RetentionRules' checks: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: $ref: '#/components/schemas/CheckDiscriminator' old: $ref: '#/components/schemas/CheckDiscriminator' dashboards: type: array items: type: object properties: stateStatus: type: string id: type: string kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string new: type: object properties: name: type: string description: type: string charts: type: array items: $ref: '#/components/schemas/TemplateChart' old: type: object properties: name: type: string description: type: string charts: type: array items: $ref: '#/components/schemas/TemplateChart' labels: type: array items: type: object properties: stateStatus: type: string kind: $ref: '#/components/schemas/TemplateKind' id: type: string templateMetaName: type: string new: type: object properties: name: type: string color: type: string description: type: string old: type: object properties: name: type: string color: type: string description: type: string labelMappings: type: array items: type: object properties: status: type: string resourceType: type: string resourceID: type: string resourceTemplateMetaName: type: string resourceName: type: string labelID: type: string labelTemplateMetaName: type: string labelName: type: string notificationEndpoints: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: $ref: '#/components/schemas/NotificationEndpointDiscriminator' old: $ref: '#/components/schemas/NotificationEndpointDiscriminator' notificationRules: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: type: object properties: name: type: string description: type: string endpointName: type: string endpointID: type: string endpointType: type: string every: type: string offset: type: string messageTemplate: type: string status: type: string statusRules: type: array items: type: object properties: currentLevel: type: string previousLevel: type: string tagRules: type: array items: type: object properties: key: type: string value: type: string operator: type: string old: type: object properties: name: type: string description: type: string endpointName: type: string endpointID: type: string endpointType: type: string every: type: string offset: type: string messageTemplate: type: string status: type: string statusRules: type: array items: type: object properties: currentLevel: type: string previousLevel: type: string tagRules: type: array items: type: object properties: key: type: string value: type: string operator: type: string tasks: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: type: object properties: name: type: string cron: type: string description: type: string every: type: string offset: type: string query: type: string status: type: string old: type: object properties: name: type: string cron: type: string description: type: string every: type: string offset: type: string query: type: string status: type: string telegrafConfigs: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: $ref: '#/components/schemas/TelegrafRequest' old: $ref: '#/components/schemas/TelegrafRequest' variables: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' stateStatus: type: string id: type: string templateMetaName: type: string new: type: object properties: name: type: string description: type: string args: $ref: '#/components/schemas/VariableProperties' old: type: object properties: name: type: string description: type: string args: $ref: '#/components/schemas/VariableProperties' errors: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' reason: type: string fields: type: array items: type: string indexes: type: array items: type: integer TemplateSummaryLabel: type: object properties: id: type: string orgID: type: string kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string name: type: string properties: type: object properties: color: type: string description: type: string envReferences: $ref: '#/components/schemas/TemplateEnvReferences' TemplateChart: type: object properties: xPos: type: integer yPos: type: integer height: type: integer width: type: integer properties: $ref: '#/components/schemas/ViewProperties' Stack: type: object properties: id: type: string orgID: type: string createdAt: type: string format: date-time readOnly: true events: type: array items: type: object properties: eventType: type: string name: type: string description: type: string sources: type: array items: type: string resources: type: array items: type: object properties: apiVersion: type: string resourceID: type: string kind: $ref: '#/components/schemas/TemplateKind' templateMetaName: type: string associations: type: array items: type: object properties: kind: $ref: '#/components/schemas/TemplateKind' metaName: type: string links: type: object properties: self: type: string urls: type: array items: type: string updatedAt: type: string format: date-time readOnly: true Runs: type: object properties: links: $ref: '#/components/schemas/Links' runs: type: array items: $ref: '#/components/schemas/Run' Run: properties: id: readOnly: true type: string taskID: readOnly: true type: string status: readOnly: true type: string enum: - scheduled - started - failed - success - canceled scheduledFor: description: 'The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp) used for the run''s `now` option.' type: string format: date-time log: description: An array of logs associated with the run. type: array readOnly: true items: $ref: '#/components/schemas/LogEvent' flux: description: Flux used for the task type: string readOnly: true startedAt: readOnly: true description: 'The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' finishedAt: readOnly: true description: 'The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' requestedAt: readOnly: true description: 'The time ([RFC3339Nano date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested.' type: string format: date-time example: '2006-01-02T15:04:05.999999999Z07:00' links: type: object readOnly: true example: self: /api/v2/tasks/1/runs/1 task: /api/v2/tasks/1 retry: /api/v2/tasks/1/runs/1/retry properties: self: type: string format: uri task: type: string format: uri retry: type: string format: uri RunManually: properties: scheduledFor: nullable: true description: | The time [RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. Default is the server _now_ time. type: string format: date-time TaskStatusType: type: string enum: - active - inactive description: | `inactive` cancels scheduled runs and prevents manual runs of the task. 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 Flags: type: object additionalProperties: true Resource: type: object required: - type properties: type: type: string enum: - authorizations - buckets - dashboards - orgs - tasks - telegrafs - users - variables - secrets - labels - views - documents - notificationRules - notificationEndpoints - checks - dbrp - annotations - sources - scrapers - notebooks - remotes - replications - instance - flows - functions - subscriptions description: | A resource type. Identifies the API resource's type (or _kind_). id: type: string description: | A resource ID. Identifies a specific resource. name: type: string description: | The name of the resource. _Note: not all resource types have a `name` property_. orgID: type: string description: | An organization ID. Identifies the organization that owns the resource. org: type: string description: | An organization name. The organization that owns the resource. ResourceMember: allOf: - $ref: '#/components/schemas/UserResponse' - type: object properties: role: type: string default: member enum: - member ResourceMembers: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/ResourceMember' ResourceOwner: allOf: - $ref: '#/components/schemas/UserResponse' - type: object properties: role: type: string default: owner enum: - owner ResourceOwners: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/ResourceOwner' FluxSuggestions: type: object properties: funcs: type: array items: $ref: '#/components/schemas/FluxSuggestion' FluxSuggestion: type: object properties: name: type: string params: type: object additionalProperties: type: string Routes: properties: authorizations: type: string format: uri backup: type: string format: uri buckets: type: string format: uri dashboards: type: string format: uri external: type: object properties: statusFeed: type: string format: uri variables: type: string format: uri me: type: string format: uri notificationRules: type: string format: uri notificationEndpoints: type: string format: uri flags: type: string format: uri invocableScripts: type: string format: uri labels: type: string format: uri orgs: type: string format: uri query: type: object properties: self: type: string format: uri ast: type: string format: uri analyze: type: string format: uri suggestions: type: string format: uri restore: type: string format: uri setup: type: string format: uri signin: type: string format: uri signout: type: string format: uri sources: type: string format: uri scrapers: type: string format: uri swagger: type: string format: uri system: type: object properties: metrics: type: string format: uri debug: type: string format: uri health: type: string format: uri ready: type: string format: uri tasks: type: string format: uri checks: type: string format: uri telegraf: type: object properties: plugins: type: string format: uri telegrafs: type: string format: uri plugins: type: string format: uri users: type: string format: uri write: type: string format: uri delete: type: string format: uri 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 LineProtocolError: properties: code: description: Code is the machine-readable error code. readOnly: true type: string enum: - internal error - not found - conflict - invalid - empty value - unavailable 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 line: readOnly: true description: First line in the request body that contains malformed data. type: integer format: int32 required: - code LineProtocolLengthError: properties: code: description: Code is the machine-readable error code. readOnly: true type: string enum: - invalid message: readOnly: true description: Human-readable message. type: string required: - code - message Field: type: object properties: value: description: value is the value of the field. Meaning of the value is implied by the `type` key type: string type: description: '`type` describes the field type. `func` is a function. `field` is a field reference.' type: string enum: - func - field - integer - number - regex - wildcard alias: description: Alias overrides the field name in the returned response. Applies only if type is `func` type: string args: description: Args are the arguments to the function type: array items: $ref: '#/components/schemas/Field' BuilderConfig: type: object properties: buckets: type: array items: type: string tags: type: array items: $ref: '#/components/schemas/BuilderTagsType' functions: type: array items: $ref: '#/components/schemas/BuilderFunctionsType' aggregateWindow: type: object properties: period: type: string fillValues: type: boolean BuilderTagsType: type: object properties: key: type: string values: type: array items: type: string aggregateFunctionType: $ref: '#/components/schemas/BuilderAggregateFunctionType' BuilderAggregateFunctionType: type: string enum: - filter - group BuilderFunctionsType: type: object properties: name: type: string DashboardQuery: type: object properties: text: type: string description: The text of the Flux query. editMode: $ref: '#/components/schemas/QueryEditMode' name: type: string builderConfig: $ref: '#/components/schemas/BuilderConfig' QueryEditMode: type: string enum: - builder - advanced Axis: type: object description: Axis used in a visualization. properties: bounds: type: array minItems: 0 maxItems: 2 description: 'The extents of the axis in the form [lower, upper]. Clients determine whether bounds are inclusive or exclusive of their limits.' items: type: string label: description: Description of the axis. type: string prefix: description: Label prefix for formatting axis values. type: string suffix: description: Label suffix for formatting axis values. type: string base: description: Radix for formatting axis values. type: string enum: - '' - '2' - '10' scale: $ref: '#/components/schemas/AxisScale' AxisScale: description: 'Scale is the axis formatting scale. Supported: "log", "linear"' type: string enum: - log - linear DashboardColor: type: object description: Defines an encoding of data value into color space. required: - id - type - hex - name - value properties: id: description: The unique ID of the view color. type: string type: description: Type is how the color is used. type: string enum: - min - max - threshold - scale - text - background hex: description: The hex number of the color type: string maxLength: 7 minLength: 7 name: description: The user-facing name of the hex color. type: string value: description: The data value mapped to this color. type: number format: float RenamableField: description: Describes a field that can be renamed and made visible or invisible. type: object properties: internalName: description: The calculated name of a field. readOnly: true type: string displayName: description: The name that a field is renamed to by the user. type: string visible: description: Indicates whether this field should be visible on the table. type: boolean XYViewProperties: type: object required: - type - geom - queries - shape - axes - colors - note - showNoteWhenEmpty - position properties: adaptiveZoomHide: type: boolean timeFormat: type: string type: type: string enum: - xy queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' colorMapping: description: An object that contains information about the color mapping $ref: '#/components/schemas/ColorMapping' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean axes: $ref: '#/components/schemas/Axes' staticLegend: $ref: '#/components/schemas/StaticLegend' xColumn: type: string generateXAxisTicks: type: array items: type: string xTotalTicks: type: integer xTickStart: type: number format: float xTickStep: type: number format: float yColumn: type: string generateYAxisTicks: type: array items: type: string yTotalTicks: type: integer yTickStart: type: number format: float yTickStep: type: number format: float shadeBelow: type: boolean hoverDimension: type: string enum: - auto - x - 'y' - xy position: type: string enum: - overlaid - stacked geom: $ref: '#/components/schemas/XYGeom' legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer XYGeom: type: string enum: - line - step - stacked - bar - monotoneX - stepBefore - stepAfter BandViewProperties: type: object required: - type - geom - queries - shape - axes - colors - note - showNoteWhenEmpty properties: adaptiveZoomHide: type: boolean timeFormat: type: string type: type: string enum: - band queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean axes: $ref: '#/components/schemas/Axes' staticLegend: $ref: '#/components/schemas/StaticLegend' xColumn: type: string generateXAxisTicks: type: array items: type: string xTotalTicks: type: integer xTickStart: type: number format: float xTickStep: type: number format: float yColumn: type: string generateYAxisTicks: type: array items: type: string yTotalTicks: type: integer yTickStart: type: number format: float yTickStep: type: number format: float upperColumn: type: string mainColumn: type: string lowerColumn: type: string hoverDimension: type: string enum: - auto - x - 'y' - xy geom: $ref: '#/components/schemas/XYGeom' legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer LinePlusSingleStatProperties: type: object required: - type - queries - shape - axes - colors - note - showNoteWhenEmpty - prefix - suffix - decimalPlaces - position properties: adaptiveZoomHide: type: boolean timeFormat: type: string type: type: string enum: - line-plus-single-stat queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean axes: $ref: '#/components/schemas/Axes' staticLegend: $ref: '#/components/schemas/StaticLegend' xColumn: type: string generateXAxisTicks: type: array items: type: string xTotalTicks: type: integer xTickStart: type: number format: float xTickStep: type: number format: float yColumn: type: string generateYAxisTicks: type: array items: type: string yTotalTicks: type: integer yTickStart: type: number format: float yTickStep: type: number format: float shadeBelow: type: boolean hoverDimension: type: string enum: - auto - x - 'y' - xy position: type: string enum: - overlaid - stacked prefix: type: string suffix: type: string decimalPlaces: $ref: '#/components/schemas/DecimalPlaces' legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer MosaicViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - xColumn - ySeriesColumns - fillColumns - xDomain - yDomain - xAxisLabel - yAxisLabel - xPrefix - yPrefix - xSuffix - ySuffix properties: timeFormat: type: string type: type: string enum: - mosaic queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: type: string shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean xColumn: type: string generateXAxisTicks: type: array items: type: string xTotalTicks: type: integer xTickStart: type: number format: float xTickStep: type: number format: float yLabelColumnSeparator: type: string yLabelColumns: type: array items: type: string ySeriesColumns: type: array items: type: string fillColumns: type: array items: type: string xDomain: type: array items: type: number maxItems: 2 yDomain: type: array items: type: number maxItems: 2 xAxisLabel: type: string yAxisLabel: type: string xPrefix: type: string xSuffix: type: string yPrefix: type: string ySuffix: type: string hoverDimension: type: string enum: - auto - x - 'y' - xy legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer ScatterViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - xColumn - yColumn - fillColumns - symbolColumns - xDomain - yDomain - xAxisLabel - yAxisLabel - xPrefix - yPrefix - xSuffix - ySuffix properties: adaptiveZoomHide: type: boolean timeFormat: type: string type: type: string enum: - scatter queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: type: string shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean xColumn: type: string generateXAxisTicks: type: array items: type: string xTotalTicks: type: integer xTickStart: type: number format: float xTickStep: type: number format: float yColumn: type: string generateYAxisTicks: type: array items: type: string yTotalTicks: type: integer yTickStart: type: number format: float yTickStep: type: number format: float fillColumns: type: array items: type: string symbolColumns: type: array items: type: string xDomain: type: array items: type: number maxItems: 2 yDomain: type: array items: type: number maxItems: 2 xAxisLabel: type: string yAxisLabel: type: string xPrefix: type: string xSuffix: type: string yPrefix: type: string ySuffix: type: string legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer HeatmapViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - xColumn - yColumn - xDomain - yDomain - xAxisLabel - yAxisLabel - xPrefix - yPrefix - xSuffix - ySuffix - binSize properties: adaptiveZoomHide: type: boolean timeFormat: type: string type: type: string enum: - heatmap queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: type: string shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean xColumn: type: string generateXAxisTicks: type: array items: type: string xTotalTicks: type: integer xTickStart: type: number format: float xTickStep: type: number format: float yColumn: type: string generateYAxisTicks: type: array items: type: string yTotalTicks: type: integer yTickStart: type: number format: float yTickStep: type: number format: float xDomain: type: array items: type: number maxItems: 2 yDomain: type: array items: type: number maxItems: 2 xAxisLabel: type: string yAxisLabel: type: string xPrefix: type: string xSuffix: type: string yPrefix: type: string ySuffix: type: string binSize: type: number legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer SingleStatViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - prefix - tickPrefix - suffix - tickSuffix - decimalPlaces properties: type: type: string enum: - single-stat queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean prefix: type: string tickPrefix: type: string suffix: type: string tickSuffix: type: string staticLegend: $ref: '#/components/schemas/StaticLegend' decimalPlaces: $ref: '#/components/schemas/DecimalPlaces' HistogramViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - xColumn - fillColumns - xDomain - xAxisLabel - position - binCount properties: type: type: string enum: - histogram queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean xColumn: type: string fillColumns: type: array items: type: string xDomain: type: array items: type: number format: float xAxisLabel: type: string position: type: string enum: - overlaid - stacked binCount: type: integer legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer GaugeViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - prefix - tickPrefix - suffix - tickSuffix - decimalPlaces properties: type: type: string enum: - gauge queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean prefix: type: string tickPrefix: type: string suffix: type: string tickSuffix: type: string decimalPlaces: $ref: '#/components/schemas/DecimalPlaces' TableViewProperties: type: object required: - type - queries - colors - shape - note - showNoteWhenEmpty - tableOptions - fieldOptions - timeFormat - decimalPlaces properties: type: type: string enum: - table queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean tableOptions: type: object properties: verticalTimeAxis: description: verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically type: boolean sortBy: $ref: '#/components/schemas/RenamableField' wrapping: description: Wrapping describes the text wrapping style to be used in table views type: string enum: - truncate - wrap - single-line fixFirstColumn: description: fixFirstColumn indicates whether the first column of the table should be locked type: boolean fieldOptions: description: fieldOptions represent the fields retrieved by the query with customization options type: array items: $ref: '#/components/schemas/RenamableField' timeFormat: description: timeFormat describes the display format for time values according to moment.js date formatting type: string decimalPlaces: $ref: '#/components/schemas/DecimalPlaces' SimpleTableViewProperties: type: object required: - type - showAll - queries - shape - note - showNoteWhenEmpty properties: type: type: string enum: - simple-table showAll: type: boolean queries: type: array items: $ref: '#/components/schemas/DashboardQuery' shape: type: string enum: - chronograf-v2 note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean MarkdownViewProperties: type: object required: - type - shape - note properties: type: type: string enum: - markdown shape: type: string enum: - chronograf-v2 note: type: string CheckViewProperties: type: object required: - type - shape - checkID - queries - colors properties: adaptiveZoomHide: type: boolean type: type: string enum: - check shape: type: string enum: - chronograf-v2 checkID: type: string check: $ref: '#/components/schemas/Check' queries: type: array items: $ref: '#/components/schemas/DashboardQuery' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' legendColorizeRows: type: boolean legendHide: type: boolean legendOpacity: type: number format: float legendOrientationThreshold: type: integer GeoViewLayer: type: object oneOf: - $ref: '#/components/schemas/GeoCircleViewLayer' - $ref: '#/components/schemas/GeoHeatMapViewLayer' - $ref: '#/components/schemas/GeoPointMapViewLayer' - $ref: '#/components/schemas/GeoTrackMapViewLayer' GeoViewLayerProperties: type: object required: - type properties: type: type: string enum: - heatmap - circleMap - pointMap - trackMap GeoCircleViewLayer: allOf: - $ref: '#/components/schemas/GeoViewLayerProperties' - type: object required: - radiusField - radiusDimension - colorField - colorDimension - colors properties: radiusField: type: string description: Radius field radiusDimension: $ref: '#/components/schemas/Axis' colorField: type: string description: Circle color field colorDimension: $ref: '#/components/schemas/Axis' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' radius: description: Maximum radius size in pixels type: integer interpolateColors: description: Interpolate circle color based on displayed value type: boolean GeoPointMapViewLayer: allOf: - $ref: '#/components/schemas/GeoViewLayerProperties' - type: object required: - colorField - colorDimension - colors properties: colorField: type: string description: Marker color field colorDimension: $ref: '#/components/schemas/Axis' colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' isClustered: description: Cluster close markers together type: boolean tooltipColumns: description: An array for which columns to display in tooltip type: array items: type: string GeoTrackMapViewLayer: allOf: - $ref: '#/components/schemas/GeoViewLayerProperties' - type: object required: - trackWidth - speed - randomColors - trackPointVisualization properties: trackWidth: description: Width of the track type: integer speed: description: Speed of the track animation type: integer randomColors: description: Assign different colors to different tracks type: boolean colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' GeoHeatMapViewLayer: allOf: - $ref: '#/components/schemas/GeoViewLayerProperties' - type: object required: - intensityField - intensityDimension - radius - blur - colors properties: intensityField: type: string description: Intensity field intensityDimension: $ref: '#/components/schemas/Axis' radius: description: Radius size in pixels type: integer blur: description: Blur for heatmap points type: integer colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' GeoViewProperties: type: object required: - type - shape - queries - note - showNoteWhenEmpty - center - zoom - allowPanAndZoom - detectCoordinateFields - layers properties: type: type: string enum: - geo queries: type: array items: $ref: '#/components/schemas/DashboardQuery' shape: type: string enum: - chronograf-v2 center: description: Coordinates of the center of the map type: object required: - lat - lon properties: lat: description: Latitude of the center of the map type: number format: double lon: description: Longitude of the center of the map type: number format: double zoom: description: Zoom level used for initial display of the map type: number format: double minimum: 1 maximum: 28 allowPanAndZoom: description: 'If true, map zoom and pan controls are enabled on the dashboard view' type: boolean default: true detectCoordinateFields: description: 'If true, search results get automatically regroupped so that lon,lat and value are treated as columns' type: boolean default: true useS2CellID: description: 'If true, S2 column is used to calculate lat/lon' type: boolean s2Column: description: String to define the column type: string latLonColumns: $ref: '#/components/schemas/LatLonColumns' mapStyle: description: 'Define map type - regular, satellite etc.' type: string note: type: string showNoteWhenEmpty: description: 'If true, will display note when empty' type: boolean colors: description: Colors define color encoding of data into a visualization type: array items: $ref: '#/components/schemas/DashboardColor' layers: description: List of individual layers shown in the map type: array items: $ref: '#/components/schemas/GeoViewLayer' LatLonColumns: description: Object type to define lat/lon columns type: object required: - lat - lon properties: lat: $ref: '#/components/schemas/LatLonColumn' lon: $ref: '#/components/schemas/LatLonColumn' LatLonColumn: description: Object type for key and column definitions type: object required: - key - column properties: key: description: Key to determine whether the column is tag/field type: string column: description: Column to look up Lat/Lon type: string Axes: description: The viewport for a View's visualizations type: object required: - x - 'y' properties: x: $ref: '#/components/schemas/Axis' 'y': $ref: '#/components/schemas/Axis' StaticLegend: description: StaticLegend represents the options specific to the static legend type: object properties: colorizeRows: type: boolean heightRatio: type: number format: float show: type: boolean opacity: type: number format: float orientationThreshold: type: integer valueAxis: type: string widthRatio: type: number format: float DecimalPlaces: description: 'Indicates whether decimal places should be enforced, and how many digits it should show.' type: object properties: isEnforced: description: Indicates whether decimal point setting should be enforced type: boolean digits: description: The number of digits after decimal to display type: integer format: int32 ConstantVariableProperties: properties: type: type: string enum: - constant values: type: array items: type: string MapVariableProperties: properties: type: type: string enum: - map values: type: object additionalProperties: type: string QueryVariableProperties: properties: type: type: string enum: - query values: type: object properties: query: type: string language: type: string VariableProperties: type: object oneOf: - $ref: '#/components/schemas/QueryVariableProperties' - $ref: '#/components/schemas/ConstantVariableProperties' - $ref: '#/components/schemas/MapVariableProperties' ViewProperties: oneOf: - $ref: '#/components/schemas/LinePlusSingleStatProperties' - $ref: '#/components/schemas/XYViewProperties' - $ref: '#/components/schemas/SingleStatViewProperties' - $ref: '#/components/schemas/HistogramViewProperties' - $ref: '#/components/schemas/GaugeViewProperties' - $ref: '#/components/schemas/TableViewProperties' - $ref: '#/components/schemas/SimpleTableViewProperties' - $ref: '#/components/schemas/MarkdownViewProperties' - $ref: '#/components/schemas/CheckViewProperties' - $ref: '#/components/schemas/ScatterViewProperties' - $ref: '#/components/schemas/HeatmapViewProperties' - $ref: '#/components/schemas/MosaicViewProperties' - $ref: '#/components/schemas/BandViewProperties' - $ref: '#/components/schemas/GeoViewProperties' View: required: - name - properties properties: links: type: object readOnly: true properties: self: type: string id: readOnly: true type: string name: type: string properties: $ref: '#/components/schemas/ViewProperties' Views: type: object properties: links: type: object properties: self: type: string views: type: array items: $ref: '#/components/schemas/View' CellUpdate: type: object properties: x: type: integer format: int32 'y': type: integer format: int32 w: type: integer format: int32 h: type: integer format: int32 CreateCell: type: object properties: name: type: string x: type: integer format: int32 'y': type: integer format: int32 w: type: integer format: int32 h: type: integer format: int32 usingView: type: string description: Makes a copy of the provided view. AnalyzeQueryResponse: type: object properties: errors: type: array items: type: object properties: line: type: integer column: type: integer character: type: integer message: type: string CellWithViewProperties: type: object allOf: - $ref: '#/components/schemas/Cell' - type: object properties: name: type: string properties: $ref: '#/components/schemas/ViewProperties' Cell: type: object properties: id: type: string links: type: object properties: self: type: string view: type: string x: type: integer format: int32 'y': type: integer format: int32 w: type: integer format: int32 h: type: integer format: int32 viewID: type: string description: The reference to a view from the views API. CellsWithViewProperties: type: array items: $ref: '#/components/schemas/CellWithViewProperties' Cells: type: array items: $ref: '#/components/schemas/Cell' Secrets: additionalProperties: type: string example: apikey: abc123xyz SecretKeys: type: object properties: secrets: type: array items: type: string SecretKeysResponse: allOf: - $ref: '#/components/schemas/SecretKeys' - type: object properties: links: readOnly: true type: object properties: self: type: string org: type: string CreateDashboardRequest: properties: orgID: type: string description: The ID of the organization that owns the dashboard. name: type: string description: The user-facing name of the dashboard. description: type: string description: The user-facing description of the dashboard. required: - orgID - name DashboardWithViewProperties: type: object allOf: - $ref: '#/components/schemas/CreateDashboardRequest' - type: object properties: links: type: object example: self: /api/v2/dashboards/1 cells: /api/v2/dashboards/1/cells owners: /api/v2/dashboards/1/owners members: /api/v2/dashboards/1/members labels: /api/v2/dashboards/1/labels org: /api/v2/labels/1 properties: self: $ref: '#/components/schemas/Link' cells: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' org: $ref: '#/components/schemas/Link' id: readOnly: true type: string meta: type: object properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time cells: $ref: '#/components/schemas/CellsWithViewProperties' labels: $ref: '#/components/schemas/Labels' Dashboard: type: object allOf: - $ref: '#/components/schemas/CreateDashboardRequest' - type: object properties: links: type: object example: self: /api/v2/dashboards/1 cells: /api/v2/dashboards/1/cells owners: /api/v2/dashboards/1/owners members: /api/v2/dashboards/1/members labels: /api/v2/dashboards/1/labels org: /api/v2/labels/1 properties: self: $ref: '#/components/schemas/Link' cells: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' org: $ref: '#/components/schemas/Link' id: readOnly: true type: string meta: type: object properties: createdAt: type: string format: date-time updatedAt: type: string format: date-time cells: $ref: '#/components/schemas/Cells' labels: $ref: '#/components/schemas/Labels' Dashboards: type: object properties: links: $ref: '#/components/schemas/Links' dashboards: type: array items: $ref: '#/components/schemas/Dashboard' TelegrafRequest: type: object properties: name: type: string description: type: string metadata: type: object properties: buckets: type: array items: type: string config: type: string orgID: type: string TelegrafPluginRequest: type: object properties: name: type: string description: type: string plugins: type: array items: type: object properties: type: type: string name: type: string alias: type: string description: type: string config: type: string metadata: type: object properties: buckets: type: array items: type: string config: type: string orgID: type: string Telegraf: type: object allOf: - $ref: '#/components/schemas/TelegrafRequest' - type: object properties: id: type: string readOnly: true links: type: object readOnly: true example: self: /api/v2/telegrafs/1 lables: /api/v2/telegrafs/1/labels owners: /api/v2/telegrafs/1/owners members: /api/v2/telegrafs/1/members properties: self: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' labels: readOnly: true $ref: '#/components/schemas/Labels' Telegrafs: type: object properties: configurations: type: array items: $ref: '#/components/schemas/Telegraf' TelegrafPlugin: type: object properties: type: type: string name: type: string description: type: string config: type: string TelegrafPlugins: type: object properties: version: type: string os: type: string plugins: type: array items: $ref: '#/components/schemas/TelegrafPlugin' IsOnboarding: type: object properties: allowed: description: | If `true`, the InfluxDB instance hasn't had initial setup; `false` otherwise. type: boolean PasswordResetBody: properties: password: type: string required: - password 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 Ready: type: object properties: status: type: string enum: - ready - starting started: type: string format: date-time example: '2019-03-13T10:09:33.891196-04:00' up: type: string example: 14m45.911966424s uptime: description: 'Time since `started`, in float seconds.' allOf: - $ref: '#/components/schemas/HealthCheckMeasure' checks: description: | Ready gates that haven't passed. Omitted when `status` is `ready`. type: array items: $ref: '#/components/schemas/HealthCheck' HealthCheck: description: | A health check. A check can also report measure groups, such as `progress` or `failures`. Each key other than `name`, `status`, `message`, and `checks` whose value is an object is a measure group. type: object required: - name - status properties: name: type: string message: type: string description: | Status detail. For a failing check, may contain the raw error text. checks: type: array items: $ref: '#/components/schemas/HealthCheck' status: type: string enum: - pass - fail version: type: string description: Build version. Returned only at the top level. commit: type: string description: Build commit. Returned only at the top level. additionalProperties: $ref: '#/components/schemas/HealthCheckMeasure' HealthCheckMeasure: description: | A measure group: one or more numeric values that share a unit. Durations are float seconds with `unit: seconds`. type: object required: - unit properties: unit: type: string example: shards additionalProperties: type: number example: completed: 94 total: 200 unit: shards Labels: type: array items: $ref: '#/components/schemas/Label' 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 LabelCreateRequest: type: object required: - orgID - name properties: orgID: 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 LabelUpdate: type: object properties: 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 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 LabelsResponse: type: object properties: labels: $ref: '#/components/schemas/Labels' links: $ref: '#/components/schemas/Links' LabelResponse: type: object properties: label: $ref: '#/components/schemas/Label' links: $ref: '#/components/schemas/Links' ASTResponse: description: Contains the AST for the supplied Flux query type: object properties: ast: $ref: '#/components/schemas/Package' WritePrecision: type: string enum: - ms - s - us - ns FluxResponse: description: Rendered flux that backs the check or notification. properties: flux: type: string CheckPatch: type: object properties: name: type: string description: type: string status: type: string enum: - active - inactive CheckDiscriminator: oneOf: - $ref: '#/components/schemas/DeadmanCheck' - $ref: '#/components/schemas/ThresholdCheck' - $ref: '#/components/schemas/CustomCheck' discriminator: propertyName: type mapping: deadman: '#/components/schemas/DeadmanCheck' threshold: '#/components/schemas/ThresholdCheck' custom: '#/components/schemas/CustomCheck' Check: allOf: - $ref: '#/components/schemas/CheckDiscriminator' PostCheck: allOf: - $ref: '#/components/schemas/CheckDiscriminator' Checks: properties: checks: type: array items: $ref: '#/components/schemas/Check' links: $ref: '#/components/schemas/Links' CheckBase: properties: id: readOnly: true type: string name: type: string orgID: description: The ID of the organization that owns this check. type: string taskID: description: The ID of the task associated with this check. type: string ownerID: description: The ID of creator used to create this check. type: string readOnly: true createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true query: $ref: '#/components/schemas/DashboardQuery' status: $ref: '#/components/schemas/TaskStatusType' description: description: An optional description of the check. type: string latestCompleted: type: string description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' format: date-time readOnly: true lastRunStatus: readOnly: true type: string enum: - failed - success - canceled lastRunError: readOnly: true type: string labels: $ref: '#/components/schemas/Labels' links: type: object readOnly: true example: self: /api/v2/checks/1 labels: /api/v2/checks/1/labels members: /api/v2/checks/1/members owners: /api/v2/checks/1/owners query: /api/v2/checks/1/query properties: self: description: The URL for this check. $ref: '#/components/schemas/Link' labels: description: The URL to retrieve labels for this check. $ref: '#/components/schemas/Link' members: description: The URL to retrieve members for this check. $ref: '#/components/schemas/Link' owners: description: The URL to retrieve owners for this check. $ref: '#/components/schemas/Link' query: description: The URL to retrieve the Flux script for this check. $ref: '#/components/schemas/Link' required: - name - orgID - query ThresholdCheck: allOf: - $ref: '#/components/schemas/CheckBase' - type: object required: - type properties: type: type: string enum: - threshold thresholds: type: array items: $ref: '#/components/schemas/Threshold' every: description: Check repetition interval. type: string offset: description: 'Duration to delay after the schedule, before executing check.' type: string tags: description: List of tags to write to each status. type: array items: type: object properties: key: type: string value: type: string statusMessageTemplate: description: The template used to generate and write a status message. type: string Threshold: oneOf: - $ref: '#/components/schemas/GreaterThreshold' - $ref: '#/components/schemas/LesserThreshold' - $ref: '#/components/schemas/RangeThreshold' discriminator: propertyName: type mapping: greater: '#/components/schemas/GreaterThreshold' lesser: '#/components/schemas/LesserThreshold' range: '#/components/schemas/RangeThreshold' DeadmanCheck: allOf: - $ref: '#/components/schemas/CheckBase' - type: object required: - type properties: type: type: string enum: - deadman timeSince: description: String duration before deadman triggers. type: string staleTime: description: String duration for time that a series is considered stale and should not trigger deadman. type: string reportZero: description: 'If only zero values reported since time, trigger an alert' type: boolean level: $ref: '#/components/schemas/CheckStatusLevel' every: description: Check repetition interval. type: string offset: description: 'Duration to delay after the schedule, before executing check.' type: string tags: description: List of tags to write to each status. type: array items: type: object properties: key: type: string value: type: string statusMessageTemplate: description: The template used to generate and write a status message. type: string CustomCheck: allOf: - $ref: '#/components/schemas/CheckBase' - type: object properties: type: type: string enum: - custom required: - type ThresholdBase: properties: level: $ref: '#/components/schemas/CheckStatusLevel' allValues: description: 'If true, only alert if all values meet threshold.' type: boolean GreaterThreshold: allOf: - $ref: '#/components/schemas/ThresholdBase' - type: object required: - type - value properties: type: type: string enum: - greater value: type: number format: float LesserThreshold: allOf: - $ref: '#/components/schemas/ThresholdBase' - type: object required: - type - value properties: type: type: string enum: - lesser value: type: number format: float RangeThreshold: allOf: - $ref: '#/components/schemas/ThresholdBase' - type: object required: - type - min - max - within properties: type: type: string enum: - range min: type: number format: float max: type: number format: float within: type: boolean CheckStatusLevel: description: The state to record if check matches a criteria. type: string enum: - UNKNOWN - OK - INFO - CRIT - WARN RuleStatusLevel: description: The state to record if check matches a criteria. type: string enum: - UNKNOWN - OK - INFO - CRIT - WARN - ANY NotificationRuleUpdate: type: object properties: name: type: string description: type: string status: type: string enum: - active - inactive NotificationRuleDiscriminator: oneOf: - $ref: '#/components/schemas/SlackNotificationRule' - $ref: '#/components/schemas/SMTPNotificationRule' - $ref: '#/components/schemas/PagerDutyNotificationRule' - $ref: '#/components/schemas/HTTPNotificationRule' - $ref: '#/components/schemas/TelegramNotificationRule' discriminator: propertyName: type mapping: slack: '#/components/schemas/SlackNotificationRule' smtp: '#/components/schemas/SMTPNotificationRule' pagerduty: '#/components/schemas/PagerDutyNotificationRule' http: '#/components/schemas/HTTPNotificationRule' telegram: '#/components/schemas/TelegramNotificationRule' NotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleDiscriminator' PostNotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleDiscriminator' NotificationRules: properties: notificationRules: type: array items: $ref: '#/components/schemas/NotificationRule' links: $ref: '#/components/schemas/Links' NotificationRuleBase: type: object required: - orgID - status - name - statusRules - endpointID properties: latestCompleted: description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true lastRunStatus: readOnly: true type: string enum: - failed - success - canceled lastRunError: readOnly: true type: string id: readOnly: true type: string endpointID: type: string orgID: description: The ID of the organization that owns this notification rule. type: string taskID: description: The ID of the task associated with this notification rule. type: string ownerID: description: The ID of creator used to create this notification rule. type: string readOnly: true createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true status: $ref: '#/components/schemas/TaskStatusType' name: description: Human-readable name describing the notification rule. type: string sleepUntil: type: string every: description: The notification repetition interval. type: string offset: description: 'Duration to delay after the schedule, before executing check.' type: string runbookLink: type: string limitEvery: description: 'Don''t notify me more than times every seconds. If set, limit cannot be empty.' type: integer limit: description: 'Don''t notify me more than times every seconds. If set, limitEvery cannot be empty.' type: integer tagRules: description: List of tag rules the notification rule attempts to match. type: array items: $ref: '#/components/schemas/TagRule' description: description: An optional description of the notification rule. type: string statusRules: description: List of status rules the notification rule attempts to match. type: array minItems: 1 items: $ref: '#/components/schemas/StatusRule' labels: $ref: '#/components/schemas/Labels' links: type: object readOnly: true example: self: /api/v2/notificationRules/1 labels: /api/v2/notificationRules/1/labels members: /api/v2/notificationRules/1/members owners: /api/v2/notificationRules/1/owners query: /api/v2/notificationRules/1/query properties: self: description: The URL for this endpoint. $ref: '#/components/schemas/Link' labels: description: The URL to retrieve labels for this notification rule. $ref: '#/components/schemas/Link' members: description: The URL to retrieve members for this notification rule. $ref: '#/components/schemas/Link' owners: description: The URL to retrieve owners for this notification rule. $ref: '#/components/schemas/Link' query: description: The URL to retrieve the Flux script for this notification rule. $ref: '#/components/schemas/Link' TagRule: type: object properties: key: type: string value: type: string operator: type: string enum: - equal - notequal - equalregex - notequalregex StatusRule: type: object properties: currentLevel: $ref: '#/components/schemas/RuleStatusLevel' previousLevel: $ref: '#/components/schemas/RuleStatusLevel' count: type: integer period: type: string HTTPNotificationRuleBase: type: object required: - type properties: type: type: string enum: - http url: type: string HTTPNotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleBase' - $ref: '#/components/schemas/HTTPNotificationRuleBase' SlackNotificationRuleBase: type: object required: - type - messageTemplate properties: type: type: string enum: - slack channel: type: string messageTemplate: type: string SlackNotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleBase' - $ref: '#/components/schemas/SlackNotificationRuleBase' SMTPNotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleBase' - $ref: '#/components/schemas/SMTPNotificationRuleBase' SMTPNotificationRuleBase: type: object required: - type - subjectTemplate - to properties: type: type: string enum: - smtp subjectTemplate: type: string bodyTemplate: type: string to: type: string PagerDutyNotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleBase' - $ref: '#/components/schemas/PagerDutyNotificationRuleBase' PagerDutyNotificationRuleBase: type: object required: - type - messageTemplate properties: type: type: string enum: - pagerduty messageTemplate: type: string TelegramNotificationRule: allOf: - $ref: '#/components/schemas/NotificationRuleBase' - $ref: '#/components/schemas/TelegramNotificationRuleBase' TelegramNotificationRuleBase: type: object required: - type - messageTemplate - channel properties: type: description: The discriminator between other types of notification rules is "telegram". type: string enum: - telegram messageTemplate: description: The message template as a flux interpolated string. type: string parseMode: description: 'Parse mode of the message text per https://core.telegram.org/bots/api#formatting-options. Defaults to "MarkdownV2".' type: string enum: - MarkdownV2 - HTML - Markdown disableWebPagePreview: description: Disables preview of web links in the sent messages when "true". Defaults to "false". type: boolean NotificationEndpointUpdate: type: object properties: name: type: string description: type: string status: type: string enum: - active - inactive NotificationEndpointDiscriminator: oneOf: - $ref: '#/components/schemas/SlackNotificationEndpoint' - $ref: '#/components/schemas/PagerDutyNotificationEndpoint' - $ref: '#/components/schemas/HTTPNotificationEndpoint' - $ref: '#/components/schemas/TelegramNotificationEndpoint' discriminator: propertyName: type mapping: slack: '#/components/schemas/SlackNotificationEndpoint' pagerduty: '#/components/schemas/PagerDutyNotificationEndpoint' http: '#/components/schemas/HTTPNotificationEndpoint' telegram: '#/components/schemas/TelegramNotificationEndpoint' NotificationEndpoint: allOf: - $ref: '#/components/schemas/NotificationEndpointDiscriminator' PostNotificationEndpoint: allOf: - $ref: '#/components/schemas/NotificationEndpointDiscriminator' NotificationEndpoints: properties: notificationEndpoints: type: array items: $ref: '#/components/schemas/NotificationEndpoint' links: $ref: '#/components/schemas/Links' NotificationEndpointBase: type: object required: - type - name properties: id: type: string orgID: type: string userID: type: string createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true description: description: An optional description of the notification endpoint. type: string name: type: string status: description: The status of the endpoint. default: active type: string enum: - active - inactive labels: $ref: '#/components/schemas/Labels' links: type: object readOnly: true example: self: /api/v2/notificationEndpoints/1 labels: /api/v2/notificationEndpoints/1/labels members: /api/v2/notificationEndpoints/1/members owners: /api/v2/notificationEndpoints/1/owners properties: self: description: The URL for this endpoint. $ref: '#/components/schemas/Link' labels: description: The URL to retrieve labels for this endpoint. $ref: '#/components/schemas/Link' members: description: The URL to retrieve members for this endpoint. $ref: '#/components/schemas/Link' owners: description: The URL to retrieve owners for this endpoint. $ref: '#/components/schemas/Link' type: $ref: '#/components/schemas/NotificationEndpointType' SlackNotificationEndpoint: type: object allOf: - $ref: '#/components/schemas/NotificationEndpointBase' - type: object properties: url: description: Specifies the URL of the Slack endpoint. Specify either `URL` or `Token`. type: string token: description: Specifies the API token string. Specify either `URL` or `Token`. type: string PagerDutyNotificationEndpoint: type: object allOf: - $ref: '#/components/schemas/NotificationEndpointBase' - type: object required: - routingKey properties: clientURL: type: string routingKey: type: string HTTPNotificationEndpoint: type: object allOf: - $ref: '#/components/schemas/NotificationEndpointBase' - type: object required: - url - authMethod - method properties: url: type: string username: type: string password: type: string token: type: string method: type: string enum: - POST - GET - PUT authMethod: type: string enum: - none - basic - bearer contentTemplate: type: string headers: type: object description: Customized headers. additionalProperties: type: string TelegramNotificationEndpoint: type: object allOf: - $ref: '#/components/schemas/NotificationEndpointBase' - type: object required: - token - channel properties: token: description: 'Specifies the Telegram bot token. See https://core.telegram.org/bots#creating-a-new-bot .' type: string channel: description: 'The ID of the telegram channel; a chat_id in https://core.telegram.org/bots/api#sendmessage .' type: string NotificationEndpointType: type: string enum: - slack - pagerduty - http - telegram DBRP: type: object properties: id: type: string description: | The resource ID that InfluxDB uses to uniquely identify the database retention policy (DBRP) mapping. readOnly: true orgID: type: string description: | An organization ID. Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the mapping. bucketID: type: string description: | A bucket ID. Identifies the bucket used as the target for the translation. database: type: string description: | A database name. Identifies the InfluxDB v1 database. retention_policy: type: string description: | A [retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. default: type: boolean description: | If set to `true`, this DBRP mapping is the default retention policy for the database (specified by the `database` property's value). virtual: type: boolean description: 'Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS.' links: $ref: '#/components/schemas/Links' required: - id - orgID - bucketID - database - retention_policy - default DBRPs: properties: content: type: array items: $ref: '#/components/schemas/DBRP' DBRPUpdate: properties: retention_policy: type: string description: | A [retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. default: type: boolean description: | Set to `true` to use this DBRP mapping as the default retention policy for the database (specified by the `database` property's value). To remove the default mapping, set to `false`. DBRPCreate: type: object properties: org: type: string description: | An organization name. Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the mapping. orgID: type: string description: | An organization ID. Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the mapping. bucketID: type: string description: | A bucket ID. Identifies the bucket used as the target for the translation. database: type: string description: | A database name. Identifies the InfluxDB v1 database. retention_policy: type: string description: | A [retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. Identifies the InfluxDB v1 retention policy mapping. default: type: boolean description: | Set to `true` to use this DBRP mapping as the default retention policy for the database (specified by the `database` property's value). required: - bucketID - database - retention_policy DBRPGet: type: object properties: content: $ref: '#/components/schemas/DBRP' required: true SchemaType: type: string enum: - implicit - explicit ColorMapping: type: object description: A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. additionalProperties: type: string example: series_id_1: '#edf529' series_id_2: '#edf529' measurement_birdmigration_europe: '#663cd0' configcat_deployments-autopromotionblocker: '#663cd0' Permission: required: - action - resource properties: action: type: string enum: - read - write resource: $ref: '#/components/schemas/Resource' User: properties: id: readOnly: true type: string name: type: string status: description: If inactive the user is inactive. default: active type: string enum: - active - inactive role: type: string enum: - owner - member org_id: type: string required: - name Users: type: object properties: links: type: object properties: self: type: string format: uri users: type: array items: $ref: '#/components/schemas/UserResponse' OnboardingRequest: type: object properties: username: type: string password: type: string org: type: string bucket: type: string retentionPeriodHrs: type: integer deprecated: true retentionPeriodSeconds: type: integer limit: $ref: '#/components/schemas/Limit' required: - username - org - bucket OnboardingResponse: type: object properties: user: $ref: '#/components/schemas/UserResponse' org: $ref: '#/components/schemas/Organization' bucket: $ref: '#/components/schemas/Bucket' auth: $ref: '#/components/schemas/Authorization' Limit: type: object description: These are org limits similar to those configured in/by quartz. properties: orgID: type: string rate: type: object properties: queryTime: type: integer description: Query Time in nanoseconds readKBs: type: integer description: Query limit in kb/sec. 0 is unlimited. concurrentReadRequests: type: integer description: Allowed concurrent queries. 0 is unlimited. writeKBs: type: integer description: Write limit in kb/sec. 0 is unlimited. concurrentWriteRequests: type: integer description: Allowed concurrent writes. 0 is unlimited. cardinality: type: integer description: Allowed organization total cardinality. 0 is unlimited. concurrentDeleteRequests: type: integer description: Allowed organization concurrent outstanding delete requests. deleteRequestsPerSecond: type: integer description: Allowed organization delete request rate. required: - readKBs - queryTime - concurrentReadRequests - writeKBs - concurrentWriteRequests - cardinality bucket: type: object properties: maxBuckets: type: integer maxRetentionDuration: type: integer description: Max bucket retention duration in nanoseconds. 0 is unlimited. required: - maxBuckets - maxRetentionDuration task: type: object properties: maxTasks: type: integer required: - maxTasks dashboard: type: object properties: maxDashboards: type: integer required: - maxDashboards check: type: object properties: maxChecks: type: integer required: - maxChecks notificationRule: type: object properties: maxNotifications: type: integer blockedNotificationRules: type: string description: comma separated list of notification rules example: 'http,pagerduty' required: - maxNotifications - blockNotificationRules notificationEndpoint: type: object properties: blockedNotificationEndpoints: type: string description: comma separated list of notification endpoints example: 'http,pagerduty' required: - blockNotificationEndpoints stack: type: object properties: enabled: type: boolean required: - enabled timeout: type: object properties: queryUnconditionalTimeoutSeconds: type: integer queryidleWriteTimeoutSeconds: type: integer required: - queryUnconditionalTimeoutSeconds - queryidleWriteTimeoutSeconds ioxQuery: type: object properties: partitions: type: integer parquetFiles: type: integer required: - partitions - parquetFiles features: type: object properties: allowDelete: type: boolean description: allow delete predicate endpoint required: - rate - bucket - task - dashboard - check - notificationRule - notificationEndpoint Variable: type: object required: - name - orgID - arguments properties: links: type: object readOnly: true properties: self: type: string format: uri org: type: string format: uri labels: type: string format: uri id: readOnly: true type: string orgID: type: string name: type: string description: type: string selected: type: array items: type: string sort_order: type: integer labels: $ref: '#/components/schemas/Labels' arguments: $ref: '#/components/schemas/VariableProperties' createdAt: type: string format: date-time updatedAt: type: string format: date-time Variables: type: object example: variables: - id: '1221432' name: ':ok:' selected: - hello arguments: type: constant values: - howdy - hello - hi - yo - oy - id: '1221432' name: ':ok:' selected: - c arguments: type: map values: a: fdjaklfdjkldsfjlkjdsa b: dfaksjfkljekfajekdljfas c: fdjksajfdkfeawfeea - id: '1221432' name: ':ok:' selected: - host arguments: type: query query: 'from(bucket: "foo") |> showMeasurements()' language: flux properties: variables: type: array items: $ref: '#/components/schemas/Variable' ColumnDataType: type: string enum: - integer - float - boolean - string - unsigned ColumnSemanticType: type: string nullable: false enum: - timestamp - tag - field MeasurementSchema: description: Definition of a measurement schema. type: object example: id: 1a3c5e7f9b0a8642 orgID: 0a3c5e7f9b0a0001 bucketID: ba3c5e7f9b0a0010 name: cpu columns: - name: time type: integer format: unix timestamp - name: host type: tag - name: region type: tag - name: usage_user type: field dataType: float - name: usage_user type: field dataType: float createdAt: '2021-01-21T00:48:40.993Z' updatedAt: '2021-01-21T00:48:40.993Z' required: - id - name - columns - createdAt - updatedAt properties: id: type: string readOnly: true orgID: type: string description: The ID of the organization. bucketID: type: string description: The ID of the bucket that the measurement schema is associated with. name: type: string nullable: false columns: description: Ordered collection of column definitions. type: array items: $ref: '#/components/schemas/MeasurementSchemaColumn' createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true MeasurementSchemaColumn: description: Definition of a measurement schema column. example: name: time type: integer format: unix timestamp type: object required: - name - type properties: name: type: string type: $ref: '#/components/schemas/ColumnSemanticType' dataType: $ref: '#/components/schemas/ColumnDataType' MeasurementSchemaCreateRequest: description: Create a new measurement schema. type: object example: name: cpu columns: - name: time type: integer format: unix timestamp - name: host type: tag - name: region type: tag - name: usage_user type: field dataType: float - name: usage_user type: field dataType: float required: - name - columns properties: name: description: | The [measurement](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#measurement) name. type: string columns: description: Ordered collection of column definitions. type: array items: $ref: '#/components/schemas/MeasurementSchemaColumn' MeasurementSchemaList: description: A list of measurement schemas returning summary information example: measurementSchemas: - id: 1a3c5e7f9b0a8642 orgID: 0a3c5e7f9b0a0001 bucketID: ba3c5e7f9b0a0010 name: cpu createdAt: '2021-01-21T00:48:40.993Z' updatedAt: '2021-01-21T00:48:40.993Z' - id: 1a3c5e7f9b0a8643 orgID: 0a3c5e7f9b0a0001 bucketID: ba3c5e7f9b0a0010 name: memory createdAt: '2021-01-21T00:48:40.993Z' updatedAt: '2021-01-21T00:48:40.993Z' - id: 1a3c5e7f9b0a8644 orgID: 0a3c5e7f9b0a0001 bucketID: ba3c5e7f9b0a0010 name: disk createdAt: '2021-01-21T00:48:40.993Z' updatedAt: '2021-01-21T00:48:40.993Z' type: object required: - measurementSchemas properties: measurementSchemas: type: array items: $ref: '#/components/schemas/MeasurementSchema' MeasurementSchemaUpdateRequest: description: Update an existing measurement schema type: object example: columns: - name: time type: integer format: unix timestamp - name: host type: tag - name: region type: tag - name: usage_user type: field dataType: float - name: usage_user type: field dataType: float required: - columns properties: columns: description: An ordered collection of column definitions type: array items: $ref: '#/components/schemas/MeasurementSchemaColumn' Tasks: type: object properties: links: readOnly: true $ref: '#/components/schemas/Links' tasks: type: array items: $ref: '#/components/schemas/Task' Task: type: object properties: id: readOnly: true type: string orgID: description: | An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. Specifies the organization that owns the task. type: string org: description: | An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. Specifies the organization that owns the task. type: string name: description: The name of the task. type: string ownerID: description: | A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. Specifies the owner of the task. To find a user ID, you can use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string description: description: A description of the task. type: string status: $ref: '#/components/schemas/TaskStatusType' labels: $ref: '#/components/schemas/Labels' authorizationID: description: | An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to list authorizations. type: string flux: description: | The Flux script that the task executes. #### Limitations - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. type: string format: flux every: description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string format: duration cron: description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.' type: string offset: description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' type: string format: duration latestCompleted: description: 'A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string format: date-time readOnly: true lastRunStatus: readOnly: true type: string enum: - failed - success - canceled lastRunError: readOnly: true type: string createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true links: type: object readOnly: true example: self: /api/v2/tasks/1 owners: /api/v2/tasks/1/owners members: /api/v2/tasks/1/members labels: /api/v2/tasks/1/labels runs: /api/v2/tasks/1/runs logs: /api/v2/tasks/1/logs properties: self: $ref: '#/components/schemas/Link' owners: $ref: '#/components/schemas/Link' members: $ref: '#/components/schemas/Link' runs: $ref: '#/components/schemas/Link' logs: $ref: '#/components/schemas/Link' labels: $ref: '#/components/schemas/Link' scriptID: description: | A script ID. Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations - If you use the `scriptID` property, you can't use the `flux` property. #### Related guides - [Create a task that references a script](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) type: string scriptParameters: description: | Key-value pairs for `params` in the script. Defines the invocation parameter values passed to the script specified by `scriptID`. When running the task, InfluxDB executes the script with the parameters you provide. #### Limitations - To use `scriptParameters`, you must provide a `scriptID`. - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. type: object required: - id - name - orgID TaskCreateRequest: type: object properties: orgID: description: The ID of the organization that owns the task. type: string org: description: The name of the organization that owns the task. type: string status: $ref: '#/components/schemas/TaskStatusType' flux: description: | The Flux script that the task runs. #### Limitations - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. type: string description: description: The description of the task. type: string scriptID: description: | The ID of the script that the task runs. #### Limitations - If you use the `scriptID` property, you can't use the `flux` property. type: string scriptParameters: description: | The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. #### Limitations - `scriptParameters` requires `scriptID`. - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. type: object name: description: The name of the task type: string every: description: | The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. `every` also determines when the task first runs, depending on the specified time. type: string cron: description: 'A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time.' type: string offset: description: 'A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.' type: string format: duration TaskUpdateRequest: type: object properties: status: $ref: '#/components/schemas/TaskStatusType' flux: description: Update the Flux script that the task runs. type: string name: description: Update the 'name' option in the flux script. type: string every: description: Update the 'every' option in the flux script. type: string cron: description: Update the 'cron' option in the flux script. type: string offset: description: Update the 'offset' option in the flux script. type: string description: description: Update the description of the task. type: string scriptID: description: Update the 'scriptID' of the task. type: string scriptParameters: description: Update the 'scriptParameters' of the task. type: object responses: AuthorizationError: description: | 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. 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 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' GeneralServerError: description: Non 2XX error response from server. content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: | Internal server error. The server encountered an unexpected situation. content: application/json: schema: $ref: '#/components/schemas/Error' ResourceNotFoundError: description: | 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. 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 examples: AuthorizationPostRequest: summary: An authorization for a resource type description: Creates an authorization. value: orgID: INFLUX_ORG_ID description: iot_users read buckets permissions: - action: read resource: type: buckets AuthorizationWithResourcePostRequest: summary: An authorization for a resource description: Creates an authorization for access to a specific resource. value: orgID: INFLUX_ORG_ID description: iot_users read buckets permissions: - action: read resource: type: buckets id: INFLUX_BUCKET_ID AuthorizationWithUserPostRequest: summary: An authorization scoped to a user description: Creates an authorization scoped to a specific user. value: orgID: INFLUX_ORG_ID userID: INFLUX_USER_ID description: iot_user write to bucket permissions: - action: write resource: type: buckets id: INFLUX_BUCKET_ID TaskWithFluxRequest: summary: A task with Flux description: Sets the `flux` property with Flux task options and a query. value: flux: "option task = {name: \"CPU Total 1 Hour New\", every: 1h}from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")" status: active description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. TaskWithScriptRequest: summary: A task with an invokable script description: | Sets properties for a task that runs an _invokable script_. value: name: CPU Total 1 Hour New every: 1h scriptID: SCRIPT_ID scriptParameters: rangeStart: '-1h' bucket: telegraf filterField: cpu-total status: active description: This task runs an invokable script every hour with the defined parameters. securitySchemes: TokenAuthentication: type: apiKey name: Authorization in: header description: | Use the [Token authentication](#section/Authentication/TokenAuthentication) scheme to authenticate to the InfluxDB API. In your API requests, send an `Authorization` header. For the header value, provide the word `Token` followed by a space and an InfluxDB API token. The word `Token` is case-sensitive. ### Syntax `Authorization: Token INFLUX_API_TOKEN` ### Example #### Use Token authentication with cURL The following example shows how to use cURL to send an API request that uses Token authentication: ```sh curl --request GET "INFLUX_URL/api/v2/buckets" \ --header "Authorization: Token INFLUX_API_TOKEN" ``` Replace the following: - *`INFLUX_URL`*: your InfluxDB Cloud URL - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) ### Related endpoints - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) ### Related guides - [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication) - [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/) BasicAuthentication: type: http scheme: basic description: | ### Basic authentication scheme Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it: ### Syntax `Authorization: Basic BASE64_ENCODED_CREDENTIALS` To construct the `BASE64_ENCODED_CREDENTIALS`, combine the username and the password with a colon (`USERNAME:PASSWORD`), and then encode the resulting string in [base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64). Many HTTP clients encode the credentials for you before sending the request. _**Warning**: Base64-encoding can easily be reversed to obtain the original username and password. It is used to keep the data intact and does not provide security. You should always use HTTPS when authenticating or sending a request with sensitive information._ ### Examples In the examples, replace the following: - **`EMAIL_ADDRESS`**: InfluxDB Cloud username (the email address the user signed up with) - **`PASSWORD`**: InfluxDB Cloud [API token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token) - **`INFLUX_URL`**: your InfluxDB Cloud URL #### Encode credentials with cURL The following example shows how to use cURL to send an API request that uses Basic authentication. With the `--user` option, cURL encodes the credentials and passes them in the `Authorization: Basic` header. ```sh curl --get "INFLUX_URL/api/v2/signin" --user "EMAIL_ADDRESS":"PASSWORD" ``` #### Encode credentials with Flux The Flux [`http.basicAuth()` function](https://docs.influxdata.com/flux/v0.x/stdlib/http/basicauth/) returns a Base64-encoded basic authentication header using a specified username and password combination. #### Encode credentials with JavaScript The following example shows how to use the JavaScript `btoa()` function to create a Base64-encoded string: ```js btoa('EMAIL_ADDRESS:PASSWORD') ``` The output is the following: ```js 'VVNFUk5BTUU6UEFTU1dPUkQ=' ``` Once you have the Base64-encoded credentials, you can pass them in the `Authorization` header--for example: ```sh curl --get "INFLUX_URL/api/v2/signin" --header "Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ=" ``` To learn more about HTTP authentication, see [Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._ security: - TokenAuthentication: []