diff --git a/contracts/cloud-diff.yml b/contracts/cloud-diff.yml index 7dde1e258..010a2305a 100644 --- a/contracts/cloud-diff.yml +++ b/contracts/cloud-diff.yml @@ -426,6 +426,342 @@ paths: default: description: Unexpected error $ref: '#/paths/~1tasks/get/responses/default' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + 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 for the organization. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### Required permissions + + - `read-authorizations` + + #### Related guides + + - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) + parameters: + - $ref: '#/paths/~1users/get/parameters/0' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified + [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified + [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: | + An organization ID. + Only returns authorizations that belong to the specified + [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified + [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value. + Returns the authorization for the specified token. + responses: + '200': + description: Success. The response body contains a list of authorizations. + content: + application/json: + schema: + type: object + properties: + links: + readOnly: true + $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' + authorizations: + type: array + items: + $ref: '#/components/schemas/OnboardingResponse/properties/auth' + '400': + description: Invalid request + $ref: '#/paths/~1tasks/get/responses/default' + '401': + $ref: '#/paths/~1tasks/get/responses/401' + '500': + $ref: '#/paths/~1users/get/responses/500' + default: + description: Unexpected error + $ref: '#/paths/~1tasks/get/responses/default' + post: + operationId: PostAuthorizations + tags: + - Authorizations + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token]({{% INFLUXDB_DOCS_URL %}}/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. + + #### Limitations + + To follow best practices for secure API token generation and retrieval, + InfluxDB Cloud enforces access restrictions on API tokens. + + - InfluxDB only allows access to the API token value immediately after the authorization is created. + - You can't update an authorization's permissions. + - A token stops working when the user who created the authorization 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. + + #### Related guides + + - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) + parameters: + - $ref: '#/paths/~1users/get/parameters/0' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + required: + - orgID + - permissions + allOf: + - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' + - 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: + required: + - action + - resource + properties: + action: + type: string + enum: + - read + - write + 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. + 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/OnboardingResponse/properties/auth' + '400': + description: Invalid request + $ref: '#/paths/~1tasks/get/responses/default' + '401': + $ref: '#/paths/~1tasks/get/responses/401' + '500': + $ref: '#/paths/~1users/get/responses/500' + default: + description: Unexpected error + $ref: '#/paths/~1tasks/get/responses/default' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + summary: Retrieve an authorization + parameters: + - $ref: '#/paths/~1users/get/parameters/0' + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to get. + responses: + '200': + description: Authorization details + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingResponse/properties/auth' + default: + description: Unexpected error + $ref: '#/paths/~1tasks/get/responses/default' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + summary: Update authorization status + description: Update an authorization's status to `active` or `inactive`. + requestBody: + description: The updated Authorization object. + required: true + content: + application/json: + schema: + properties: + status: + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. + parameters: + - $ref: '#/paths/~1users/get/parameters/0' + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to update. + responses: + '200': + description: The updated authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingResponse/properties/auth' + default: + description: Unexpected error + $ref: '#/paths/~1tasks/get/responses/default' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + summary: Delete an authorization + parameters: + - $ref: '#/paths/~1users/get/parameters/0' + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to delete. + responses: + '204': + description: Authorization deleted + default: + description: Unexpected error + $ref: '#/paths/~1tasks/get/responses/default' /variables: get: operationId: GetVariables @@ -1113,20 +1449,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' cells: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' org: - type: string - format: uri - readOnly: true - description: URI of resource. + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -1169,7 +1502,7 @@ paths: type: string description: The reference to a view from the views API. labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' - type: object allOf: - $ref: '#/paths/~1dashboards/post/requestBody/content/application~1json/schema' @@ -1186,17 +1519,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' cells: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' org: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -1934,7 +2267,7 @@ paths: readOnly: true type: string labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' links: type: object readOnly: true @@ -1947,19 +2280,19 @@ paths: properties: self: description: The URL for this check. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: description: The URL to retrieve labels for this check. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: description: The URL to retrieve members for this check. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: description: The URL to retrieve owners for this check. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' query: description: The URL to retrieve the Flux script for this check. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' required: - name - orgID @@ -2778,7 +3111,7 @@ paths: items: $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/1/allOf/1/properties/cells/items/allOf/1/properties/properties/oneOf/0/properties/colors/items' labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' default: description: Unexpected error content: @@ -2880,11 +3213,11 @@ paths: URI pointers for additional paged results. properties: next: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' self: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' prev: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' required: - self dashboards: @@ -2903,23 +3236,19 @@ paths: tags: - Data I/O endpoints - Tasks - summary: List tasks + summary: List all tasks description: | - Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/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`. - - #### Related guide - - - [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/) parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: query name: name description: | - A task name. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) with the specified name. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. schema: type: string @@ -2928,29 +3257,29 @@ paths: schema: type: string description: | - A task ID. - Only returns [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Only returns tasks created after the specified task. - in: query name: user schema: type: string description: | - A user ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. - in: query name: org schema: type: string description: | - An organization name. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. - in: query name: orgID schema: type: string description: | - An organization ID. - Only returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. - in: query name: status schema: @@ -2959,8 +3288,8 @@ paths: - active - inactive description: | - A task status. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). - in: query name: limit schema: @@ -2993,11 +3322,8 @@ paths: - in: query name: sortBy description: | - The sort field. - Specifies the task property used to sort records in the list. - Default is `name`. - - The parameter has one supported value: `name`. + The sort field. Only `name` is supported. + Specifies the field used to sort records in the list. required: false schema: type: string @@ -3006,13 +3332,11 @@ paths: - in: query name: type description: | - A task type. - Specifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response. + A [task]({{% INFLUXDB_DOCS_URL %}}/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, set the `type` parameter to `basic` (`type=basic`) - to omit some task properties (`flux`, `createdAt`, `updatedAt`). + To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). required: false schema: default: '' @@ -3023,8 +3347,8 @@ paths: - in: query name: scriptID description: | - A script ID. - Only returns tasks that use the specified [invokable script](#tag/Invokable-Scripts). + A [script](#tag/Invokable-Scripts) ID. + Only returns tasks that use the specified invokable script. schema: type: string responses: @@ -3153,7 +3477,52 @@ paths: description: | Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. - Use this endpoint to create a scheduled task that runs a script. + 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 @@ -3164,41 +3533,15 @@ paths: parameters: - $ref: '#/paths/~1users/get/parameters/0' requestBody: - description: | - In the request body, provide the task. - - Set one of the following properties to provide the script that the task runs: - - `flux` - - `scriptID` - - If you set the `scriptID` property, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, you must provide the `task` configuration option - in the Flux script. - - See [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't use `flux` and `scriptID` in the same task. + description: The task to create required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' responses: '201': - description: Success. The response body contains a `tasks` list with the task. + description: Success. The response body contains a `tasks` list with the new task. content: application/json: schema: @@ -3210,10 +3553,8 @@ paths: #### InfluxDB Cloud - - Returns this error if the task doesn't contain the `flux` property - or the `scriptID` property. - - Returns this error if the task contains `flux` _and_ `scriptID` - properties. + - 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: @@ -3239,6 +3580,44 @@ paths: application/json: schema: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + 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 @@ -3247,7 +3626,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: path @@ -3256,8 +3635,8 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Specifies the task to retrieve. responses: '200': description: Success. The response body contains the task. @@ -3325,52 +3704,67 @@ paths: - Tasks summary: Update a task description: | - Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), + Updates a [task]({{% INFLUXDB_DOCS_URL %}}/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. - The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. - #### Related guides + #### InfluxDB Cloud - - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + - 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: | - In the request body, provide the task properties to update. - To provide the script that the task runs, - set either the `flux` property or the `scriptID` property. - - If you set `scriptID`, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, provide the `task` configuration option - in the Flux script. - - See [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't set `flux` and `scriptID` properties for the same task--for - example, if you set the `scriptID` property, then InfluxDB sets the `flux` property - to an empty string (`""`). + description: An task update to apply. required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: path @@ -3379,8 +3773,8 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to update. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Specifies the task to update. responses: '200': description: Success. The response body contains the updated task. @@ -3404,13 +3798,12 @@ paths: - Tasks summary: Delete a task description: | - Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + Deletes a [task]({{% INFLUXDB_DOCS_URL %}}/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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` - property to `inactive`. + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). parameters: - $ref: '#/paths/~1users/get/parameters/0' - in: path @@ -3418,9 +3811,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. + description: 'A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. Specifies the task to delete.' responses: '204': description: Success. The task and task runs are deleted. Scheduled runs are canceled. @@ -3545,21 +3936,21 @@ components: dashboards: /api/v2/dashboards?org=myorg properties: self: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' secrets: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' buckets: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' tasks: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' dashboards: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -3605,22 +3996,22 @@ components: properties: labels: description: The URL to retrieve labels for this bucket. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: description: The URL to retrieve members that can read this bucket. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' org: description: The URL to retrieve parent organization for this bucket. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: description: The URL to retrieve owners that can read and write to this bucket. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' self: description: The URL for this bucket. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' write: description: The URL to write line protocol to this bucket. - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -3698,11 +4089,11 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' required: - name - retentionRules @@ -3711,17 +4102,7 @@ components: - orgID - permissions allOf: - - 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. + - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' - type: object properties: createdAt: @@ -3744,72 +4125,7 @@ components: The list of permissions. An authorization must have at least one permission. items: - required: - - action - - resource - properties: - action: - type: string - enum: - - read - - write - 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. + $ref: '#/paths/~1authorizations/post/requestBody/content/application~1json/schema/allOf/1/properties/permissions/items' id: readOnly: true type: string @@ -3852,10 +4168,10 @@ components: properties: self: readOnly: true - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' user: readOnly: true - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' Limit: type: object description: These are org limits similar to those configured in/by quartz. @@ -4016,28 +4332,7 @@ components: sort_order: type: integer labels: - type: array - items: - 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 + $ref: '#/components/schemas/Task/properties/labels' arguments: type: object oneOf: @@ -4309,33 +4604,31 @@ components: id: readOnly: true type: string - description: | - The resource ID that InfluxDB uses to uniquely identify the task. orgID: description: | - An organization ID. - Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Specifies the organization that owns the task. type: string org: description: | - An organization name. - Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Specifies the organization that owns the task. type: string name: description: The name of the task. type: string - description: - description: A description of the task. - type: string ownerID: description: | - A user ID. - Identifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task. + A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + 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: type: string enum: @@ -4344,11 +4637,32 @@ components: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. labels: - $ref: '#/components/schemas/Variable/properties/labels' + type: array + items: + 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 authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + 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 @@ -4356,14 +4670,12 @@ components: type: string flux: description: | - Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - and the script for the task to run. + The Flux script that the task executes. - #### Related guides - - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + #### Limitations + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. type: string - format: Flux + format: flux every: description: 'The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string @@ -4371,7 +4683,6 @@ components: 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 - format: cron 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 @@ -4411,21 +4722,45 @@ components: logs: /api/v2/tasks/1/logs properties: self: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + type: string + format: uri + readOnly: true + description: URI of resource. owners: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' runs: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' logs: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/0/allOf/1/properties/links/properties/org' + $ref: '#/components/schemas/Task/properties/links/properties/self' scriptID: - $ref: '#/components/schemas/TaskScriptID' + 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]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + 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 @@ -4434,74 +4769,85 @@ components: type: object properties: orgID: - $ref: '#/components/schemas/Task/properties/orgID' + description: The ID of the organization that owns the task. + type: string org: - $ref: '#/components/schemas/Task/properties/org' - name: - $ref: '#/components/schemas/Task/properties/name' - description: - $ref: '#/components/schemas/Task/properties/description' - every: - $ref: '#/components/schemas/Task/properties/every' - cron: - $ref: '#/components/schemas/Task/properties/cron' - offset: - $ref: '#/components/schemas/Task/properties/offset' + description: The name of the organization that owns the task. + type: string status: $ref: '#/components/schemas/Task/properties/status' flux: - $ref: '#/components/schemas/Task/properties/flux' - scriptID: - $ref: '#/components/schemas/TaskScriptID' - scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' - TaskScriptID: - description: | - A script ID. - Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. + description: | + The Flux script that the task runs. - #### Related guides + #### Limitations - - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). - type: string - TaskScriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified - by the `scriptID` property. - When running the task, InfluxDB executes the script with the parameters - you provide. + - 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 + #### Limitations - - To use the `scriptParameters` property, you must also set the `scriptID` property - for the task. + - 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. - #### Related guides + #### Limitations - - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). - type: object + - `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/Task/properties/status' + flux: + description: Update the Flux script that the task runs. + type: string name: - $ref: '#/components/schemas/Task/properties/name' - description: - $ref: '#/components/schemas/Task/properties/description' + description: Update the 'name' option in the flux script. + type: string every: - $ref: '#/components/schemas/Task/properties/every' + description: Update the 'every' option in the flux script. + type: string cron: - $ref: '#/components/schemas/Task/properties/cron' + description: Update the 'cron' option in the flux script. + type: string offset: - $ref: '#/components/schemas/Task/properties/offset' - flux: - $ref: '#/components/schemas/Task/properties/flux' + description: Update the 'offset' option in the flux script. + type: string + description: + description: Update the description of the task. + type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + description: Update the 'scriptID' of the task. + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + description: Update the 'scriptParameters' of the task. + type: object responses: null examples: AuthorizationPostRequest: @@ -4541,7 +4887,7 @@ components: 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\")" + 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: @@ -4593,7 +4939,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides diff --git a/contracts/cloud.json b/contracts/cloud.json index 5e35b5dc2..c2797910a 100644 --- a/contracts/cloud.json +++ b/contracts/cloud.json @@ -16,8 +16,8 @@ ], "tags": [ { - "name": "Authorizations (API tokens)", - "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf the user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" + "name": "Authorizations", + "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nIn InfluxDB Cloud, an authorization with `read-authorizations` permission\ncan be used to view other authorizations.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- InfluxDB allows access to the API token value immediately after the authorization is created.\n- You can’t change access (read/write) permissions for an API token after it’s created.\n- Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n#### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf the user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" }, { "name": "Buckets", @@ -29,7 +29,7 @@ }, { "name": "Invokable Scripts", - "description": "Store, manage, and execute scripts in InfluxDB.\nA script stores your custom Flux script and provides an invokable\nendpoint that accepts runtime parameters.\nIn a script, you can specify custom runtime parameters\n(`params`)--for example, `params.myparameter`.\nOnce you create a script, InfluxDB generates an\n[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)\nfor your organization.\nYou can run the script from API requests and tasks, defining parameter\nvalues for each run.\nWhen the script runs, InfluxDB replaces `params` references in the\nscript with the runtime parameter values you define.\n\nUse the `/api/v2/scripts` endpoints to create and manage scripts.\nSee related guides to learn how to define parameters and execute scripts.\n\n### Related guides\n\n- [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests.\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n" + "description": "Store, manage, and execute scripts in InfluxDB.\nA script stores your custom Flux script and provides an invokable\nendpoint that accepts runtime parameters.\nIn a script, you can specify custom runtime parameters\n(`params`)--for example, `params.myparameter`.\nOnce you create a script, InfluxDB generates an\n[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)\nfor your organization.\nYou can run the script from API requests and tasks, defining parameter\nvalues for each run.\nWhen the script runs, InfluxDB replaces `params` references in the\nscript with the runtime parameter values you define.\n\nUse the `/api/v2/scripts` endpoints to create and manage scripts.\nSee related guides to learn how to define parameters and execute scripts.\n\n#### Related guides\n\n- [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests.\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n" }, { "name": "Delete", @@ -45,15 +45,15 @@ }, { "name": "Tasks", - "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in this object:\n\n\n\n### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)\n" + "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n#### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in this object:\n\n\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Create a script](https://docs.influxdata.com/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script)\n" }, { "name": "Templates", - "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for resources.\nUse InfluxDB templates to configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" + "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for resources.\nUse InfluxDB templates to configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n#### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" }, { "name": "Users", - "description": "Retrieve specific users.\n\nInfluxDB Cloud lets you invite and collaborate with multiple users in your organization.\nTo invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);\nyou can't use the InfluxDB API to manage users in InfluxDB Cloud.\nOnce a user is added to your organization, you can use the\n`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to\nview specific members.\n\n### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n" + "description": "Retrieve specific users.\n\nInfluxDB Cloud lets you invite and collaborate with multiple users in your organization.\nTo invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);\nyou can't use the InfluxDB API to manage users in InfluxDB Cloud.\nOnce a user is added to your organization, you can use the\n`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to\nview specific members.\n\n#### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n" }, { "name": "Write", @@ -87,7 +87,7 @@ { "name": "Pagination", "x-traitTag": true, - "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n | Query parameter | Value type | Description |\n |:------------------------ |:--------------------- |:-------------------------------------------|\n | `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n | `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n ### Limitations\n\n - For specific endpoint parameters and examples, see the endpoint definition.\n - If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" + "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n | Query parameter | Value type | Description |\n |:------------------------ |:--------------------- |:-------------------------------------------|\n | `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n | `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n #### Limitations\n\n - For specific endpoint parameters and examples, see the endpoint definition.\n - If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" }, { "name": "Response codes", @@ -6391,7 +6391,7 @@ "Buckets" ], "summary": "List all owners of a bucket", - "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6467,7 +6467,7 @@ "Buckets" ], "summary": "Add an owner to a bucket", - "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6565,7 +6565,7 @@ "Buckets" ], "summary": "Remove an owner from a bucket", - "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7121,7 +7121,7 @@ "Security and access endpoints" ], "summary": "List all members of an organization", - "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7222,7 +7222,7 @@ "Organizations" ], "summary": "Add a member to an organization", - "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7321,7 +7321,7 @@ "Security and access endpoints" ], "summary": "Remove a member from an organization", - "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7379,7 +7379,7 @@ "Security and access endpoints" ], "summary": "List all owners of an organization", - "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", + "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7453,7 +7453,7 @@ "Organizations" ], "summary": "Add an owner to an organization", - "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", + "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7543,7 +7543,7 @@ "Security and access endpoints" ], "summary": "Remove an owner from an organization", - "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", + "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8437,7 +8437,7 @@ "Tasks" ], "summary": "List runs for a task", - "description": "Lists runs for the specified [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf you don't pass query parameters, InfluxDB returns all runs for the task\nup to the default `limit`.\n", + "description": "Retrieves a list of runs for a [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all task runs up to the default `limit`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8449,7 +8449,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto list runs for.\n" + "description": "The ID of the task to get runs for.\nOnly returns runs for this task.\n" }, { "in": "query", @@ -8457,7 +8457,7 @@ "schema": { "type": "string" }, - "description": "A task run ID. Only returns runs created after the specified run." + "description": "A task run ID. Only returns runs created after this run." }, { "in": "query", @@ -8477,7 +8477,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after the specified time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after this time.\n" }, { "in": "query", @@ -8486,7 +8486,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before the specified time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before this time.\n" } ], "responses": { @@ -8518,7 +8518,7 @@ "Tasks" ], "summary": "Start a task run, overriding the schedule", - "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", + "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8529,8 +8529,7 @@ "schema": { "type": "string" }, - "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto run.\n" + "required": true } ], "requestBody": { @@ -8553,25 +8552,6 @@ } } }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "inactiveTask": { - "summary": "Can't run an inactive task", - "value": { - "code": "invalid", - "message": "failed to force run: inactive task" - } - } - } - } - } - }, "401": { "$ref": "#/components/responses/AuthorizationError" }, @@ -8591,7 +8571,7 @@ "Tasks" ], "summary": "Retrieve a run for a task.", - "description": "Retrieves the specified run for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", + "description": "Retrieves a specific run for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8603,7 +8583,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nthat the task run belongs to.\n" + "description": "The ID of the task to retrieve runs for." }, { "in": "path", @@ -8612,7 +8592,7 @@ "type": "string" }, "required": true, - "description": "A task run ID. Specifies the run to retrieve." + "description": "The ID of the run to retrieve." } ], "responses": { @@ -8681,7 +8661,7 @@ "Tasks" ], "summary": "Cancel a running task", - "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", + "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint with InfluxDB OSS to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8693,7 +8673,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto cancel.\n" + "description": "The ID of the task to cancel." }, { "in": "path", @@ -8702,7 +8682,7 @@ "type": "string" }, "required": true, - "description": "A task run ID.\nSpecifies the task run to cancel.\n" + "description": "The ID of the task run to cancel." } ], "responses": { @@ -8744,7 +8724,7 @@ "Tasks" ], "summary": "Retry a task run", - "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and then returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", + "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- The task must be _active_ (`status: \"active\"`).\n", "requestBody": { "content": { "application/json; charset=utf-8": { @@ -8765,7 +8745,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the task run belongs to.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to retry.\n" }, { "in": "path", @@ -8774,7 +8754,7 @@ "type": "string" }, "required": true, - "description": "A task run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" } ], "responses": { @@ -8846,8 +8826,8 @@ "tags": [ "Tasks" ], - "summary": "List logs for a task", - "description": "Lists all log events for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen a task runs, InfluxDB creates a `run` record in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", + "summary": "Retrieve all logs for a task", + "description": "Retrieves a list of all logs for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen an InfluxDB task runs, a “run” record is created in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8859,12 +8839,12 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve logs for." + "description": "The task ID." } ], "responses": { "200": { - "description": "Success.\nThe response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", + "description": "Success. The response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", "content": { "application/json": { "schema": { @@ -8872,7 +8852,7 @@ }, "examples": { "taskSuccess": { - "summary": "Events for a successful task run", + "summary": "Events for a successful task run.", "value": { "events": [ { @@ -8889,7 +8869,7 @@ } }, "taskFailure": { - "summary": "Events for a failed task run", + "summary": "Events for a failed task run.", "value": { "events": [ { @@ -8938,8 +8918,8 @@ "tags": [ "Tasks" ], - "summary": "List logs for a run", - "description": "Lists all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) performance and troubleshoot failed task runs.\n", + "summary": "Retrieve all logs for a run", + "description": "Retrieves all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze task performance and troubleshoot failed task runs.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8951,7 +8931,7 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the run belongs to." + "description": "The ID of the task to get logs for." }, { "in": "path", @@ -8960,7 +8940,7 @@ "type": "string" }, "required": true, - "description": "A run ID. Specifies the task run to list logs for." + "description": "The ID of the run to get logs for." } ], "responses": { @@ -9040,7 +9020,7 @@ "Tasks" ], "summary": "List labels for a task", - "description": "Lists all labels for a task.\n\nUse this endpoint to list labels applied to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", + "description": "Retrieves a list of all labels for a task.\n\nLabels may be used for grouping and filtering tasks.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9052,7 +9032,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the task to retrieve labels for.\n" + "description": "The ID of the task to retrieve labels for." } ], "responses": { @@ -9089,7 +9069,7 @@ "Tasks" ], "summary": "Add a label to a task", - "description": "Adds a label to a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to add a label to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", + "description": "Adds a label to a task.\n\nUse this endpoint to add a label that you can use to filter tasks in the InfluxDB UI.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9101,11 +9081,11 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to label.\n" + "description": "The ID of the task to label." } ], "requestBody": { - "description": "In the request body, provide an object that specifies the label.\n", + "description": "An object that contains a _`labelID`_ to add to the task.", "required": true, "content": { "application/json": { @@ -9117,7 +9097,7 @@ }, "responses": { "201": { - "description": "Success. The response body contains the label.", + "description": "Success. The response body contains a list of all labels for the task.", "content": { "application/json": { "schema": { @@ -9151,7 +9131,7 @@ "Tasks" ], "summary": "Delete a label from a task", - "description": "Deletes a label from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "Deletes a label from a task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9163,7 +9143,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete the label from.\n" + "description": "The ID of the task to delete the label from." }, { "in": "path", @@ -9172,7 +9152,7 @@ "type": "string" }, "required": true, - "description": "A label ID.\nSpecifies the label to delete.\n" + "description": "The ID of the label to delete." } ], "responses": { @@ -9204,7 +9184,7 @@ "Config" ], "summary": "Retrieve feature flags", - "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/)\n", + "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9345,7 +9325,7 @@ "Tasks" ], "summary": "List all task members", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9357,12 +9337,12 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve members for.\n" + "description": "The task ID." } ], "responses": { "200": { - "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n\nIf the task has no members, the response contains an empty `users` array.\n", + "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n", "content": { "application/json": { "schema": { @@ -9390,7 +9370,7 @@ "Tasks" ], "summary": "Add a member to a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a user to members of a task and returns the member.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9402,11 +9382,11 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task for the member.\n" + "description": "The task ID." } ], "requestBody": { - "description": "In the request body, provide an object that specifies the user.\n", + "description": "A user to add as a member of the task.", "required": true, "content": { "application/json": { @@ -9418,7 +9398,7 @@ }, "responses": { "201": { - "description": "Created. The task `member` role is assigned to the user.\nThe response body contains the resource member with\nrole and user detail.\n", + "description": "Created. The user is added to task members.", "content": { "application/json": { "schema": { @@ -9448,7 +9428,7 @@ "Tasks" ], "summary": "Remove a member from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9460,7 +9440,7 @@ "type": "string" }, "required": true, - "description": "A user ID. Specifies the member to remove." + "description": "The ID of the member to remove." }, { "in": "path", @@ -9469,12 +9449,12 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the member from." + "description": "The task ID." } ], "responses": { "204": { - "description": "Success. The member is removed." + "description": "Member removed" }, "default": { "description": "Unexpected error", @@ -9497,7 +9477,7 @@ "Tasks" ], "summary": "List all owners of a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRetrieves all users that have owner permission for a task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9509,7 +9489,7 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the task to retrieve owners for." + "description": "The ID of the task to retrieve owners for." } ], "responses": { @@ -9558,7 +9538,7 @@ "Tasks" ], "summary": "Add an owner for a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAssigns a task `owner` role to a user.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9570,11 +9550,11 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) for the owner.\n" + "description": "The task ID." } ], "requestBody": { - "description": "In the request body, provide an object that specifies the user.\n", + "description": "A user to add as an owner of the task.", "required": true, "content": { "application/json": { @@ -9647,7 +9627,7 @@ "Tasks" ], "summary": "Remove an owner from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9659,7 +9639,7 @@ "type": "string" }, "required": true, - "description": "A user ID. Specifies the owner to remove from the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)." + "description": "The ID of the owner to remove." }, { "in": "path", @@ -9668,12 +9648,12 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the owner from.\n" + "description": "The task ID." } ], "responses": { "204": { - "description": "Success. The owner is removed." + "description": "Owner removed" }, "default": { "description": "Unexpected error", @@ -11379,77 +11359,66 @@ } } }, - "/authorizations": { + "/users": { "get": { - "operationId": "GetAuthorizations", + "operationId": "GetUsers", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Security and access endpoints", + "Users" ], - "summary": "List authorizations", - "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\nTo retrieve an authorization, the request must use an API token that has the\nfollowing permissions:\n\n- `read-authorizations`\n- `read-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "summary": "List users", + "description": "Lists [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\nTo limit which users are returned, pass query parameters in your request.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't allow listing all users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| List all users | Operator token | InfluxData internal use only |\n| List a specific user | `read-users` or `read-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to retrieve.\n\n#### Related guides\n\n- [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "query", - "name": "userID", - "schema": { - "type": "string" - }, - "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "user", - "schema": { - "type": "string" - }, - "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, - { - "in": "query", - "name": "orgID", - "schema": { - "type": "string" - }, - "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." - }, - { - "in": "query", - "name": "org", + "name": "name", "schema": { "type": "string" }, - "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + "description": "A user name.\nOnly lists the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" }, { "in": "query", - "name": "token", + "name": "id", "schema": { "type": "string" }, - "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nSpecifies an authorization by its `token` property value\nand returns the authorization.\n\n#### InfluxDB OSS\n\n- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,\n applies other parameters, and then returns the result.\n\n#### Limitations\n\n- The parameter is non-repeatable. If you specify more than one,\n only the first one is used. If a resource with the specified\n property value doesn't exist, then the response body contains an empty list.\n" + "description": "A user id.\nOnly lists the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" } ], "responses": { "200": { - "description": "Success. The response body contains a list of authorizations.\n\nIf the response body is missing authorizations that you expect, check that the API\ntoken used in the request has `read-user` permission for the users (`userID` property value)\nin those authorizations.\n\n#### InfluxDB OSS\n\n- **Warning**: The response body contains authorizations with their\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in clear text.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n", + "description": "Success. The response contains a list of `users`.\n\n#### InfluxDB Cloud\n\n- Returns an empty `users` list if you don't pass _`id`_ or _`name`_ parameters and don't use an\n _operator token_.\n Only InfluxData can access InfluxDB Cloud operator tokens.\n", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Authorizations" + "$ref": "#/components/schemas/Users" } } } }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, "401": { - "$ref": "#/components/responses/AuthorizationError" + "description": "Unauthorized.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed,\n but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -11461,57 +11430,58 @@ } }, "post": { - "operationId": "PostAuthorizations", + "operationId": "PostUsers", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Users" ], - "summary": "Create an authorization", - "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe API token is the authorization's `token` property value.\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n - InfluxDB allows access to the API token value immediately after the authorization is created.\n - You can’t change access (read/write) permissions for an API token after it’s created.\n - Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n - Create a generic user to create and manage tokens for writing data.\n - Store your tokens in a secure password vault for future access.\n\n#### Required permissions\n\n- `write-authorizations`\n- `write-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", + "summary": "Create a user", + "description": "(InfluxData internal use only)\n\nCreates and returns a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user)\nthat can access InfluxDB.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud Doesn't let you manage users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| Create user | Operator token | InfluxData internal use only |\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" } ], "requestBody": { - "description": "The authorization to create.", + "description": "In the request body, provide the user.", "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" - } + "$ref": "#/components/schemas/User" } } } }, "responses": { "201": { - "description": "Success. The authorization is created. The response body contains the\nauthorization.\n", + "description": "Success.\nThe response body contains the user.\n", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Authorization" + "$ref": "#/components/schemas/UserResponse" } } } }, - "400": { - "description": "Invalid request", - "$ref": "#/components/responses/GeneralServerError" - }, "401": { - "$ref": "#/components/responses/AuthorizationError" + "description": "Unauthorized.\n\n#### InfluxDB Cloud\n\n- Returns this error if the request doesn't use an _operator token_.\n Only InfluxData can access InfluxDB Cloud operator tokens.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed,\n but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -11523,88 +11493,39 @@ } } }, - "/authorizations/{authID}": { + "/users/{userID}": { "get": { - "operationId": "GetAuthorizationsID", + "operationId": "GetUsersID", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Users" ], - "summary": "Retrieve an authorization", - "description": "Retrieves an authorization.\n\nUse this endpoint to retrieve information about an API token, including\nthe token's permissions and the user that the token is scoped to.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "externalDocs": { - "url": "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/", - "description": "View tokens" - }, + "summary": "Retrieve a user", + "description": "Retrieves a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "path", - "name": "authID", + "name": "userID", "schema": { "type": "string" }, "required": true, - "description": "An authorization ID. Specifies the authorization to retrieve." + "description": "A user ID.\nRetrieves the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" } ], "responses": { "200": { - "description": "Success. The response body contains the authorization.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Authorization" - } - } - } - }, - "400": { - "description": "Bad request.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "notFound": { - "summary": "The specified resource ID is invalid.\n", - "value": { - "code": "invalid", - "message": "id must have a length of 16 bytes" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "description": "Not found.\n", + "description": "Success. The response body contains the user.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "notFound": { - "summary": "The requested authorization doesn't exist.\n", - "value": { - "code": "not found", - "message": "authorization not found" - } - } + "$ref": "#/components/schemas/UserResponse" } } } }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, "default": { "description": "Unexpected error", "$ref": "#/components/responses/GeneralServerError" @@ -11612,20 +11533,19 @@ } }, "patch": { - "operationId": "PatchAuthorizationsID", + "operationId": "PatchUsersID", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Users" ], - "summary": "Update an API token to be active or inactive", - "description": "Updates an authorization.\n\nUse this endpoint to set an API token's status to be _active_ or _inactive_.\nInfluxDB rejects requests that use inactive API tokens.\n", + "summary": "Update a user", + "description": "(InfluxData internal use only)\n\nUpdates a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) and returns the user.\n\n#### InfluxDB Cloud\n\n- Doesn't let you manage users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| Update user | Operator token | InfluxData internal use only |\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", "requestBody": { - "description": "In the request body, provide the authorization properties to update.", + "description": "The user update to apply.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthorizationUpdateRequest" + "$ref": "#/components/schemas/User" } } } @@ -11636,100 +11556,181 @@ }, { "in": "path", - "name": "authID", + "name": "userID", "schema": { "type": "string" }, "required": true, - "description": "An authorization ID. Specifies the authorization to update." + "description": "A user ID.\nUpdates the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" } ], "responses": { "200": { - "description": "Success. The response body contains the updated authorization.", + "description": "Success. The response body contains the updated user.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Authorization" + "$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": { - "description": "Unexpected error", "$ref": "#/components/responses/GeneralServerError" } } }, "delete": { - "operationId": "DeleteAuthorizationsID", + "operationId": "DeleteUsersID", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Users" ], - "summary": "Delete an authorization", - "description": "Deletes an authorization.\n\nUse the endpoint to delete an API token.\n\nIf you want to disable an API token instead of delete it,\n[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).\n", + "summary": "Delete a user", + "description": "(InfluxData internal use only)\n\nDeletes a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\nFor security purposes, once an InfluxDB user account is deleted from an\norganization, the user (and their token) cannot be reactivated.\n\n#### InfluxDB Cloud\n\n- Doesn't let you manage users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| Delete user | Operator token | InfluxData internal use only |\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "path", - "name": "authID", + "name": "userID", "schema": { "type": "string" }, "required": true, - "description": "An authorization ID. Specifies the authorization to delete." + "description": "A user ID.\nDeletes the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" } ], "responses": { "204": { - "description": "Success. The authorization is deleted." + "description": "Success. The user is deleted." }, "400": { - "description": "Bad request.\n", + "$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/Error" - }, - "examples": { - "notFound": { - "summary": "The specified resource ID is invalid.\n", - "value": { - "code": "invalid", - "message": "id must have a length of 16 bytes" - } - } + "$ref": "#/components/schemas/IsOnboarding" } } } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "description": "Not found.\n", + } + } + }, + "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/Error" - }, - "examples": { - "notFound": { - "summary": "The requested authorization doesn't exist.\n", - "value": { - "code": "not found", - "message": "authorization not found" - } - } + "$ref": "#/components/schemas/OnboardingResponse" } } } }, - "500": { - "$ref": "#/components/responses/InternalServerError" + "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", @@ -11738,66 +11739,76 @@ } } }, - "/users": { + "/authorizations": { "get": { - "operationId": "GetUsers", + "operationId": "GetAuthorizations", "tags": [ - "Security and access endpoints", - "Users" + "Authorizations" ], - "summary": "List users", - "description": "Lists [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\nTo limit which users are returned, pass query parameters in your request.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't allow listing all users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| List all users | Operator token | InfluxData internal use only |\n| List a specific user | `read-users` or `read-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to retrieve.\n\n#### Related guides\n\n- [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/)\n", + "summary": "List authorizations", + "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations for the organization.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\n- `read-authorizations`\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "query", - "name": "name", + "name": "userID", "schema": { "type": "string" }, - "description": "A user name.\nOnly lists the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "A user ID.\nOnly returns authorizations scoped to the specified\n[user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" }, { "in": "query", - "name": "id", + "name": "user", "schema": { "type": "string" }, - "description": "A user id.\nOnly lists the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "A user name.\nOnly returns authorizations scoped to the specified\n[user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "orgID", + "schema": { + "type": "string" + }, + "description": "An organization ID.\nOnly returns authorizations that belong to the specified\n[organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + }, + { + "in": "query", + "name": "org", + "schema": { + "type": "string" + }, + "description": "An organization name.\nOnly returns authorizations that belong to the specified\n[organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + }, + { + "in": "query", + "name": "token", + "schema": { + "type": "string" + }, + "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nReturns the authorization for the specified token.\n" } ], "responses": { "200": { - "description": "Success. The response contains a list of `users`.\n\n#### InfluxDB Cloud\n\n- Returns an empty `users` list if you don't pass _`id`_ or _`name`_ parameters and don't use an\n _operator token_.\n Only InfluxData can access InfluxDB Cloud operator tokens.\n", + "description": "Success. The response body contains a list of authorizations.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Users" + "$ref": "#/components/schemas/Authorizations" } } } }, - "401": { - "description": "Unauthorized.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" }, - "422": { - "description": "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed,\n but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "401": { + "$ref": "#/components/responses/AuthorizationError" }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -11809,58 +11820,56 @@ } }, "post": { - "operationId": "PostUsers", + "operationId": "PostAuthorizations", "tags": [ - "Users" + "Authorizations" ], - "summary": "Create a user", - "description": "(InfluxData internal use only)\n\nCreates and returns a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user)\nthat can access InfluxDB.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud Doesn't let you manage users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| Create user | Operator token | InfluxData internal use only |\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Create an authorization", + "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB Cloud enforces access restrictions on API tokens.\n\n- InfluxDB only allows access to the API token value immediately after the authorization is created.\n- You can't update an authorization's permissions.\n- A token stops working when the user who created the authorization is deleted.\n\nWe recommend the following for managing your tokens:\n\n- Create a generic user to create and manage tokens for writing data.\n- Store your tokens in a secure password vault for future access.\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" } ], "requestBody": { - "description": "In the request body, provide the user.", + "description": "The authorization to create.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/AuthorizationPostRequest" + }, + "examples": { + "AuthorizationPostRequest": { + "$ref": "#/components/examples/AuthorizationPostRequest" + }, + "AuthorizationWithResourcePostRequest": { + "$ref": "#/components/examples/AuthorizationWithResourcePostRequest" + }, + "AuthorizationWithUserPostRequest": { + "$ref": "#/components/examples/AuthorizationWithUserPostRequest" + } } } } }, "responses": { "201": { - "description": "Success.\nThe response body contains the user.\n", + "description": "Success. The authorization is created. The response body contains the authorization.\n", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserResponse" + "$ref": "#/components/schemas/Authorization" } } } }, - "401": { - "description": "Unauthorized.\n\n#### InfluxDB Cloud\n\n- Returns this error if the request doesn't use an _operator token_.\n Only InfluxData can access InfluxDB Cloud operator tokens.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" }, - "422": { - "description": "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed,\n but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "401": { + "$ref": "#/components/responses/AuthorizationError" }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -11872,35 +11881,34 @@ } } }, - "/users/{userID}": { + "/authorizations/{authID}": { "get": { - "operationId": "GetUsersID", + "operationId": "GetAuthorizationsID", "tags": [ - "Users" + "Authorizations" ], - "summary": "Retrieve a user", - "description": "Retrieves a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Retrieve an authorization", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "path", - "name": "userID", + "name": "authID", "schema": { "type": "string" }, "required": true, - "description": "A user ID.\nRetrieves the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "The identifier of the authorization to get." } ], "responses": { "200": { - "description": "Success. The response body contains the user.", + "description": "Authorization details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserResponse" + "$ref": "#/components/schemas/Authorization" } } } @@ -11912,19 +11920,19 @@ } }, "patch": { - "operationId": "PatchUsersID", + "operationId": "PatchAuthorizationsID", "tags": [ - "Users" + "Authorizations" ], - "summary": "Update a user", - "description": "(InfluxData internal use only)\n\nUpdates a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) and returns the user.\n\n#### InfluxDB Cloud\n\n- Doesn't let you manage users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions for InfluxDB Cloud\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| Update user | Operator token | InfluxData internal use only |\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Update authorization status", + "description": "Update an authorization's status to `active` or `inactive`.", "requestBody": { - "description": "The user update to apply.", + "description": "The updated Authorization object.", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/AuthorizationUpdateRequest" } } } @@ -11935,181 +11943,54 @@ }, { "in": "path", - "name": "userID", + "name": "authID", "schema": { "type": "string" }, "required": true, - "description": "A user ID.\nUpdates the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "The identifier of the authorization to update." } ], "responses": { "200": { - "description": "Success. The response body contains the updated user.", + "description": "The updated authorization.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserResponse" + "$ref": "#/components/schemas/Authorization" } } } }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "$ref": "#/components/responses/ResourceNotFoundError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, "default": { + "description": "Unexpected error", "$ref": "#/components/responses/GeneralServerError" } } }, "delete": { - "operationId": "DeleteUsersID", + "operationId": "DeleteAuthorizationsID", "tags": [ - "Users" + "Authorizations" ], - "summary": "Delete a user", - "description": "(InfluxData internal use only)\n\nDeletes a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\nFor security purposes, once an InfluxDB user account is deleted from an\norganization, the user (and their token) cannot be reactivated.\n\n#### InfluxDB Cloud\n\n- Doesn't let you manage users through the API.\n Use the InfluxDB Cloud user interface (UI) to manage account information.\n\n#### Required permissions\n\n| Action | Permission required | Restriction |\n|:-------|:--------------------|:------------|\n| Delete user | Operator token | InfluxData internal use only |\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Delete an authorization", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "path", - "name": "userID", + "name": "authID", "schema": { "type": "string" }, "required": true, - "description": "A user ID.\nDeletes the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "The identifier of the authorization to delete." } ], "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" - } - } - } + "description": "Authorization deleted" }, "default": { "description": "Unexpected error", @@ -13068,8 +12949,8 @@ "Data I/O endpoints", "Tasks" ], - "summary": "List tasks", - "description": "Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n\n#### Related guide\n\n- [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)\n", + "summary": "List all tasks", + "description": "Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -13077,7 +12958,7 @@ { "in": "query", "name": "name", - "description": "A task name.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) with the specified name.\nDifferent tasks may have the same name.\n", + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name.\nOnly returns tasks with the specified name.\nDifferent tasks may have the same name.\n", "schema": { "type": "string" } @@ -13088,7 +12969,7 @@ "schema": { "type": "string" }, - "description": "A task ID.\nOnly returns [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nOnly returns tasks created after the specified task.\n" }, { "in": "query", @@ -13096,7 +12977,7 @@ "schema": { "type": "string" }, - "description": "A user ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nOnly returns tasks owned by the specified user.\n" }, { "in": "query", @@ -13104,7 +12985,7 @@ "schema": { "type": "string" }, - "description": "An organization name.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nOnly returns tasks owned by the specified organization.\n" }, { "in": "query", @@ -13112,7 +12993,7 @@ "schema": { "type": "string" }, - "description": "An organization ID.\nOnly returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nOnly returns tasks owned by the specified organization.\n" }, { "in": "query", @@ -13124,7 +13005,7 @@ "inactive" ] }, - "description": "A task status.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status.\nOnly returns tasks that have the specified status (`active` or `inactive`).\n" }, { "in": "query", @@ -13161,7 +13042,7 @@ { "in": "query", "name": "sortBy", - "description": "The sort field.\nSpecifies the task property used to sort records in the list.\nDefault is `name`.\n\nThe parameter has one supported value: `name`.\n", + "description": "The sort field. Only `name` is supported.\nSpecifies the field used to sort records in the list.\n", "required": false, "schema": { "type": "string", @@ -13173,7 +13054,7 @@ { "in": "query", "name": "type", - "description": "A task type.\nSpecifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response.\nDefault is `system`.\n\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, set the `type` parameter to `basic` (`type=basic`)\nto omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) type (`basic` or `system`).\nDefault is `system`.\nSpecifies the level of detail for tasks in the response.\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", "required": false, "schema": { "default": "", @@ -13187,7 +13068,7 @@ { "in": "query", "name": "scriptID", - "description": "A script ID.\nOnly returns tasks that use the specified [invokable script](#tag/Invokable-Scripts).\n", + "description": "A [script](#tag/Invokable-Scripts) ID.\nOnly returns tasks that use the specified invokable script.\n", "schema": { "type": "string" } @@ -13298,34 +13179,26 @@ "Tasks" ], "summary": "Create a task", - "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\nUse this endpoint to create a scheduled task that runs a script.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\nUse this endpoint to create a scheduled task that runs a Flux script.\n\n#### InfluxDB Cloud\n\n- You can use either `flux` or `scriptID` to provide the task script.\n\n - `flux`: a string of \"raw\" Flux that contains task options and the script--for example:\n\n ```json\n {\n \"flux\": \"option task = {name: \\\"CPU Total 1 Hour New\\\", every: 1h}\\\n from(bucket: \\\"telegraf\\\")\n |> range(start: -1h)\n |> filter(fn: (r) => (r._measurement == \\\"cpu\\\"))\n |> filter(fn: (r) =>\\n\\t\\t(r._field == \\\"usage_system\\\"))\n |> filter(fn: (r) => (r.cpu == \\\"cpu-total\\\"))\n |> aggregateWindow(every: 1h, fn: max)\n |> to(bucket: \\\"cpu_usage_user_total_1h\\\", org: \\\"INFLUX_ORG\\\")\",\n \"status\": \"active\",\n \"description\": \"This task downsamples CPU data every hour\"\n }\n ```\n\n - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)\n for the task to run.\n To pass task options when using `scriptID`, pass the options as\n properties in the request body--for example:\n\n ```json\n {\n \"name\": \"CPU Total 1 Hour New\",\n \"description\": \"This task downsamples CPU data every hour\",\n \"every\": \"1h\",\n \"scriptID\": \"SCRIPT_ID\",\n \"scriptParameters\":\n {\n \"rangeStart\": \"-1h\",\n \"bucket\": \"telegraf\",\n \"filterField\": \"cpu-total\"\n }\n }\n ```\n\n#### Limitations:\n\n- You can't use `flux` and `scriptID` for the same task.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" } ], "requestBody": { - "description": "In the request body, provide the task.\n\nSet one of the following properties to provide the script that the task runs:\n - `flux`\n - `scriptID`\n\nIf you set the `scriptID` property, you can set the following properties to configure the task:\n - `cron`\n - `every`\n - `offset`\n - `scriptParameters`\n\nIf you set the `flux` property, you must provide the `task` configuration option\nin the Flux script.\n\nSee [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nfor detail and examples.\n\n#### Limitations:\n\n- You can't use `flux` and `scriptID` in the same task.\n", + "description": "The task to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" - }, - "examples": { - "TaskWithFlux": { - "$ref": "#/components/examples/TaskWithFluxRequest" - }, - "TaskWithScriptID": { - "$ref": "#/components/examples/TaskWithScriptRequest" - } } } } }, "responses": { "201": { - "description": "Success. The response body contains a `tasks` list with the task.", + "description": "Success. The response body contains a `tasks` list with the new task.", "content": { "application/json": { "schema": { @@ -13335,7 +13208,7 @@ } }, "400": { - "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB Cloud\n\n- Returns this error if the task doesn't contain the `flux` property\n or the `scriptID` property.\n- Returns this error if the task contains `flux` _and_ `scriptID`\n properties.\n", + "description": "Bad request.\nThe response body contains detail about the error.\n\n#### InfluxDB Cloud\n\n- Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_.\n- Returns this error if the task contains _`flux`_ _and_ _`scriptID`_.\n", "content": { "application/json": { "schema": { @@ -13376,7 +13249,19 @@ } } } - } + }, + "x-codeSamples": [ + { + "lang": "Shell", + "label": "cURL: create a Flux script task", + "source": "curl INFLUX_URL/api/v2/tasks \\\n--header \"Content-type: application/json\" \\\n--header \"Authorization: Token INFLUX_API_TOKEN\" \\\n--data-binary @- << EOF\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"description\": \"IoT Center 30d environment average.\",\n \"flux\": \"option task = {name: \\\"iot-center-task-1\\\", every: 30m}\\\n from(bucket: \\\"iot_center\\\")\\\n |> range(start: -30d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\\\n |> aggregateWindow(every: 1h, fn: mean)\"\n }\nEOF\n" + }, + { + "lang": "Shell", + "label": "cURL: create a Flux script reference task", + "source": "curl INFLUX_URL/api/v2/tasks \\\n--header \"Content-type: application/json\" \\\n--header \"Authorization: Token INFLUX_API_TOKEN\" \\\n--data-binary @- << EOF\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"description\": \"IoT Center 30d environment average.\",\n \"scriptID\": \"085138a111448000\",\n \"scriptParameters\":\n {\n \"rangeStart\": \"-30d\",\n \"bucket\": \"air_sensor\",\n \"filterField\": \"temperature\",\n \"groupColumn\": \"_time\"\n }\n }\nEOF\n" + } + ] } }, "/tasks/{taskID}": { @@ -13387,7 +13272,7 @@ "Tasks" ], "summary": "Retrieve a task", - "description": "Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -13399,7 +13284,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to retrieve.\n" } ], "responses": { @@ -13436,22 +13321,14 @@ "Tasks" ], "summary": "Update a task", - "description": "Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task),\nand then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`.\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\nTo activate or inactivate a task, set the `status` property.\nThe `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task.\n\n#### Related guides\n\n- [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "description": "Updates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task),\nand then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`.\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\nTo update a task, pass an object that contains the updated key-value pairs.\nTo activate or inactivate a task, set the `status` property.\n_`\"status\": \"inactive\"`_ cancels scheduled runs and prevents manual runs of the task.\n\n#### InfluxDB Cloud\n\n- Use either `flux` or `scriptID` to provide the task script.\n\n - `flux`: a string of \"raw\" Flux that contains task options and the script--for example:\n\n ```json\n {\n \"flux\": \"option task = {name: \\\"CPU Total 1 Hour New\\\", every: 1h}\\\n from(bucket: \\\"telegraf\\\")\n |> range(start: -1h)\n |> filter(fn: (r) => (r._measurement == \\\"cpu\\\"))\n |> filter(fn: (r) =>\\n\\t\\t(r._field == \\\"usage_system\\\"))\n |> filter(fn: (r) => (r.cpu == \\\"cpu-total\\\"))\n |> aggregateWindow(every: 1h, fn: max)\n |> to(bucket: \\\"cpu_usage_user_total_1h\\\", org: \\\"INFLUX_ORG\\\")\",\n \"status\": \"active\",\n \"description\": \"This task downsamples CPU data every hour\"\n }\n ```\n\n - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts)\n for the task to run.\n To pass task options when using `scriptID`, pass the options as\n properties in the request body--for example:\n\n ```json\n {\n \"name\": \"CPU Total 1 Hour New\",\n \"description\": \"This task downsamples CPU data every hour\",\n \"every\": \"1h\",\n \"scriptID\": \"SCRIPT_ID\",\n \"scriptParameters\":\n {\n \"rangeStart\": \"-1h\",\n \"bucket\": \"telegraf\",\n \"filterField\": \"cpu-total\"\n }\n }\n ```\n\n#### Limitations:\n\n- You can't use `flux` and `scriptID` for the same task.\n", "requestBody": { - "description": "In the request body, provide the task properties to update.\nTo provide the script that the task runs,\nset either the `flux` property or the `scriptID` property.\n\nIf you set `scriptID`, you can set the following properties to configure the task:\n - `cron`\n - `every`\n - `offset`\n - `scriptParameters`\n\nIf you set the `flux` property, provide the `task` configuration option\nin the Flux script.\n\nSee [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nfor detail and examples.\n\n#### Limitations:\n\n- You can't set `flux` and `scriptID` properties for the same task--for\n example, if you set the `scriptID` property, then InfluxDB sets the `flux` property\n to an empty string (`\"\"`).\n", + "description": "An task update to apply.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateRequest" - }, - "examples": { - "TaskWithFlux": { - "$ref": "#/components/examples/TaskWithFluxRequest" - }, - "TaskWithScriptID": { - "$ref": "#/components/examples/TaskWithScriptRequest" - } } } } @@ -13467,7 +13344,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to update.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to update.\n" } ], "responses": { @@ -13504,7 +13381,7 @@ "Tasks" ], "summary": "Delete a task", - "description": "Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nand all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nTo disable a task instead of delete it, use\n[`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status`\nproperty to `inactive`.\n", + "description": "Deletes a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and associated records.\n\nUse this endpoint to delete a task and all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nIf you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -13516,7 +13393,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. Specifies the task to delete." } ], "responses": { @@ -14573,7 +14450,7 @@ "AuthorizationUpdateRequest": { "properties": { "status": { - "description": "Status of the token. If `inactive`, InfluxDB rejects requests that use the token.", + "description": "Status of the token. If `inactive`, requests using the token will be rejected.", "default": "active", "type": "string", "enum": [ @@ -14806,7 +14683,7 @@ "shardGroupDurationSeconds": { "type": "integer", "format": "int64", - "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration).\n" + "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration).\n" } }, "required": [ @@ -16583,42 +16460,6 @@ } } }, - "TaskCron": { - "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", - "format": "cron" - }, - "TaskDescription": { - "description": "A description of the task.", - "type": "string" - }, - "TaskEvery": { - "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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" - }, - "TaskFlux": { - "description": "Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nand the script for the task to run.\n\n#### Related guides\n\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", - "type": "string", - "format": "Flux" - }, - "TaskName": { - "description": "The name of the task.", - "type": "string" - }, - "TaskOffset": { - "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" - }, - "TaskOrg": { - "description": "An organization name.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", - "type": "string" - }, - "TaskOrgID": { - "description": "An organization ID.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", - "type": "string" - }, "TaskStatusType": { "type": "string", "enum": [ @@ -21901,23 +21742,26 @@ "properties": { "id": { "readOnly": true, - "type": "string", - "description": "The resource ID that InfluxDB uses to uniquely identify the task.\n" + "type": "string" }, "orgID": { - "$ref": "#/components/schemas/TaskOrgID" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nSpecifies the organization that owns the task.\n", + "type": "string" }, "org": { - "$ref": "#/components/schemas/TaskOrg" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nSpecifies the organization that owns the task.\n", + "type": "string" }, "name": { - "$ref": "#/components/schemas/TaskName" - }, - "description": { - "$ref": "#/components/schemas/TaskDescription" + "description": "The name of the task.", + "type": "string" }, "ownerID": { - "description": "A user ID.\nIdentifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task.\n\nTo find a user ID, use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", + "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nSpecifies the owner of the task.\n\nTo find a user ID, you can use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", + "type": "string" + }, + "description": { + "description": "A description of the task.", "type": "string" }, "status": { @@ -21927,20 +21771,27 @@ "$ref": "#/components/schemas/Labels" }, "authorizationID": { - "description": "An authorization ID.\nIdentifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", + "description": "An authorization ID.\nSpecifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", "type": "string" }, "flux": { - "$ref": "#/components/schemas/TaskFlux" + "description": "The Flux script that the task executes.\n\n#### Limitations\n - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties.\n", + "type": "string", + "format": "flux" }, "every": { - "$ref": "#/components/schemas/TaskEvery" + "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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": { - "$ref": "#/components/schemas/TaskCron" + "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": { - "$ref": "#/components/schemas/TaskOffset" + "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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.", @@ -22004,10 +21855,12 @@ } }, "scriptID": { - "$ref": "#/components/schemas/TaskScriptID" + "description": "A script ID.\nSpecifies the [invokable script](#tag/Invokable-Scripts) that the task executes.\n\n#### Limitations\n\n- If you use the `scriptID` property, you can't use the `flux` property.\n\n#### Related guides\n\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script)\n", + "type": "string" }, "scriptParameters": { - "$ref": "#/components/schemas/TaskScriptParameters" + "description": "Key-value pairs for `params` in the script.\nDefines the invocation parameter values passed to the script specified by `scriptID`.\nWhen running the task, InfluxDB executes the script with the parameters\nyou provide.\n\n#### Limitations\n\n- To use `scriptParameters`, you must provide a `scriptID`.\n- If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property.\n", + "type": "object" } }, "required": [ @@ -22020,77 +21873,88 @@ "type": "object", "properties": { "orgID": { - "$ref": "#/components/schemas/TaskOrgID" + "description": "The ID of the organization that owns the task.", + "type": "string" }, "org": { - "$ref": "#/components/schemas/TaskOrg" - }, - "name": { - "$ref": "#/components/schemas/TaskName" - }, - "description": { - "$ref": "#/components/schemas/TaskDescription" - }, - "every": { - "$ref": "#/components/schemas/TaskEvery" - }, - "cron": { - "$ref": "#/components/schemas/TaskCron" - }, - "offset": { - "$ref": "#/components/schemas/TaskOffset" + "description": "The name of the organization that owns the task.", + "type": "string" }, "status": { "$ref": "#/components/schemas/TaskStatusType" }, "flux": { - "$ref": "#/components/schemas/TaskFlux" + "description": "The Flux script that the task runs.\n\n#### Limitations\n\n- If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties.\n", + "type": "string" + }, + "description": { + "description": "The description of the task.", + "type": "string" }, "scriptID": { - "$ref": "#/components/schemas/TaskScriptID" + "description": "The ID of the script that the task runs.\n\n#### Limitations\n\n- If you use the `scriptID` property, you can't use the `flux` property.\n", + "type": "string" }, "scriptParameters": { - "$ref": "#/components/schemas/TaskScriptParameters" + "description": "The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run.\n\n#### Limitations\n\n- `scriptParameters` requires `scriptID`.\n- If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property.\n", + "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.\n`every` also determines when the task first runs, depending on the specified time.\n", + "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" } } }, - "TaskScriptID": { - "description": "A script ID.\nIdentifies the [invokable script](#tag/Invokable-Scripts) that the task runs.\n\n#### Related guides\n\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script).\n", - "type": "string" - }, - "TaskScriptParameters": { - "description": "Key-value pairs for `params` in the script.\nDefines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified\nby the `scriptID` property.\nWhen running the task, InfluxDB executes the script with the parameters\nyou provide.\n\n#### Limitations\n\n- To use the `scriptParameters` property, you must also set the `scriptID` property\n for the task.\n\n#### Related guides\n\n- [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script).\n", - "type": "object" - }, "TaskUpdateRequest": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/TaskStatusType" }, - "name": { - "$ref": "#/components/schemas/TaskName" + "flux": { + "description": "Update the Flux script that the task runs.", + "type": "string" }, - "description": { - "$ref": "#/components/schemas/TaskDescription" + "name": { + "description": "Update the 'name' option in the flux script.", + "type": "string" }, "every": { - "$ref": "#/components/schemas/TaskEvery" + "description": "Update the 'every' option in the flux script.", + "type": "string" }, "cron": { - "$ref": "#/components/schemas/TaskCron" + "description": "Update the 'cron' option in the flux script.", + "type": "string" }, "offset": { - "$ref": "#/components/schemas/TaskOffset" + "description": "Update the 'offset' option in the flux script.", + "type": "string" }, - "flux": { - "$ref": "#/components/schemas/TaskFlux" + "description": { + "description": "Update the description of the task.", + "type": "string" }, "scriptID": { - "$ref": "#/components/schemas/TaskScriptID" + "description": "Update the 'scriptID' of the task.", + "type": "string" }, "scriptParameters": { - "$ref": "#/components/schemas/TaskScriptParameters" + "description": "Update the 'scriptParameters' of the task.", + "type": "object" } } } @@ -22258,7 +22122,7 @@ "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\")", + "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." } @@ -22285,7 +22149,7 @@ "type": "apiKey", "name": "Authorization", "in": "header", - "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB Cloud URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n" + "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB Cloud URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n" }, "BasicAuthentication": { "type": "http", diff --git a/contracts/cloud.yml b/contracts/cloud.yml index fe022f567..e8d0b5b93 100644 --- a/contracts/cloud.yml +++ b/contracts/cloud.yml @@ -10,7 +10,7 @@ info: servers: - url: /api/v2 tags: - - name: Authorizations (API tokens) + - name: Authorizations description: | Create and manage authorizations (API tokens). @@ -18,12 +18,24 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. + In InfluxDB Cloud, an authorization with `read-authorizations` permission + can be used to view other authorizations. + + #### Limitations + + 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. - ### User sessions with authorizations + #### 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_, @@ -85,7 +97,7 @@ tags: 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 + #### 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) @@ -114,7 +126,7 @@ tags: - ### Properties + #### Properties A `task` object contains information about an InfluxDB task resource. @@ -122,7 +134,7 @@ tags: - ### Related guides + #### 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/) @@ -145,7 +157,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - ### Related guides + #### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) @@ -160,14 +172,14 @@ tags: `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to view specific members. - ### User sessions with authorizations + #### 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 + #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) - name: Write @@ -233,7 +245,7 @@ tags: | `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 + #### 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, @@ -5348,7 +5360,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5364,7 +5376,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5429,7 +5441,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5444,7 +5456,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5530,7 +5542,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5546,7 +5558,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -6024,7 +6036,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6121,7 +6133,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6221,7 +6233,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6282,7 +6294,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -6343,7 +6355,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -6353,7 +6365,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6428,7 +6440,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6443,7 +6455,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7216,11 +7228,10 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/cloud/process-data/). + 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 you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7229,14 +7240,13 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to - to list runs for. + 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 the specified run. + description: A task run ID. Only returns runs created after this run. - in: query name: limit schema: @@ -7253,7 +7263,7 @@ paths: 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 the specified time. + Only returns runs scheduled after this time. - in: query name: beforeTime schema: @@ -7261,7 +7271,7 @@ paths: 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 the specified time. + Only returns runs scheduled before this time. responses: '200': description: Success. The response body contains the list of task runs. @@ -7290,10 +7300,6 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7301,10 +7307,6 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to - to run. requestBody: content: application/json: @@ -7317,18 +7319,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Run' - '400': - description: Bad request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -7342,7 +7332,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + 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: @@ -7352,16 +7342,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - that the task run belongs to. + description: The ID of the task to retrieve runs for. - in: path name: runID schema: type: string required: true - description: A task run ID. Specifies the run to retrieve. + description: The ID of the run to retrieve. responses: '200': description: Success. The response body contains the task run. @@ -7410,7 +7397,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - Use this endpoint to cancel a running task. + Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud @@ -7422,18 +7409,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to - to cancel. + description: The ID of the task to cancel. - in: path name: runID schema: type: string required: true - description: | - A task run ID. - Specifies the task run to cancel. + description: The ID of the task run to cancel. responses: '204': description: | @@ -7475,15 +7457,15 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to - retry and then returns the scheduled run. + 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 - - Queuing a task run requires that the task's `status` property be set to `active`. + - The task must be _active_ (`status: "active"`). requestBody: content: application/json; charset=utf-8: @@ -7497,15 +7479,15 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that the task run belongs to. + 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 run ID. + 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 @@ -7563,12 +7545,12 @@ paths: operationId: GetTasksIDLogs tags: - Tasks - summary: List logs for a task + summary: Retrieve all logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - When a task runs, InfluxDB creates a `run` record in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. + 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. @@ -7579,12 +7561,11 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve logs for.' + description: The task ID. responses: '200': description: | - Success. - The response body contains an `events` list with logs for the task. + 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: @@ -7593,7 +7574,7 @@ paths: $ref: '#/components/schemas/Logs' examples: taskSuccess: - summary: Events for a successful task run + summary: Events for a successful task run. value: events: - runID: 09b070dadaa7d000 @@ -7603,7 +7584,7 @@ paths: time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: - summary: Events for a failed task run + summary: Events for a failed task run. value: events: - runID: 09a946fc3167d000 @@ -7630,12 +7611,12 @@ paths: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: List logs for a run + summary: Retrieve all logs for a run description: | - Lists all logs for a task run. + 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7643,13 +7624,13 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that the run belongs to.' + description: The ID of the task to get logs for. - in: path name: runID schema: type: string required: true - description: A run ID. Specifies the task run to list logs for. + description: The ID of the run to get logs for. responses: '200': description: | @@ -7701,12 +7682,9 @@ paths: - Tasks summary: List labels for a task description: | - Lists all labels for a task. + Retrieves a list of all labels for a task. - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Labels may be used for grouping and filtering tasks. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7714,9 +7692,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the task to retrieve labels for. + 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. @@ -7740,12 +7716,9 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Adds a label to a task. - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + 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 @@ -7753,12 +7726,9 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to label. + description: The ID of the task to label. requestBody: - description: | - In the request body, provide an object that specifies the label. + description: An object that contains a _`labelID`_ to add to the task. required: true content: application/json: @@ -7766,7 +7736,7 @@ paths: $ref: '#/components/schemas/LabelMapping' responses: '201': - description: Success. The response body contains the label. + description: Success. The response body contains a list of all labels for the task. content: application/json: schema: @@ -7788,7 +7758,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Deletes a label from a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7796,17 +7766,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete the label from. + description: The ID of the task to delete the label from. - in: path name: labelID schema: type: string required: true - description: | - A label ID. - Specifies the label to delete. + description: The ID of the label to delete. responses: '204': description: Success. The label is deleted. @@ -7837,7 +7803,7 @@ paths: 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). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/cloud/influxdb/v2.4/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. @@ -7846,7 +7812,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7977,9 +7943,7 @@ paths: 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). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7987,16 +7951,12 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve members for. + description: The task ID. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -8015,10 +7975,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and then returns - the member. + Adds a user to members of a task and returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8026,12 +7985,9 @@ paths: schema: type: string required: true - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task for the member. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as a member of the task. required: true content: application/json: @@ -8039,10 +7995,7 @@ paths: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. + description: Created. The user is added to task members. content: application/json: schema: @@ -8062,9 +8015,7 @@ paths: 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). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8072,16 +8023,16 @@ paths: schema: type: string required: true - description: A user ID. Specifies the member to remove. + description: The ID of the member to remove. - in: path name: taskID schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to remove the member from.' + description: The task ID. responses: '204': - description: Success. The member is removed. + description: Member removed default: description: Unexpected error content: @@ -8097,9 +8048,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `owner` role for the specified task. + Retrieves all users that have owner permission for a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8107,7 +8058,7 @@ paths: schema: type: string required: true - description: A task ID. Specifies the task to retrieve owners for. + description: The ID of the task to retrieve owners for. responses: '200': description: | @@ -8149,10 +8100,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to owners of the specified task and then returns the - owner. + 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. @@ -8163,12 +8113,9 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) for the owner. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as an owner of the task. required: true content: application/json: @@ -8226,9 +8173,7 @@ paths: 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. - - Removes an owner from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8236,18 +8181,16 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task).' + description: The ID of the owner to remove. - in: path name: taskID schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to remove the owner from. + description: The task ID. responses: '204': - description: Success. The owner is removed. + description: Owner removed default: description: Unexpected error content: @@ -9342,711 +9285,585 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - /authorizations: + /users: get: - operationId: GetAuthorizations + operationId: GetUsers tags: - - Authorizations (API tokens) - Security and access endpoints - summary: List authorizations + - Users + summary: List users description: | - Lists authorizations. + Lists [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - To limit which authorizations are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all authorizations. + To limit which users are returned, pass query parameters in your request. #### 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. + - InfluxDB Cloud doesn't allow listing all users through the API. + Use the InfluxDB Cloud user interface (UI) to manage account information. - #### Required permissions + #### Required permissions for InfluxDB Cloud - To retrieve an authorization, the request must use an API token that has the - following permissions: + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | List all users | Operator token | InfluxData internal use only | + | List a specific user | `read-users` or `read-user USER_ID` | - - `read-authorizations` - - `read-user` for the user that the authorization is scoped to + *`USER_ID`* is the ID of the user that you want to retrieve. #### Related guides - - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) + - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) 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 + name: name 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). + Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). - in: query - name: token + name: id 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. + A user id. + Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). 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. + Success. The response contains a list of `users`. - #### InfluxDB OSS + #### InfluxDB Cloud - - **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. + - 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/Authorizations' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' + $ref: '#/components/schemas/Users' '401': - $ref: '#/components/responses/AuthorizationError' + 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: PostAuthorizations + operationId: PostUsers tags: - - Authorizations (API tokens) - - Security and access endpoints - summary: Create an authorization + - Users + summary: Create a user 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. + (InfluxData internal use only) - - 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. + Creates and returns a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) + that can access InfluxDB. - We recommend the following for managing your tokens: + #### InfluxDB Cloud - - Create a generic user to create and manage tokens for writing data. - - Store your tokens in a secure password vault for future access. + - InfluxDB Cloud Doesn't let you manage users through the API. + Use the InfluxDB Cloud user interface (UI) to manage account information. - #### Required permissions + #### Required permissions for InfluxDB Cloud - - `write-authorizations` - - `write-user` for the user that the authorization is scoped to + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | Create user | Operator token | InfluxData internal use only | #### Related guides - - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) + - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: The authorization to create. + description: 'In the request body, provide the user.' 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' + $ref: '#/components/schemas/User' responses: '201': description: | - Success. The authorization is created. The response body contains the - authorization. + Success. + The response body contains the user. content: application/json: schema: - $ref: '#/components/schemas/Authorization' - '400': - description: Invalid request - $ref: '#/components/responses/GeneralServerError' + $ref: '#/components/schemas/UserResponse' '401': - $ref: '#/components/responses/AuthorizationError' + 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' - '/authorizations/{authID}': + '/users/{userID}': get: - operationId: GetAuthorizationsID + operationId: GetUsersID tags: - - Authorizations (API tokens) - - Security and access endpoints - summary: Retrieve an authorization + - Users + summary: Retrieve a user 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. + Retrieves a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). #### 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 + - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path - name: authID + name: userID schema: type: string required: true - description: An authorization ID. Specifies the authorization to retrieve. + 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 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. + description: Success. The response body contains the user. 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' + $ref: '#/components/schemas/UserResponse' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' patch: - operationId: PatchAuthorizationsID + operationId: PatchUsersID tags: - - Authorizations (API tokens) - - Security and access endpoints - summary: Update an API token to be active or inactive + - Users + summary: Update a user description: | - Updates an authorization. + (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 | - Use this endpoint to set an API token's status to be _active_ or _inactive_. - InfluxDB rejects requests that use inactive API tokens. + #### Related guides + + - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) requestBody: - description: 'In the request body, provide the authorization properties to update.' + description: The user update to apply. required: true content: application/json: schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' + $ref: '#/components/schemas/User' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path - name: authID + name: userID schema: type: string required: true - description: An authorization ID. Specifies the authorization to update. + 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 authorization. + description: Success. The response body contains the updated user. 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. + $ref: '#/components/schemas/UserResponse' '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 + $ref: '#/components/responses/BadRequestError' '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 + $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: - description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /users: - get: - operationId: GetUsers + delete: + operationId: DeleteUsersID tags: - - Security and access endpoints - Users - summary: List users + summary: Delete a user description: | - Lists [users](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + (InfluxData internal use only) - To limit which users are returned, pass query parameters in your request. + 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 - - InfluxDB Cloud doesn't allow listing all users through the API. + - 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 + #### Required permissions | 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. + | 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: 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 + - in: path + name: userID schema: type: string + required: true description: | - A user id. - Only lists the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + A user ID. + Deletes 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' + '204': + description: Success. The user is deleted. + '400': + $ref: '#/components/responses/BadRequestError' '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' + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: - description: Unexpected error $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: PostUsers + operationId: PostSetup 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/) + - 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: 'In the request body, provide the user.' + description: Source to create required: true content: application/json: schema: - $ref: '#/components/schemas/User' + $ref: '#/components/schemas/OnboardingRequest' 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. + description: 'The created default user, bucket, and organization' content: application/json: schema: - $ref: '#/components/schemas/Error' - '500': - $ref: '#/components/responses/InternalServerError' + $ref: '#/components/schemas/OnboardingResponse' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - '/users/{userID}': - get: - operationId: GetUsersID + /setup/user: + post: + operationId: PostSetupUser 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). + - 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: - '200': - description: Success. The response body contains the user. + '201': + description: 'The created default user, bucket, and organization.' content: application/json: schema: - $ref: '#/components/schemas/UserResponse' + $ref: '#/components/schemas/OnboardingResponse' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - patch: - operationId: PatchUsersID + /authorizations: + get: + operationId: GetAuthorizations tags: - - Users - summary: Update a user + - Authorizations + summary: List authorizations description: | - (InfluxData internal use only) + Lists authorizations. - Updates a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) and returns the user. + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations for the organization. #### InfluxDB Cloud - - Doesn't let you manage users through the API. - Use the InfluxDB Cloud user interface (UI) to manage account information. + - 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 for InfluxDB Cloud + #### Required permissions - | Action | Permission required | Restriction | - |:-------|:--------------------|:------------| - | Update user | Operator token | InfluxData internal use only | + - `read-authorizations` #### 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' + - [View tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/) parameters: - $ref: '#/components/parameters/TraceSpan' - - in: path + - in: query name: userID schema: type: string - required: true description: | A user ID. - Updates the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + 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. + Returns the authorization for the specified token. responses: '200': - description: Success. The response body contains the updated user. + description: Success. The response body contains a list of authorizations. content: application/json: schema: - $ref: '#/components/schemas/UserResponse' + $ref: '#/components/schemas/Authorizations' '400': - $ref: '#/components/responses/BadRequestError' + description: Invalid request + $ref: '#/components/responses/GeneralServerError' '401': $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: + description: Unexpected error $ref: '#/components/responses/GeneralServerError' - delete: - operationId: DeleteUsersID + post: + operationId: PostAuthorizations tags: - - Users - summary: Delete a user + - Authorizations + summary: Create an authorization description: | - (InfluxData internal use only) + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#token). - Deletes a [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + 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. - For security purposes, once an InfluxDB user account is deleted from an - organization, the user (and their token) cannot be reactivated. + #### Limitations - #### InfluxDB Cloud + To follow best practices for secure API token generation and retrieval, + InfluxDB Cloud enforces access restrictions on API tokens. - - Doesn't let you manage users through the API. - Use the InfluxDB Cloud user interface (UI) to manage account information. + - InfluxDB only allows access to the API token value immediately after the authorization is created. + - You can't update an authorization's permissions. + - A token stops working when the user who created the authorization is deleted. - #### Required permissions + We recommend the following for managing your tokens: - | Action | Permission required | Restriction | - |:-------|:--------------------|:------------| - | Delete user | Operator token | InfluxData internal use only | + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. #### Related guides - - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) + - [Create a token](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/) 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). + 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: - '204': - description: Success. The user is deleted. + '201': + description: | + Success. The authorization is created. The response body contains the authorization. + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' '400': - $ref: '#/components/responses/BadRequestError' + description: Invalid request + $ref: '#/components/responses/GeneralServerError' '401': $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' '500': $ref: '#/components/responses/InternalServerError' default: + description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /setup: + '/authorizations/{authID}': get: - operationId: GetSetup + operationId: GetAuthorizationsID tags: - - Setup - summary: Retrieve setup status - description: 'Check if setup is allowed. Returns `true` if no default user, organization, or bucket have been created.' + - Authorizations + summary: Retrieve an authorization parameters: - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to get. responses: '200': - description: 'Setup is allowed, true or false' + description: Authorization details content: application/json: schema: - $ref: '#/components/schemas/IsOnboarding' - post: - operationId: PostSetup + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID 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' + - Authorizations + summary: Update authorization status + description: Update an authorization's status to `active` or `inactive`. requestBody: - description: Source to create + description: The updated Authorization object. required: true content: application/json: schema: - $ref: '#/components/schemas/OnboardingRequest' + $ref: '#/components/schemas/AuthorizationUpdateRequest' + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to update. responses: - '201': - description: 'The created default user, bucket, and organization' + '200': + description: The updated authorization. content: application/json: schema: - $ref: '#/components/schemas/OnboardingResponse' + $ref: '#/components/schemas/Authorization' default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' - /setup/user: - post: - operationId: PostSetupUser + delete: + operationId: DeleteAuthorizationsID 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' + - Authorizations + summary: Delete an authorization + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to delete. responses: - '201': - description: 'The created default user, bucket, and organization.' - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse' + '204': + description: Authorization deleted default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' @@ -10802,23 +10619,19 @@ paths: tags: - Data I/O endpoints - Tasks - summary: List tasks + summary: List all tasks description: | - Lists [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + 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`. - - #### Related guide - - - [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/cloud/process-data/) parameters: - $ref: '#/components/parameters/TraceSpan' - in: query name: name description: | - A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) with the specified name. + 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 @@ -10827,29 +10640,29 @@ paths: schema: type: string description: | - A task ID. - Only returns [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) created after the specified task. + 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 ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + 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 name. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + 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 ID. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + 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: @@ -10858,8 +10671,8 @@ paths: - active - inactive description: | - A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that have the specified status. + 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: @@ -10892,11 +10705,8 @@ paths: - in: query name: sortBy description: | - The sort field. - Specifies the task property used to sort records in the list. - Default is `name`. - - The parameter has one supported value: `name`. + The sort field. Only `name` is supported. + Specifies the field used to sort records in the list. required: false schema: type: string @@ -10905,13 +10715,11 @@ paths: - in: query name: type description: | - A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) in the response. + 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, set the `type` parameter to `basic` (`type=basic`) - to omit some task properties (`flux`, `createdAt`, `updatedAt`). + To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). required: false schema: default: '' @@ -10922,8 +10730,8 @@ paths: - in: query name: scriptID description: | - A script ID. - Only returns tasks that use the specified [invokable script](#tag/Invokable-Scripts). + A [script](#tag/Invokable-Scripts) ID. + Only returns tasks that use the specified invokable script. schema: type: string responses: @@ -11022,7 +10830,52 @@ paths: 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 script. + 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 @@ -11033,41 +10886,15 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: | - In the request body, provide the task. - - Set one of the following properties to provide the script that the task runs: - - `flux` - - `scriptID` - - If you set the `scriptID` property, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, you must provide the `task` configuration option - in the Flux script. - - See [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't use `flux` and `scriptID` in the same task. + description: The task to create required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' responses: '201': - description: Success. The response body contains a `tasks` list with the task. + description: Success. The response body contains a `tasks` list with the new task. content: application/json: schema: @@ -11079,10 +10906,8 @@ paths: #### InfluxDB Cloud - - Returns this error if the task doesn't contain the `flux` property - or the `scriptID` property. - - Returns this error if the task contains `flux` _and_ `scriptID` - properties. + - 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: @@ -11108,6 +10933,44 @@ paths: 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 @@ -11116,7 +10979,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -11125,8 +10988,8 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve. + 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. @@ -11150,52 +11013,67 @@ paths: - Tasks summary: Update a task description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), + 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. - The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. - #### Related guides + #### InfluxDB Cloud - - [Update a task](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - requestBody: - description: | - In the request body, provide the task properties to update. - To provide the script that the task runs, - set either the `flux` property or the `scriptID` property. + - Use either `flux` or `scriptID` to provide the task script. - If you set `scriptID`, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` + - `flux`: a string of "raw" Flux that contains task options and the script--for example: - If you set the `flux` property, provide the `task` configuration option - in the Flux script. + ```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" + } + ``` - See [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - for detail and examples. + - `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: + #### Limitations: - - You can't set `flux` and `scriptID` properties for the same task--for - example, if you set the `scriptID` property, then InfluxDB sets the `flux` property - to an empty string (`""`). + - 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' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -11204,8 +11082,8 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to update. + 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. @@ -11229,13 +11107,12 @@ paths: - Tasks summary: Delete a task description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + 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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` - property to `inactive`. + 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 @@ -11243,9 +11120,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete. + 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. @@ -12031,7 +11906,7 @@ components: AuthorizationUpdateRequest: properties: status: - description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' default: active type: string enum: @@ -12272,7 +12147,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -13588,44 +13463,6 @@ components: Default is the server _now_ time. type: string format: date-time - TaskCron: - 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 - format: cron - TaskDescription: - description: A description of the task. - type: string - TaskEvery: - 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 - TaskFlux: - description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - type: string - format: Flux - TaskName: - description: The name of the task. - type: string - TaskOffset: - 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 - TaskOrg: - description: | - An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. - type: string - TaskOrgID: - description: | - An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. - type: string TaskStatusType: type: string enum: @@ -17287,25 +17124,31 @@ components: id: readOnly: true type: string - description: | - The resource ID that InfluxDB uses to uniquely identify the task. orgID: - $ref: '#/components/schemas/TaskOrgID' + description: | + An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: | + An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string name: - $ref: '#/components/schemas/TaskName' - description: - $ref: '#/components/schemas/TaskDescription' + description: The name of the task. + type: string ownerID: description: | - A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the task. + A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + 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: @@ -17313,20 +17156,31 @@ components: authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + 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: - $ref: '#/components/schemas/TaskFlux' + 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: - $ref: '#/components/schemas/TaskEvery' + 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: - $ref: '#/components/schemas/TaskCron' + 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: - $ref: '#/components/schemas/TaskOffset' + 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 @@ -17374,9 +17228,30 @@ components: labels: $ref: '#/components/schemas/Link' scriptID: - $ref: '#/components/schemas/TaskScriptID' + 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: - $ref: '#/components/schemas/TaskScriptParameters' + 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 @@ -17385,74 +17260,85 @@ components: type: object properties: orgID: - $ref: '#/components/schemas/TaskOrgID' + description: The ID of the organization that owns the task. + type: string org: - $ref: '#/components/schemas/TaskOrg' - name: - $ref: '#/components/schemas/TaskName' - description: - $ref: '#/components/schemas/TaskDescription' - every: - $ref: '#/components/schemas/TaskEvery' - cron: - $ref: '#/components/schemas/TaskCron' - offset: - $ref: '#/components/schemas/TaskOffset' + description: The name of the organization that owns the task. + type: string status: $ref: '#/components/schemas/TaskStatusType' flux: - $ref: '#/components/schemas/TaskFlux' - scriptID: - $ref: '#/components/schemas/TaskScriptID' - scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' - TaskScriptID: - description: | - A script ID. - Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. + description: | + The Flux script that the task runs. - #### Related guides + #### Limitations - - [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 - TaskScriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified - by the `scriptID` property. - When running the task, InfluxDB executes the script with the parameters - you provide. + - 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 + #### Limitations - - To use the `scriptParameters` property, you must also set the `scriptID` property - for the task. + - 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. - #### Related guides + #### Limitations - - [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: object + - `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: - $ref: '#/components/schemas/TaskName' - description: - $ref: '#/components/schemas/TaskDescription' + description: Update the 'name' option in the flux script. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: Update the 'every' option in the flux script. + type: string cron: - $ref: '#/components/schemas/TaskCron' + description: Update the 'cron' option in the flux script. + type: string offset: - $ref: '#/components/schemas/TaskOffset' - flux: - $ref: '#/components/schemas/TaskFlux' + description: Update the 'offset' option in the flux script. + type: string + description: + description: Update the description of the task. + type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + description: Update the 'scriptID' of the task. + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + description: Update the 'scriptParameters' of the task. + type: object responses: AuthorizationError: description: | @@ -17582,7 +17468,7 @@ components: 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\")" + 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: @@ -17634,7 +17520,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides diff --git a/contracts/common.yml b/contracts/common.yml index 3ee47f904..bb42f5f28 100644 --- a/contracts/common.yml +++ b/contracts/common.yml @@ -5057,7 +5057,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5073,7 +5073,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5138,7 +5138,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5153,7 +5153,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5239,7 +5239,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5255,7 +5255,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5733,7 +5733,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5830,7 +5830,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5930,7 +5930,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5991,7 +5991,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -6052,7 +6052,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -6062,7 +6062,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6137,7 +6137,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6152,7 +6152,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6925,11 +6925,10 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). + Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. - If you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6938,14 +6937,13 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to list runs for. + 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 the specified run. + description: A task run ID. Only returns runs created after this run. - in: query name: limit schema: @@ -6962,7 +6960,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. + Only returns runs scheduled after this time. - in: query name: beforeTime schema: @@ -6970,7 +6968,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. + Only returns runs scheduled before this time. responses: '200': description: Success. The response body contains the list of task runs. @@ -6999,10 +6997,6 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7010,10 +7004,6 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to run. requestBody: content: application/json: @@ -7026,18 +7016,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Run' - '400': - description: Bad request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -7051,7 +7029,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -7061,16 +7039,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - that the task run belongs to. + description: The ID of the task to retrieve runs for. - in: path name: runID schema: type: string required: true - description: A task run ID. Specifies the run to retrieve. + description: The ID of the run to retrieve. responses: '200': description: Success. The response body contains the task run. @@ -7119,7 +7094,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). - Use this endpoint to cancel a running task. + Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud @@ -7131,18 +7106,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to cancel. + description: The ID of the task to cancel. - in: path name: runID schema: type: string required: true - description: | - A task run ID. - Specifies the task run to cancel. + description: The ID of the task run to cancel. responses: '204': description: | @@ -7184,15 +7154,15 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to - retry and then returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/latest/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 - - Queuing a task run requires that the task's `status` property be set to `active`. + - The task must be _active_ (`status: "active"`). requestBody: content: application/json; charset=utf-8: @@ -7206,15 +7176,15 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. + Specifies the task to retry. - in: path name: runID schema: type: string required: true description: | - A task run ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the @@ -7272,12 +7242,12 @@ paths: operationId: GetTasksIDLogs tags: - Tasks - summary: List logs for a task + summary: Retrieve all logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). - When a task runs, InfluxDB creates a `run` record in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. + 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. @@ -7288,12 +7258,11 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for.' + description: The task ID. responses: '200': description: | - Success. - The response body contains an `events` list with logs for the task. + 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: @@ -7302,7 +7271,7 @@ paths: $ref: '#/components/schemas/Logs' examples: taskSuccess: - summary: Events for a successful task run + summary: Events for a successful task run. value: events: - runID: 09b070dadaa7d000 @@ -7312,7 +7281,7 @@ paths: time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: - summary: Events for a failed task run + summary: Events for a failed task run. value: events: - runID: 09a946fc3167d000 @@ -7339,12 +7308,12 @@ paths: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: List logs for a run + summary: Retrieve all logs for a run description: | - Lists all logs for a task run. + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7352,13 +7321,13 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to.' + description: The ID of the task to get logs for. - in: path name: runID schema: type: string required: true - description: A run ID. Specifies the task run to list logs for. + description: The ID of the run to get logs for. responses: '200': description: | @@ -7410,12 +7379,9 @@ paths: - Tasks summary: List labels for a task description: | - Lists all labels for a task. + Retrieves a list of all labels for a task. - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Labels may be used for grouping and filtering tasks. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7423,9 +7389,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the task to retrieve labels for. + 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. @@ -7449,12 +7413,9 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Adds a label to a task. - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + 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 @@ -7462,12 +7423,9 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. + description: The ID of the task to label. requestBody: - description: | - In the request body, provide an object that specifies the label. + description: An object that contains a _`labelID`_ to add to the task. required: true content: application/json: @@ -7475,7 +7433,7 @@ paths: $ref: '#/components/schemas/LabelMapping' responses: '201': - description: Success. The response body contains the label. + description: Success. The response body contains a list of all labels for the task. content: application/json: schema: @@ -7497,7 +7455,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Deletes a label from a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7505,17 +7463,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. + description: The ID of the task to delete the label from. - in: path name: labelID schema: type: string required: true - description: | - A label ID. - Specifies the label to delete. + description: The ID of the label to delete. responses: '204': description: Success. The label is deleted. @@ -7546,7 +7500,7 @@ paths: 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/latest/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -7555,7 +7509,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7686,9 +7640,7 @@ paths: 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/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7696,16 +7648,12 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. + description: The task ID. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -7724,10 +7672,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns - the member. + Adds a user to members of a task and returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7735,12 +7682,9 @@ paths: schema: type: string required: true - description: | - A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. - Specifies the task for the member. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as a member of the task. required: true content: application/json: @@ -7748,10 +7692,7 @@ paths: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. + description: Created. The user is added to task members. content: application/json: schema: @@ -7771,9 +7712,7 @@ paths: 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/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7781,16 +7720,16 @@ paths: schema: type: string required: true - description: A user ID. Specifies the member to remove. + description: The ID of the member to remove. - in: path name: taskID schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from.' + description: The task ID. responses: '204': - description: Success. The member is removed. + description: Member removed default: description: Unexpected error content: @@ -7806,9 +7745,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `owner` role for the specified task. + Retrieves all users that have owner permission for a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7816,7 +7755,7 @@ paths: schema: type: string required: true - description: A task ID. Specifies the task to retrieve owners for. + description: The ID of the task to retrieve owners for. responses: '200': description: | @@ -7858,10 +7797,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to owners of the specified task and then returns the - owner. + 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. @@ -7872,12 +7810,9 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as an owner of the task. required: true content: application/json: @@ -7935,9 +7870,7 @@ paths: 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. - - Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7945,18 +7878,16 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task).' + description: The ID of the owner to remove. - in: path name: taskID schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. + description: The task ID. responses: '204': - description: Success. The owner is removed. + description: Owner removed default: description: Unexpected error content: @@ -9051,379 +8982,6 @@ paths: 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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token](https://docs.influxdata.com/influxdb/latest/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/latest/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/latest/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/latest/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: - 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 - 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/latest/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/latest/security/tokens/view-tokens/) - externalDocs: - url: 'https://docs.influxdata.com/influxdb/latest/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' components: parameters: TraceSpan: @@ -10196,7 +9754,7 @@ components: AuthorizationUpdateRequest: properties: status: - description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' default: active type: string enum: @@ -10437,7 +9995,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -11753,44 +11311,6 @@ components: Default is the server _now_ time. type: string format: date-time - TaskCron: - 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 - format: cron - TaskDescription: - description: A description of the task. - type: string - TaskEvery: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/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 - TaskFlux: - description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) - type: string - format: Flux - TaskName: - description: The name of the task. - type: string - TaskOffset: - 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 - TaskOrg: - description: | - An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. - type: string - TaskOrgID: - description: | - An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. - type: string TaskStatusType: type: string enum: diff --git a/contracts/legacy.yml b/contracts/legacy.yml index 591ceb189..36c031482 100644 --- a/contracts/legacy.yml +++ b/contracts/legacy.yml @@ -520,18 +520,18 @@ components: properties: orgID: type: string - description: The organization ID. Identifies the organization that the authorization is scoped to. + description: The ID of the organization that the authorization is scoped to. userID: type: string - description: The user ID. Identifies the user that the authorization is scoped to. + description: The ID of the user that the authorization is scoped to. token: type: string - description: The name that you provide for the authorization. + description: A name that you provide for the authorization. permissions: type: array minItems: 1 description: | - The list of permissions that provide `read` and `write` access to organization resources. + A list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' @@ -653,7 +653,7 @@ components: AuthorizationUpdateRequest: properties: status: - description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' default: active type: string enum: diff --git a/contracts/oss-diff.yml b/contracts/oss-diff.yml index a49023825..a2d636352 100644 --- a/contracts/oss-diff.yml +++ b/contracts/oss-diff.yml @@ -1341,6 +1341,332 @@ paths: default: description: Unexpected error $ref: '#/paths/~1config/get/responses/401' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - 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 OSS + + - InfluxDB OSS returns + [API token]({{% INFLUXDB_DOCS_URL %}}/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. + + #### Required permissions + + - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. + + #### Related guides + + - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) + parameters: + - $ref: '#/paths/~1ready/get/parameters/0' + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: 'An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).' + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + responses: + '200': + description: Success. The response body contains a list of authorizations. + content: + application/json: + schema: + type: object + properties: + links: + readOnly: true + $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' + authorizations: + type: array + items: + $ref: '#/components/schemas/OnboardingResponse/properties/auth' + '400': + description: Invalid request + $ref: '#/paths/~1config/get/responses/401' + '401': + $ref: '#/paths/~1tasks/get/responses/401' + '500': + $ref: '#/paths/~1users/get/responses/500' + default: + description: Unexpected error + $ref: '#/paths/~1config/get/responses/401' + post: + operationId: PostAuthorizations + tags: + - Authorizations + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token]({{% INFLUXDB_DOCS_URL %}}/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 response contains the new authorization with the generated API token. + + #### Limitations + + To follow best practices for secure API token generation and retrieval, + InfluxDB enforces access restrictions on API tokens. + + - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any + user with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_. + - You can't update an authorization's permissions. + - Even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + - A token stops working when the user who created the authorization is deleted. + + We recommend creating a generic user to create and manage tokens for writing data. + + #### Related guides + + - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) + parameters: + - $ref: '#/paths/~1ready/get/parameters/0' + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + required: + - orgID + - permissions + allOf: + - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' + - 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: + required: + - action + - resource + properties: + action: + type: string + enum: + - read + - write + 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. + 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/OnboardingResponse/properties/auth' + '400': + description: Invalid request + $ref: '#/paths/~1config/get/responses/401' + '401': + $ref: '#/paths/~1tasks/get/responses/401' + '500': + $ref: '#/paths/~1users/get/responses/500' + default: + description: Unexpected error + $ref: '#/paths/~1config/get/responses/401' + '/authorizations/{authID}': + get: + operationId: GetAuthorizationsID + tags: + - Authorizations + - Security and access endpoints + summary: Retrieve an authorization + parameters: + - $ref: '#/paths/~1ready/get/parameters/0' + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to get. + responses: + '200': + description: Authorization details + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingResponse/properties/auth' + default: + description: Unexpected error + $ref: '#/paths/~1config/get/responses/401' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + summary: Update an authorization to be active or inactive + requestBody: + description: Authorization to update + required: true + content: + application/json: + schema: + properties: + status: + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' + default: active + type: string + enum: + - active + - inactive + description: + type: string + description: A description of the token. + parameters: + - $ref: '#/paths/~1ready/get/parameters/0' + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to update. + responses: + '200': + description: The active or inactive authorization + content: + application/json: + schema: + $ref: '#/components/schemas/OnboardingResponse/properties/auth' + default: + description: Unexpected error + $ref: '#/paths/~1config/get/responses/401' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + summary: Delete an authorization + parameters: + - $ref: '#/paths/~1ready/get/parameters/0' + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to delete. + responses: + '204': + description: Authorization deleted + default: + description: Unexpected error + $ref: '#/paths/~1config/get/responses/401' /variables: get: operationId: GetVariables @@ -1904,7 +2230,7 @@ paths: type: object properties: labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' links: $ref: '#/paths/~1dashboards/get/responses/200/content/application~1json/schema/properties/links' default: @@ -2959,17 +3285,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' cells: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' org: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -3012,7 +3338,7 @@ paths: type: string description: The reference to a view from the views API. labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' - type: object allOf: - $ref: '#/paths/~1dashboards/post/requestBody/content/application~1json/schema' @@ -3029,17 +3355,17 @@ paths: org: /api/v2/labels/1 properties: self: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' cells: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' org: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -3777,7 +4103,7 @@ paths: readOnly: true type: string labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' links: type: object readOnly: true @@ -3790,19 +4116,19 @@ paths: properties: self: description: The URL for this check. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: description: The URL to retrieve labels for this check. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: description: The URL to retrieve members for this check. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: description: The URL to retrieve owners for this check. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' query: description: The URL to retrieve the Flux script for this check. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' required: - name - orgID @@ -4621,7 +4947,7 @@ paths: items: $ref: '#/paths/~1dashboards/post/responses/201/content/application~1json/schema/oneOf/1/allOf/1/properties/cells/items/allOf/1/properties/properties/oneOf/0/properties/colors/items' labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' default: description: Unexpected error content: @@ -4703,11 +5029,11 @@ paths: URI pointers for additional paged results. properties: next: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' self: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' prev: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' required: - self dashboards: @@ -4728,7 +5054,7 @@ paths: - Tasks summary: List tasks description: | - Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/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`. @@ -4741,9 +5067,8 @@ paths: - in: query name: name description: | - A task name. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - that have the specified name. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. schema: type: string @@ -4752,30 +5077,29 @@ paths: schema: type: string description: | - A task ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Only returns tasks created after the specified task. - in: query name: user schema: type: string description: | - A user ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. - in: query name: org schema: type: string description: | - An organization name. - Only returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. - in: query name: orgID schema: type: string description: | - An organization ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. - in: query name: status schema: @@ -4784,8 +5108,8 @@ paths: - active - inactive description: | - A task status. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). - in: query name: limit schema: @@ -4803,9 +5127,9 @@ paths: - in: query name: type description: | - A task type. - Specifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response. + A [task]({{% INFLUXDB_DOCS_URL %}}/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 @@ -4935,9 +5259,7 @@ paths: - Tasks summary: Create a task description: | - Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a script. + Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. #### Related guides @@ -4948,20 +5270,12 @@ paths: parameters: - $ref: '#/paths/~1ready/get/parameters/0' requestBody: - description: | - In the request body, provide the task. - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. + description: The task to create. required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' responses: '201': description: Success. The response body contains a `tasks` list with the task. @@ -4983,12 +5297,12 @@ paths: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' examples: orgProvidedNotFound: - summary: The organization specified by org or orgID doesn't own the token passed in the header + 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' missingFluxError: - summary: The request body doesn't contain a Flux query + summary: Task in request body is missing Flux query value: code: invalid message: 'failed to decode request: missing flux' @@ -5002,6 +5316,24 @@ paths: application/json: schema: $ref: '#/paths/~1users/get/responses/401/content/application~1json/schema' + x-codeSamples: + - lang: Shell + label: 'cURL: create a task' + source: | + curl http://localhost:8086/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 '/tasks/{taskID}': get: operationId: GetTasksID @@ -5010,7 +5342,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: '#/paths/~1ready/get/parameters/0' - in: path @@ -5018,9 +5350,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. + description: The ID of the task to retrieve. responses: '200': description: Success. The response body contains the task. @@ -5088,27 +5418,21 @@ paths: - Tasks summary: Update a task description: | - Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), - and then cancels all scheduled runs of the task. + Updates a 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`. + Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - #### Related guides - - - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + 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. requestBody: - description: | - In the request body, provide the task properties to update. + description: An object that contains updated task properties to apply. required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' parameters: - $ref: '#/paths/~1ready/get/parameters/0' - in: path @@ -5116,9 +5440,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)to update. + description: The ID of the task to update. responses: '200': description: Success. The response body contains the updated task. @@ -5142,13 +5464,12 @@ paths: - Tasks summary: Delete a task description: | - Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + Deletes a 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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status - to `inactive`. + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). parameters: - $ref: '#/paths/~1ready/get/parameters/0' - in: path @@ -5156,9 +5477,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. + description: The ID of the task to delete. responses: '204': description: Success. The task and runs are deleted. Scheduled runs are canceled. @@ -5285,21 +5604,21 @@ components: dashboards: /api/v2/dashboards?org=myorg properties: self: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' secrets: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' buckets: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' tasks: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' dashboards: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -5345,22 +5664,22 @@ components: properties: labels: description: The URL to retrieve labels for this bucket. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: description: The URL to retrieve members that can read this bucket. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' org: description: The URL to retrieve parent organization for this bucket. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: description: The URL to retrieve owners that can read and write to this bucket. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' self: description: The URL for this bucket. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' write: description: The URL to write line protocol to this bucket. - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' id: readOnly: true type: string @@ -5438,11 +5757,11 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds labels: - $ref: '#/components/schemas/Variable/properties/labels' + $ref: '#/components/schemas/Task/properties/labels' required: - name - retentionRules @@ -5451,17 +5770,7 @@ components: - orgID - permissions allOf: - - 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. + - $ref: '#/paths/~1authorizations~1%7BauthID%7D/patch/requestBody/content/application~1json/schema' - type: object properties: createdAt: @@ -5484,72 +5793,7 @@ components: The list of permissions. An authorization must have at least one permission. items: - required: - - action - - resource - properties: - action: - type: string - enum: - - read - - write - 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. + $ref: '#/paths/~1authorizations/post/requestBody/content/application~1json/schema/allOf/1/properties/permissions/items' id: readOnly: true type: string @@ -5592,10 +5836,10 @@ components: properties: self: readOnly: true - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' user: readOnly: true - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' Variable: type: object required: @@ -5630,9 +5874,7 @@ components: items: type: string labels: - type: array - items: - $ref: '#/paths/~1scrapers~1%7BscraperTargetID%7D~1labels/post/responses/201/content/application~1json/schema/properties/label' + $ref: '#/components/schemas/Task/properties/labels' arguments: type: object oneOf: @@ -5831,18 +6073,15 @@ components: organization: /api/v2/orgs/1 properties: self: - type: string - format: uri - readOnly: true - description: URI of resource. + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' owners: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' bucket: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' organization: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' ScraperTargetResponses: type: object properties: @@ -6228,33 +6467,31 @@ components: id: readOnly: true type: string - description: | - The resource ID that InfluxDB uses to uniquely identify the task. orgID: description: | - An organization ID. - Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Specifies the organization that owns the task. type: string org: description: | - An organization name. - Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Specifies the organization that owns the task. type: string name: description: The name of the task. type: string - description: - description: A description of the task. - type: string ownerID: description: | - A user ID. - Identifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task. + A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + 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: type: string enum: @@ -6263,26 +6500,22 @@ components: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. labels: - $ref: '#/components/schemas/Variable/properties/labels' + type: array + items: + $ref: '#/paths/~1scrapers~1%7BscraperTargetID%7D~1labels/post/responses/201/content/application~1json/schema/properties/label' authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + 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: | - Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + description: The Flux script that the task executes. type: string - format: Flux + format: flux every: description: 'The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.' type: string @@ -6290,7 +6523,6 @@ components: 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 - format: cron 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 @@ -6330,17 +6562,20 @@ components: logs: /api/v2/tasks/1/logs properties: self: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + type: string + format: uri + readOnly: true + description: URI of resource. owners: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' members: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' runs: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' logs: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' labels: - $ref: '#/components/schemas/ScraperTargetResponse/allOf/1/properties/links/properties/self' + $ref: '#/components/schemas/Task/properties/links/properties/self' required: - id - name @@ -6350,17 +6585,19 @@ components: type: object properties: orgID: - $ref: '#/components/schemas/Task/properties/orgID' + description: The ID of the organization that owns this Task. + type: string org: - $ref: '#/components/schemas/Task/properties/org' - name: - $ref: '#/components/schemas/Task/properties/name' - description: - $ref: '#/components/schemas/Task/properties/description' - flux: - $ref: '#/components/schemas/Task/properties/flux' + description: The name of the organization that owns this Task. + type: string status: $ref: '#/components/schemas/Task/properties/status' + flux: + description: The Flux script to run for this task. + type: string + description: + description: An optional description of the task. + type: string required: - flux TaskUpdateRequest: @@ -6369,17 +6606,23 @@ components: status: $ref: '#/components/schemas/Task/properties/status' flux: - $ref: '#/components/schemas/Task/properties/flux' + description: The Flux script that the task runs. + type: string name: - $ref: '#/components/schemas/Task/properties/name' + description: Update the 'name' option in the flux script. + type: string every: - $ref: '#/components/schemas/Task/properties/every' + description: Update the 'every' option in the flux script. + type: string cron: - $ref: '#/components/schemas/Task/properties/cron' + description: Update the 'cron' option in the flux script. + type: string offset: - $ref: '#/components/schemas/Task/properties/offset' + description: Update the 'offset' option in the flux script. + type: string description: - $ref: '#/components/schemas/Task/properties/description' + description: Update the description of the task. + type: string responses: null examples: AuthorizationPostRequest: @@ -6419,7 +6662,7 @@ components: 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\")" + 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. securitySchemes: @@ -6457,7 +6700,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides diff --git a/contracts/oss.json b/contracts/oss.json index c92cdcd14..da5beb286 100644 --- a/contracts/oss.json +++ b/contracts/oss.json @@ -16,8 +16,8 @@ ], "tags": [ { - "name": "Authorizations (API tokens)", - "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" + "name": "Authorizations", + "description": "Create and manage authorizations (API tokens).\n\nAn _authorization_ contains a list of `read` and `write`\npermissions for organization resources and provides an API token for authentication.\nAn authorization belongs to an organization and only contains permissions for that organization.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- InfluxDB allows access to the API token value immediately after the authorization is created.\n- You can’t change access (read/write) permissions for an API token after it’s created.\n- Tokens stop working when the user who created the token is deleted.\n\nAPI tokens are visible to the user who created the authorization and to any\nuser with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_.\nIn InfluxDB OSS, even if an API token has `read-authorizations` permission, the\ntoken can't be used to view its authorization details.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n#### User sessions with authorizations\n\nOptionally, when creating an authorization, you can scope it to a specific user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nFor more information, see [how to assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/).\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related endpoints\n\n- [Signin](#tag/Signin)\n- [Signout](#tag/Signout)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n- [Assign a token to a specific user]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n" }, { "name": "Buckets", @@ -45,15 +45,15 @@ }, { "name": "Tasks", - "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in a `task` object:\n\n\n\n### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n" + "description": "Process and analyze your data with [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nin the InfluxDB task engine.\nUse the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.\n\nTo configure a task, provide the script and the schedule to run the task.\nFor examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks).\n\n\n\n#### Properties\n\nA `task` object contains information about an InfluxDB task resource.\n\nThe following table defines the properties that appear in a `task` object:\n\n\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n" }, { "name": "Templates", - "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for\neverything from dashboards and Telegraf to notifications and alerts.\nUse InfluxDB templates to quickly configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration with the\nInfluxData community.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" + "description": "Export and apply InfluxDB **templates**.\nManage **stacks** of templated InfluxDB resources.\n\nInfluxDB templates are prepackaged configurations for\neverything from dashboards and Telegraf to notifications and alerts.\nUse InfluxDB templates to quickly configure a fresh instance of InfluxDB,\nback up your dashboard configuration, or share your configuration with the\nInfluxData community.\n\nUse the `/api/v2/templates` endpoints to export templates and apply templates.\n\n**InfluxDB stacks** are stateful InfluxDB templates that let you\nadd, update, and remove installed template resources over time, avoid duplicating\nresources when applying the same or similar templates more than once, and\napply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.\n\nUse the `/api/v2/stacks` endpoints to manage installed template resources.\n\n#### Related guides\n\n- [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/)\n- [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/)\n" }, { "name": "Users", - "description": "Manage users for your organization.\nUsers are those with access to InfluxDB.\nTo grant a user permission to access data, add them as a member of an\norganization and provide them with an API token.\n\n### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/)\n- [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)\n" + "description": "Manage users for your organization.\nUsers are those with access to InfluxDB.\nTo grant a user permission to access data, add them as a member of an\norganization and provide them with an API token.\n\n#### User sessions with authorizations\n\nOptionally, you can scope an authorization (and its API token) to a user.\nIf a user signs in with username and password, creating a _user session_,\nthe session carries the permissions granted by all the user's authorizations.\nTo create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/)\n- [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)\n" }, { "name": "Write", @@ -87,7 +87,7 @@ { "name": "Pagination", "x-traitTag": true, - "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n| Query parameter | Value type | Description |\n|:------------------------ |:--------------------- |:-------------------------------------------|\n| `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n| `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n### Limitations\n\n- For specific endpoint parameters and examples, see the endpoint definition.\n- If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" + "description": "Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:\n\n| Query parameter | Value type | Description |\n|:------------------------ |:--------------------- |:-------------------------------------------|\n| `limit` | integer | The maximum number of records to return (after other parameters are applied). |\n| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |\n| `after` | string (resource ID) | Only returns resources created after the specified resource. |\n\n#### Limitations\n\n- For specific endpoint parameters and examples, see the endpoint definition.\n- If you specify an `offset` parameter value greater than the total number of records,\n then InfluxDB returns an empty list in the response\n (given `offset` skips the specified number of records).\n\n The following example passes `offset=50` to skip the first 50 results,\n but the user only has 10 buckets:\n\n ```sh\n curl --request GET \"INFLUX_URL/api/v2/buckets?limit=1&offset=50\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n ```\n\n The response contains the following:\n\n ```json\n {\n \"links\": {\n \"prev\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=49\\u0026orgID=ORG_ID\",\n \"self\": \"/api/v2/buckets?descending=false\\u0026limit=1\\u0026offset=50\\u0026orgID=ORG_ID\"\n },\n \"buckets\": []\n }\n ```\n" }, { "name": "Response codes", @@ -6392,7 +6392,7 @@ "Buckets" ], "summary": "List all owners of a bucket", - "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Lists all [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nof a bucket.\n\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6468,7 +6468,7 @@ "Buckets" ], "summary": "Add an owner to a bucket", - "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Adds an owner to a bucket and returns the [owners]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner)\nwith role and user detail.\n\nUse this endpoint to create a _resource owner_ for the bucket.\nBucket owners have permission to delete buckets and remove user and member\npermissions from the bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add\n an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -6566,7 +6566,7 @@ "Buckets" ], "summary": "Remove an owner from a bucket", - "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", + "description": "Removes an owner from a bucket.\n\nUse this endpoint to remove a user's `owner` role for a bucket.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner\nfrom.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7122,7 +7122,7 @@ "Security and access endpoints" ], "summary": "List all members of an organization", - "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Lists all users that belong to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve\nmembers for.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7223,7 +7223,7 @@ "Organizations" ], "summary": "Add a member to an organization", - "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Add a user to an organization.\n\nInfluxDB [users]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) have\npermission to access InfluxDB.\n\n[Members]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#member) are users\nwithin the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/users/)\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7322,7 +7322,7 @@ "Security and access endpoints" ], "summary": "Remove a member from an organization", - "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", + "description": "Removes a member from an organization.\n\nUse this endpoint to remove a user's member privileges for an organization.\nRemoving member privileges removes the user's `read` and `write` permissions\nfrom the organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Member permissions are separate from API token permissions.\n- Member permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an\nowner from.\n\n#### Related guides\n\n- [Manage members]({{% INFLUXDB_DOCS_URL %}}/organizations/members/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7380,7 +7380,7 @@ "Security and access endpoints" ], "summary": "List all owners of an organization", - "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", + "description": "Lists all owners of an organization.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `read-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a\nlist of owners from.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7454,7 +7454,7 @@ "Organizations" ], "summary": "Add an owner to an organization", - "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", + "description": "Adds an owner to an organization.\n\nUse this endpoint to assign the organization `owner` role to a user.\n\n#### InfluxDB Cloud\n\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for.\n\n#### Related endpoints\n\n- [Authorizations](#tag/Authorizations)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -7544,7 +7544,7 @@ "Security and access endpoints" ], "summary": "Remove an owner from an organization", - "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations-(API-tokens))\n", + "description": "Removes an [owner]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#owner) from\nthe organization.\n\nOrganization owners have permission to delete organizations and remove user and member\npermissions from the organization.\n\n#### InfluxDB Cloud\n- Doesn't use `owner` and `member` roles.\n Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\n#### Limitations\n\n- Owner permissions are separate from API token permissions.\n- Owner permissions are used in the context of the InfluxDB UI.\n\n#### Required permissions\n\n- `write-orgs INFLUX_ORG_ID`\n\n*`INFLUX_ORG_ID`* is the ID of the organization that you want to\nremove an owner from.\n\n#### Related endpoints\n- [Authorizations](#tag/Authorizations)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8438,7 +8438,7 @@ "Tasks" ], "summary": "List runs for a task", - "description": "Lists runs for the specified [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf you don't pass query parameters, InfluxDB returns all runs for the task\nup to the default `limit`.\n", + "description": "Retrieves a list of runs for a [task]({{% INFLUXDB_DOCS_URL %}}/process-data/).\n\nTo limit which task runs are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all task runs up to the default `limit`.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8450,7 +8450,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto list runs for.\n" + "description": "The ID of the task to get runs for.\nOnly returns runs for this task.\n" }, { "in": "query", @@ -8458,7 +8458,7 @@ "schema": { "type": "string" }, - "description": "A task run ID. Only returns runs created after the specified run." + "description": "A task run ID. Only returns runs created after this run." }, { "in": "query", @@ -8478,7 +8478,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after the specified time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled after this time.\n" }, { "in": "query", @@ -8487,7 +8487,7 @@ "type": "string", "format": "date-time" }, - "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before the specified time.\n" + "description": "A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)).\nOnly returns runs scheduled before this time.\n" } ], "responses": { @@ -8519,7 +8519,7 @@ "Tasks" ], "summary": "Start a task run, overriding the schedule", - "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", + "description": "Schedules a task run to start immediately, ignoring scheduled runs.\n\nUse this endpoint to manually start a task run.\nScheduled runs will continue to run as scheduled.\nThis may result in concurrently running tasks.\n\nTo _retry_ a previous run (and avoid creating a new run),\nuse the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8530,8 +8530,7 @@ "schema": { "type": "string" }, - "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto run.\n" + "required": true } ], "requestBody": { @@ -8554,25 +8553,6 @@ } } }, - "400": { - "description": "Bad request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "inactiveTask": { - "summary": "Can't run an inactive task", - "value": { - "code": "invalid", - "message": "failed to force run: inactive task" - } - } - } - } - } - }, "401": { "$ref": "#/components/responses/AuthorizationError" }, @@ -8592,7 +8572,7 @@ "Tasks" ], "summary": "Retrieve a run for a task.", - "description": "Retrieves the specified run for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", + "description": "Retrieves a specific run for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to retrieve detail and logs for a specific task run.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8604,7 +8584,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nthat the task run belongs to.\n" + "description": "The ID of the task to retrieve runs for." }, { "in": "path", @@ -8613,7 +8593,7 @@ "type": "string" }, "required": true, - "description": "A task run ID. Specifies the run to retrieve." + "description": "The ID of the run to retrieve." } ], "responses": { @@ -8682,7 +8662,7 @@ "Tasks" ], "summary": "Cancel a running task", - "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", + "description": "Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint with InfluxDB OSS to cancel a running task.\n\n#### InfluxDB Cloud\n\n- Doesn't support this operation.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8694,7 +8674,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to\nto cancel.\n" + "description": "The ID of the task to cancel." }, { "in": "path", @@ -8703,7 +8683,7 @@ "type": "string" }, "required": true, - "description": "A task run ID.\nSpecifies the task run to cancel.\n" + "description": "The ID of the task run to cancel." } ], "responses": { @@ -8745,7 +8725,7 @@ "Tasks" ], "summary": "Retry a task run", - "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and then returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- Queuing a task run requires that the task's `status` property be set to `active`.\n", + "description": "Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to\nretry and returns the scheduled run.\n\nTo manually start a _new_ task run, use the\n[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).\n\n#### Limitations\n\n- The task must be _active_ (`status: \"active\"`).\n", "requestBody": { "content": { "application/json; charset=utf-8": { @@ -8766,7 +8746,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the task run belongs to.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task to retry.\n" }, { "in": "path", @@ -8775,7 +8755,7 @@ "type": "string" }, "required": true, - "description": "A task run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run ID.\nSpecifies the task run to retry.\n\nTo find a task run ID, use the\n[`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns)\nto list task runs.\n" } ], "responses": { @@ -8847,8 +8827,8 @@ "tags": [ "Tasks" ], - "summary": "List logs for a task", - "description": "Lists all log events for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen a task runs, InfluxDB creates a `run` record in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", + "summary": "Retrieve all logs for a task", + "description": "Retrieves a list of all logs for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nWhen an InfluxDB task runs, a “run” record is created in the task’s history.\nLogs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt.\n\nUse this endpoint to retrieve only the log events for a task,\nwithout additional task metadata.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8860,12 +8840,12 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve logs for." + "description": "The task ID." } ], "responses": { "200": { - "description": "Success.\nThe response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", + "description": "Success. The response body contains an `events` list with logs for the task.\nEach log event `message` contains detail about the event.\nIf a task run fails, InfluxDB logs an event with the reason for the failure.\n", "content": { "application/json": { "schema": { @@ -8873,7 +8853,7 @@ }, "examples": { "taskSuccess": { - "summary": "Events for a successful task run", + "summary": "Events for a successful task run.", "value": { "events": [ { @@ -8890,7 +8870,7 @@ } }, "taskFailure": { - "summary": "Events for a failed task run", + "summary": "Events for a failed task run.", "value": { "events": [ { @@ -8939,8 +8919,8 @@ "tags": [ "Tasks" ], - "summary": "List logs for a run", - "description": "Lists all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) performance and troubleshoot failed task runs.\n", + "summary": "Retrieve all logs for a run", + "description": "Retrieves all logs for a task run.\nA log is a list of run events with `runID`, `time`, and `message` properties.\n\nUse this endpoint to help analyze task performance and troubleshoot failed task runs.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -8952,7 +8932,7 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the run belongs to." + "description": "The ID of the task to get logs for." }, { "in": "path", @@ -8961,7 +8941,7 @@ "type": "string" }, "required": true, - "description": "A run ID. Specifies the task run to list logs for." + "description": "The ID of the run to get logs for." } ], "responses": { @@ -9041,7 +9021,7 @@ "Tasks" ], "summary": "List labels for a task", - "description": "Lists all labels for a task.\n\nUse this endpoint to list labels applied to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", + "description": "Retrieves a list of all labels for a task.\n\nLabels may be used for grouping and filtering tasks.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9053,7 +9033,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the task to retrieve labels for.\n" + "description": "The ID of the task to retrieve labels for." } ], "responses": { @@ -9090,7 +9070,7 @@ "Tasks" ], "summary": "Add a label to a task", - "description": "Adds a label to a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nUse this endpoint to add a label to a task.\nLabels are a way to add metadata to InfluxDB resources.\nYou can use labels for grouping and filtering resources in the\nInfluxDB UI, `influx` CLI, and InfluxDB API.\n", + "description": "Adds a label to a task.\n\nUse this endpoint to add a label that you can use to filter tasks in the InfluxDB UI.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9102,11 +9082,11 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to label.\n" + "description": "The ID of the task to label." } ], "requestBody": { - "description": "In the request body, provide an object that specifies the label.\n", + "description": "An object that contains a _`labelID`_ to add to the task.", "required": true, "content": { "application/json": { @@ -9118,7 +9098,7 @@ }, "responses": { "201": { - "description": "Success. The response body contains the label.", + "description": "Success. The response body contains a list of all labels for the task.", "content": { "application/json": { "schema": { @@ -9152,7 +9132,7 @@ "Tasks" ], "summary": "Delete a label from a task", - "description": "Deletes a label from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "Deletes a label from a task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9164,7 +9144,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete the label from.\n" + "description": "The ID of the task to delete the label from." }, { "in": "path", @@ -9173,7 +9153,7 @@ "type": "string" }, "required": true, - "description": "A label ID.\nSpecifies the label to delete.\n" + "description": "The ID of the label to delete." } ], "responses": { @@ -9205,7 +9185,7 @@ "Config" ], "summary": "Retrieve feature flags", - "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/)\n", + "description": "Retrieves the feature flag key-value pairs configured for the InfluxDB\ninstance.\n_Feature flags_ are configuration options used to develop and test\nexperimental InfluxDB features and are intended for internal use only.\n\nThis endpoint represents the first step in the following three-step process\nto configure feature flags:\n\n1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve\n feature flags and their values.\n2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/#feature-flags).\n3. **Optional**: To confirm that your change is applied, do one of the following:\n\n - Send a request to this endpoint to retrieve the current feature flag values.\n - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the\n current runtime server configuration.\n\n#### Related guides\n\n- [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9346,7 +9326,7 @@ "Tasks" ], "summary": "List all task members", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `member` role for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9358,12 +9338,12 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve members for.\n" + "description": "The task ID." } ], "responses": { "200": { - "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n\nIf the task has no members, the response contains an empty `users` array.\n", + "description": "Success. The response body contains a list of `users` that have\nthe `member` role for a task.\n", "content": { "application/json": { "schema": { @@ -9391,7 +9371,7 @@ "Tasks" ], "summary": "Add a member to a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns\nthe member.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAdds a user to members of a task and returns the member.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9403,11 +9383,11 @@ "type": "string" }, "required": true, - "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nSpecifies the task for the member.\n" + "description": "The task ID." } ], "requestBody": { - "description": "In the request body, provide an object that specifies the user.\n", + "description": "A user to add as a member of the task.", "required": true, "content": { "application/json": { @@ -9419,7 +9399,7 @@ }, "responses": { "201": { - "description": "Created. The task `member` role is assigned to the user.\nThe response body contains the resource member with\nrole and user detail.\n", + "description": "Created. The user is added to task members.", "content": { "application/json": { "schema": { @@ -9449,7 +9429,7 @@ "Tasks" ], "summary": "Remove a member from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves a member from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9461,7 +9441,7 @@ "type": "string" }, "required": true, - "description": "A user ID. Specifies the member to remove." + "description": "The ID of the member to remove." }, { "in": "path", @@ -9470,12 +9450,12 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the member from." + "description": "The task ID." } ], "responses": { "204": { - "description": "Success. The member is removed." + "description": "Member removed" }, "default": { "description": "Unexpected error", @@ -9498,7 +9478,7 @@ "Tasks" ], "summary": "List all owners of a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nLists all users that have the `owner` role for the specified task.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nRetrieves all users that have owner permission for a task.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9510,7 +9490,7 @@ "type": "string" }, "required": true, - "description": "A task ID. Specifies the task to retrieve owners for." + "description": "The ID of the task to retrieve owners for." } ], "responses": { @@ -9559,7 +9539,7 @@ "Tasks" ], "summary": "Add an owner for a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nAdds a specified user to owners of the specified task and then returns the\nowner.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n\nAssigns a task `owner` role to a user.\n\nUse this endpoint to create a _resource owner_ for the task.\nA _resource owner_ is a user with `role: owner` for a specific resource.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9571,11 +9551,11 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) for the owner.\n" + "description": "The task ID." } ], "requestBody": { - "description": "In the request body, provide an object that specifies the user.\n", + "description": "A user to add as an owner of the task.", "required": true, "content": { "application/json": { @@ -9648,7 +9628,7 @@ "Tasks" ], "summary": "Remove an owner from a task", - "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.\n\nRemoves an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "**Deprecated**: Tasks don't use `owner` and `member` roles.\nUse [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions.\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -9660,7 +9640,7 @@ "type": "string" }, "required": true, - "description": "A user ID. Specifies the owner to remove from the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)." + "description": "The ID of the owner to remove." }, { "in": "path", @@ -9669,12 +9649,12 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the owner from.\n" + "description": "The task ID." } ], "responses": { "204": { - "description": "Success. The owner is removed." + "description": "Owner removed" }, "default": { "description": "Unexpected error", @@ -11380,143 +11360,150 @@ } } }, - "/authorizations": { + "/debug/pprof/all": { "get": { - "operationId": "GetAuthorizations", + "operationId": "GetDebugPprofAllProfiles", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Debug", + "System information endpoints" ], - "summary": "List authorizations", - "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB Cloud\n\n- InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n values in `GET /api/v2/authorizations` responses;\n returns `token: redacted` for all authorizations.\n\n#### Required permissions\n\nTo retrieve an authorization, the request must use an API token that has the\nfollowing permissions:\n\n- `read-authorizations`\n- `read-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, + "summary": "Retrieve all runtime profiles", + "description": "Collects samples and returns reports for the following [Go runtime profiles](https://pkg.go.dev/runtime/pprof):\n\n- **allocs**: All past memory allocations\n- **block**: Stack traces that led to blocking on synchronization primitives\n- **cpu**: (Optional) Program counters sampled from the executing stack.\n Include by passing the `cpu` query parameter with a [duration]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#duration) value.\n Equivalent to the report from [`GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS`](#operation/GetDebugPprofProfile).\n- **goroutine**: All current goroutines\n- **heap**: Memory allocations for live objects\n- **mutex**: Holders of contended mutexes\n- **threadcreate**: Stack traces that led to the creation of new OS threads\n", + "x-codeSamples": [ { - "in": "query", - "name": "userID", - "schema": { - "type": "string" - }, - "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "lang": "Shell", + "label": "Shell: Get all profiles", + "source": "# Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling.\n\ncurl \"http://localhost:8086/debug/pprof/all?cpu=10s\" | tar -xz\n\n# x profiles/cpu.pb.gz\n# x profiles/goroutine.pb.gz\n# x profiles/block.pb.gz\n# x profiles/mutex.pb.gz\n# x profiles/heap.pb.gz\n# x profiles/allocs.pb.gz\n# x profiles/threadcreate.pb.gz\n\n# Analyze a profile.\n\ngo tool pprof profiles/heap.pb.gz\n" }, { - "in": "query", - "name": "user", - "schema": { - "type": "string" - }, - "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" - }, + "lang": "Shell", + "label": "Shell: Get all profiles except CPU", + "source": "# Download and extract a `tar.gz` of all profiles except CPU.\n\ncurl http://localhost:8086/debug/pprof/all | tar -xz\n\n# x profiles/goroutine.pb.gz\n# x profiles/block.pb.gz\n# x profiles/mutex.pb.gz\n# x profiles/heap.pb.gz\n# x profiles/allocs.pb.gz\n# x profiles/threadcreate.pb.gz\n\n# Analyze a profile.\n\ngo tool pprof profiles/heap.pb.gz\n" + } + ], + "servers": [ { - "in": "query", - "name": "orgID", - "schema": { - "type": "string" - }, - "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." - }, + "url": "" + } + ], + "parameters": [ { - "in": "query", - "name": "org", - "schema": { - "type": "string" - }, - "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + "$ref": "#/components/parameters/TraceSpan" }, { "in": "query", - "name": "token", + "name": "cpu", + "description": "Collects and returns CPU profiling data for the specified [duration]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#duration).\n", "schema": { - "type": "string" - }, - "description": "An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value.\nSpecifies an authorization by its `token` property value\nand returns the authorization.\n\n#### InfluxDB OSS\n\n- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,\n applies other parameters, and then returns the result.\n\n#### Limitations\n\n- The parameter is non-repeatable. If you specify more than one,\n only the first one is used. If a resource with the specified\n property value doesn't exist, then the response body contains an empty list.\n" + "type": "string", + "format": "duration", + "externalDocs": { + "description": "InfluxDB duration", + "url": "https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration" + } + } } ], "responses": { "200": { - "description": "Success. The response body contains a list of authorizations.\n\nIf the response body is missing authorizations that you expect, check that the API\ntoken used in the request has `read-user` permission for the users (`userID` property value)\nin those authorizations.\n\n#### InfluxDB OSS\n\n- **Warning**: The response body contains authorizations with their\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in clear text.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n", + "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) reports.\n", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "$ref": "#/components/schemas/Authorizations" + "description": "GZIP compressed TAR file (`.tar.gz`) that contains\n[Go runtime profile](https://pkg.go.dev/runtime/pprof) reports.\n", + "type": "string", + "format": "binary", + "externalDocs": { + "description": "Golang pprof package", + "url": "https://pkg.go.dev/net/http/pprof" + } } } } }, - "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", + } + }, + "/debug/pprof/allocs": { + "get": { + "operationId": "GetDebugPprofAllocs", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Debug", + "System information endpoints" ], - "summary": "Create an authorization", - "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe API token is the authorization's `token` property value.\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n - InfluxDB allows access to the API token value immediately after the authorization is created.\n - You can’t change access (read/write) permissions for an API token after it’s created.\n - Tokens stop working when the user who created the token is deleted.\n\nWe recommend the following for managing your tokens:\n\n - Create a generic user to create and manage tokens for writing data.\n - Store your tokens in a secure password vault for future access.\n\n#### Required permissions\n\n- `write-authorizations`\n- `write-user` for the user that the authorization is scoped to\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", - "parameters": [ + "summary": "Retrieve the memory allocations runtime profile", + "description": "Returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of\nall past memory allocations.\n**allocs** is the same as the **heap** profile,\nbut changes the default [pprof](https://pkg.go.dev/runtime/pprof)\ndisplay to __-alloc_space__,\nthe total number of bytes allocated since the program began (including garbage-collected bytes).\n", + "x-codeSamples": [ { - "$ref": "#/components/parameters/TraceSpan" + "lang": "Shell", + "label": "Shell: go tool pprof", + "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/allocs\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N memory allocations.\n\n(pprof) top10\n" } ], - "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" - } - } + "servers": [ + { + "url": "" + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "query", + "name": "debug", + "description": "- `0`: (Default) Return the report as a gzip-compressed protocol buffer.\n- `1`: Return a response body with the report formatted as human-readable text.\n The report contains comments that translate addresses to function names and line numbers for debugging.\n\n`debug=1` is mutually exclusive with the `seconds` query parameter.\n", + "schema": { + "type": "integer", + "format": "int64", + "enum": [ + 0, + 1 + ] + } + }, + { + "in": "query", + "name": "seconds", + "description": "Number of seconds to collect statistics.\n\n`seconds` is mutually exclusive with `debug=1`.\n", + "schema": { + "type": "string", + "format": "int64" } } - }, + ], "responses": { - "201": { - "description": "Success. The authorization is created. The response body contains the\nauthorization.\n", + "200": { + "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible\nwith [pprof](https://github.com/google/pprof) analysis and visualization tools.\nIf debug is enabled (`?debug=1`), response body contains a human-readable profile.\n", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "$ref": "#/components/schemas/Authorization" + "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format.\n", + "type": "string", + "format": "binary", + "externalDocs": { + "description": "Golang pprof package", + "url": "https://pkg.go.dev/net/http/pprof" + } + } + }, + "text/plain": { + "schema": { + "description": "Response body contains a report formatted in plain text.\nThe report contains comments that translate addresses to\nfunction names and line numbers for debugging.\n", + "type": "string", + "format": "Go runtime profile", + "externalDocs": { + "description": "Golang pprof package", + "url": "https://pkg.go.dev/net/http/pprof" + } } } } }, - "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" @@ -11524,214 +11511,82 @@ } } }, - "/authorizations/{authID}": { + "/debug/pprof/block": { "get": { - "operationId": "GetAuthorizationsID", + "operationId": "GetDebugPprofBlock", "tags": [ - "Authorizations (API tokens)", - "Security and access endpoints" + "Debug", + "System information endpoints" + ], + "summary": "Retrieve the block runtime profile", + "description": "Collects samples and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)\nreport of stack traces that led to blocking on synchronization primitives.\n", + "x-codeSamples": [ + { + "lang": "Shell", + "label": "Shell: go tool pprof", + "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/block\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N entries.\n\n(pprof) top10\n" + } + ], + "servers": [ + { + "url": "" + } ], - "summary": "Retrieve an authorization", - "description": "Retrieves an authorization.\n\nUse this endpoint to retrieve information about an API token, including\nthe token's permissions and the user that the token is scoped to.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", - "externalDocs": { - "url": "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/", - "description": "View tokens" - }, "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { - "in": "path", - "name": "authID", + "in": "query", + "name": "debug", + "description": "- `0`: (Default) Return the report as a gzip-compressed protocol buffer.\n- `1`: Return a response body with the report formatted as human-readable text.\n The report contains comments that translate addresses to function names and line numbers for debugging.\n\n`debug=1` is mutually exclusive with the `seconds` query parameter.\n", "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.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "notFound": { - "summary": "The specified resource ID is invalid.\n", - "value": { - "code": "invalid", - "message": "id must have a length of 16 bytes" - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "description": "Not found.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "notFound": { - "summary": "The requested authorization doesn't exist.\n", - "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.\n\nUse this endpoint to set an API token's status to be _active_ or _inactive_.\nInfluxDB rejects requests that use inactive API tokens.\n", - "requestBody": { - "description": "In the request body, provide the authorization properties to update.", - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AuthorizationUpdateRequest" - } + "type": "integer", + "format": "int64", + "enum": [ + 0, + 1 + ] } - } - }, - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" }, { - "in": "path", - "name": "authID", + "in": "query", + "name": "seconds", + "description": "Number of seconds to collect statistics.\n\n`seconds` is mutually exclusive with `debug=1`.\n", "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" - } - } + "type": "string", + "format": "int64" } - }, - "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.\n\nUse the endpoint to delete an API token.\n\nIf you want to disable an API token instead of delete it,\n[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).\n", - "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.\n", + "200": { + "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible\nwith [pprof](https://github.com/google/pprof) analysis and visualization tools.\nIf debug is enabled (`?debug=1`), response body contains a human-readable profile.\n", "content": { - "application/json": { + "application/octet-stream": { "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "notFound": { - "summary": "The specified resource ID is invalid.\n", - "value": { - "code": "invalid", - "message": "id must have a length of 16 bytes" - } + "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format.\n", + "type": "string", + "format": "binary", + "externalDocs": { + "description": "Golang pprof package", + "url": "https://pkg.go.dev/net/http/pprof" } } - } - } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "description": "Not found.\n", - "content": { - "application/json": { + }, + "text/plain": { "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "notFound": { - "summary": "The requested authorization doesn't exist.\n", - "value": { - "code": "not found", - "message": "authorization not found" - } + "description": "Response body contains a report formatted in plain text.\nThe report contains comments that translate addresses to\nfunction names and line numbers for debugging.\n", + "type": "string", + "format": "Go runtime profile", + "externalDocs": { + "description": "Golang pprof package", + "url": "https://pkg.go.dev/net/http/pprof" } } } } }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, "default": { "description": "Unexpected error", "$ref": "#/components/responses/GeneralServerError" @@ -11739,27 +11594,15 @@ } } }, - "/debug/pprof/all": { + "/debug/pprof/cmdline": { "get": { - "operationId": "GetDebugPprofAllProfiles", + "operationId": "GetDebugPprofCmdline", "tags": [ "Debug", "System information endpoints" ], - "summary": "Retrieve all runtime profiles", - "description": "Collects samples and returns reports for the following [Go runtime profiles](https://pkg.go.dev/runtime/pprof):\n\n- **allocs**: All past memory allocations\n- **block**: Stack traces that led to blocking on synchronization primitives\n- **cpu**: (Optional) Program counters sampled from the executing stack.\n Include by passing the `cpu` query parameter with a [duration]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#duration) value.\n Equivalent to the report from [`GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS`](#operation/GetDebugPprofProfile).\n- **goroutine**: All current goroutines\n- **heap**: Memory allocations for live objects\n- **mutex**: Holders of contended mutexes\n- **threadcreate**: Stack traces that led to the creation of new OS threads\n", - "x-codeSamples": [ - { - "lang": "Shell", - "label": "Shell: Get all profiles", - "source": "# Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling.\n\ncurl \"http://localhost:8086/debug/pprof/all?cpu=10s\" | tar -xz\n\n# x profiles/cpu.pb.gz\n# x profiles/goroutine.pb.gz\n# x profiles/block.pb.gz\n# x profiles/mutex.pb.gz\n# x profiles/heap.pb.gz\n# x profiles/allocs.pb.gz\n# x profiles/threadcreate.pb.gz\n\n# Analyze a profile.\n\ngo tool pprof profiles/heap.pb.gz\n" - }, - { - "lang": "Shell", - "label": "Shell: Get all profiles except CPU", - "source": "# Download and extract a `tar.gz` of all profiles except CPU.\n\ncurl http://localhost:8086/debug/pprof/all | tar -xz\n\n# x profiles/goroutine.pb.gz\n# x profiles/block.pb.gz\n# x profiles/mutex.pb.gz\n# x profiles/heap.pb.gz\n# x profiles/allocs.pb.gz\n# x profiles/threadcreate.pb.gz\n\n# Analyze a profile.\n\ngo tool pprof profiles/heap.pb.gz\n" - } - ], + "summary": "Retrieve the command line invocation", + "description": "Returns the command line that invoked InfluxDB.\n", "servers": [ { "url": "" @@ -11768,34 +11611,16 @@ "parameters": [ { "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "cpu", - "description": "Collects and returns CPU profiling data for the specified [duration]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#duration).\n", - "schema": { - "type": "string", - "format": "duration", - "externalDocs": { - "description": "InfluxDB duration", - "url": "https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration" - } - } } ], "responses": { "200": { - "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) reports.\n", + "description": "Command line invocation.", "content": { - "application/octet-stream": { + "text/plain": { "schema": { - "description": "GZIP compressed TAR file (`.tar.gz`) that contains\n[Go runtime profile](https://pkg.go.dev/runtime/pprof) reports.\n", "type": "string", - "format": "binary", - "externalDocs": { - "description": "Golang pprof package", - "url": "https://pkg.go.dev/net/http/pprof" - } + "format": "Command line" } } } @@ -11807,20 +11632,20 @@ } } }, - "/debug/pprof/allocs": { + "/debug/pprof/goroutine": { "get": { - "operationId": "GetDebugPprofAllocs", + "operationId": "GetDebugPprofGoroutine", "tags": [ "Debug", "System information endpoints" ], - "summary": "Retrieve the memory allocations runtime profile", - "description": "Returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of\nall past memory allocations.\n**allocs** is the same as the **heap** profile,\nbut changes the default [pprof](https://pkg.go.dev/runtime/pprof)\ndisplay to __-alloc_space__,\nthe total number of bytes allocated since the program began (including garbage-collected bytes).\n", + "summary": "Retrieve the goroutines runtime profile", + "description": "Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)\nreport of all current goroutines.\n", "x-codeSamples": [ { "lang": "Shell", "label": "Shell: go tool pprof", - "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/allocs\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N memory allocations.\n\n(pprof) top10\n" + "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/goroutine\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N entries.\n\n(pprof) top10\n" } ], "servers": [ @@ -11835,7 +11660,7 @@ { "in": "query", "name": "debug", - "description": "- `0`: (Default) Return the report as a gzip-compressed protocol buffer.\n- `1`: Return a response body with the report formatted as human-readable text.\n The report contains comments that translate addresses to function names and line numbers for debugging.\n\n`debug=1` is mutually exclusive with the `seconds` query parameter.\n", + "description": "- `0`: (Default) Return the report as a gzip-compressed protocol buffer.\n- `1`: Return a response body with the report formatted as\n human-readable text with comments that translate addresses to\n function names and line numbers for debugging.\n\n`debug=1` is mutually exclusive with the `seconds` query parameter.\n", "schema": { "type": "integer", "format": "int64", @@ -11890,20 +11715,20 @@ } } }, - "/debug/pprof/block": { + "/debug/pprof/heap": { "get": { - "operationId": "GetDebugPprofBlock", + "operationId": "GetDebugPprofHeap", "tags": [ "Debug", "System information endpoints" ], - "summary": "Retrieve the block runtime profile", - "description": "Collects samples and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)\nreport of stack traces that led to blocking on synchronization primitives.\n", + "summary": "Retrieve the heap runtime profile", + "description": "Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)\nreport of memory allocations for live objects.\n\nTo run **garbage collection** before sampling,\npass the `gc` query parameter with a value of `1`.\n", "x-codeSamples": [ { "lang": "Shell", "label": "Shell: go tool pprof", - "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/block\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N entries.\n\n(pprof) top10\n" + "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/heap\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N memory-intensive nodes.\n\n(pprof) top10\n\n# pprof displays the list:\n# Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total\n# Dropped 895 nodes (cum <= 0.83MB)\n# Showing top 10 nodes out of 143\n" } ], "servers": [ @@ -11936,6 +11761,19 @@ "type": "string", "format": "int64" } + }, + { + "in": "query", + "name": "gc", + "description": "- `0`: (Default) don't force garbage collection before sampling.\n- `1`: Force garbage collection before sampling.\n", + "schema": { + "type": "integer", + "format": "int64", + "enum": [ + 0, + 1 + ] + } } ], "responses": { @@ -11962,6 +11800,12 @@ "description": "Golang pprof package", "url": "https://pkg.go.dev/net/http/pprof" } + }, + "examples": { + "profileDebugResponse": { + "summary": "Profile in plain text", + "value": "heap profile: 12431: 137356528 [149885081: 846795139976] @ heap/8192\n23: 17711104 [46: 35422208] @ 0x4c6df65 0x4ce03ec 0x4cdf3c5 0x4c6f4db 0x4c9edbc 0x4bdefb3 0x4bf822a 0x567d158 0x567ced9 0x406c0a1\n#\t0x4c6df64\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*entry).add+0x1a4\t\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/cache.go:97\n#\t0x4ce03eb\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*partition).write+0x2ab\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/ring.go:229\n#\t0x4cdf3c4\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*ring).write+0xa4\t\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/ring.go:95\n#\t0x4c6f4da\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*Cache).WriteMulti+0x31a\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/cache.go:343\n" + } } } } @@ -11973,232 +11817,9 @@ } } }, - "/debug/pprof/cmdline": { + "/debug/pprof/mutex": { "get": { - "operationId": "GetDebugPprofCmdline", - "tags": [ - "Debug", - "System information endpoints" - ], - "summary": "Retrieve the command line invocation", - "description": "Returns the command line that invoked InfluxDB.\n", - "servers": [ - { - "url": "" - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - } - ], - "responses": { - "200": { - "description": "Command line invocation.", - "content": { - "text/plain": { - "schema": { - "type": "string", - "format": "Command line" - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/debug/pprof/goroutine": { - "get": { - "operationId": "GetDebugPprofGoroutine", - "tags": [ - "Debug", - "System information endpoints" - ], - "summary": "Retrieve the goroutines runtime profile", - "description": "Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)\nreport of all current goroutines.\n", - "x-codeSamples": [ - { - "lang": "Shell", - "label": "Shell: go tool pprof", - "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/goroutine\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N entries.\n\n(pprof) top10\n" - } - ], - "servers": [ - { - "url": "" - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "debug", - "description": "- `0`: (Default) Return the report as a gzip-compressed protocol buffer.\n- `1`: Return a response body with the report formatted as\n human-readable text with comments that translate addresses to\n function names and line numbers for debugging.\n\n`debug=1` is mutually exclusive with the `seconds` query parameter.\n", - "schema": { - "type": "integer", - "format": "int64", - "enum": [ - 0, - 1 - ] - } - }, - { - "in": "query", - "name": "seconds", - "description": "Number of seconds to collect statistics.\n\n`seconds` is mutually exclusive with `debug=1`.\n", - "schema": { - "type": "string", - "format": "int64" - } - } - ], - "responses": { - "200": { - "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible\nwith [pprof](https://github.com/google/pprof) analysis and visualization tools.\nIf debug is enabled (`?debug=1`), response body contains a human-readable profile.\n", - "content": { - "application/octet-stream": { - "schema": { - "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format.\n", - "type": "string", - "format": "binary", - "externalDocs": { - "description": "Golang pprof package", - "url": "https://pkg.go.dev/net/http/pprof" - } - } - }, - "text/plain": { - "schema": { - "description": "Response body contains a report formatted in plain text.\nThe report contains comments that translate addresses to\nfunction names and line numbers for debugging.\n", - "type": "string", - "format": "Go runtime profile", - "externalDocs": { - "description": "Golang pprof package", - "url": "https://pkg.go.dev/net/http/pprof" - } - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/debug/pprof/heap": { - "get": { - "operationId": "GetDebugPprofHeap", - "tags": [ - "Debug", - "System information endpoints" - ], - "summary": "Retrieve the heap runtime profile", - "description": "Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof)\nreport of memory allocations for live objects.\n\nTo run **garbage collection** before sampling,\npass the `gc` query parameter with a value of `1`.\n", - "x-codeSamples": [ - { - "lang": "Shell", - "label": "Shell: go tool pprof", - "source": "# Analyze the profile in interactive mode.\n\ngo tool pprof http://localhost:8086/debug/pprof/heap\n\n# `pprof` returns the following prompt:\n# Entering interactive mode (type \"help\" for commands, \"o\" for options)\n# (pprof)\n\n# At the prompt, get the top N memory-intensive nodes.\n\n(pprof) top10\n\n# pprof displays the list:\n# Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total\n# Dropped 895 nodes (cum <= 0.83MB)\n# Showing top 10 nodes out of 143\n" - } - ], - "servers": [ - { - "url": "" - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - }, - { - "in": "query", - "name": "debug", - "description": "- `0`: (Default) Return the report as a gzip-compressed protocol buffer.\n- `1`: Return a response body with the report formatted as human-readable text.\n The report contains comments that translate addresses to function names and line numbers for debugging.\n\n`debug=1` is mutually exclusive with the `seconds` query parameter.\n", - "schema": { - "type": "integer", - "format": "int64", - "enum": [ - 0, - 1 - ] - } - }, - { - "in": "query", - "name": "seconds", - "description": "Number of seconds to collect statistics.\n\n`seconds` is mutually exclusive with `debug=1`.\n", - "schema": { - "type": "string", - "format": "int64" - } - }, - { - "in": "query", - "name": "gc", - "description": "- `0`: (Default) don't force garbage collection before sampling.\n- `1`: Force garbage collection before sampling.\n", - "schema": { - "type": "integer", - "format": "int64", - "enum": [ - 0, - 1 - ] - } - } - ], - "responses": { - "200": { - "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible\nwith [pprof](https://github.com/google/pprof) analysis and visualization tools.\nIf debug is enabled (`?debug=1`), response body contains a human-readable profile.\n", - "content": { - "application/octet-stream": { - "schema": { - "description": "[Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format.\n", - "type": "string", - "format": "binary", - "externalDocs": { - "description": "Golang pprof package", - "url": "https://pkg.go.dev/net/http/pprof" - } - } - }, - "text/plain": { - "schema": { - "description": "Response body contains a report formatted in plain text.\nThe report contains comments that translate addresses to\nfunction names and line numbers for debugging.\n", - "type": "string", - "format": "Go runtime profile", - "externalDocs": { - "description": "Golang pprof package", - "url": "https://pkg.go.dev/net/http/pprof" - } - }, - "examples": { - "profileDebugResponse": { - "summary": "Profile in plain text", - "value": "heap profile: 12431: 137356528 [149885081: 846795139976] @ heap/8192\n23: 17711104 [46: 35422208] @ 0x4c6df65 0x4ce03ec 0x4cdf3c5 0x4c6f4db 0x4c9edbc 0x4bdefb3 0x4bf822a 0x567d158 0x567ced9 0x406c0a1\n#\t0x4c6df64\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*entry).add+0x1a4\t\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/cache.go:97\n#\t0x4ce03eb\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*partition).write+0x2ab\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/ring.go:229\n#\t0x4cdf3c4\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*ring).write+0xa4\t\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/ring.go:95\n#\t0x4c6f4da\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*Cache).WriteMulti+0x31a\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/cache.go:343\n" - } - } - } - } - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/debug/pprof/mutex": { - "get": { - "operationId": "GetDebugPprofMutex", + "operationId": "GetDebugPprofMutex", "tags": [ "Debug", "System information endpoints" @@ -12722,50 +12343,407 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/User" + } + } + } + }, + "responses": { + "201": { + "description": "Success.\nThe response body contains the user.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserResponse" + } + } + } + }, + "401": { + "description": "Unauthorized.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "examples": { + "tokenNotAuthorized": { + "summary": "API token doesn't have `write:users` permission", + "value": { + "code": "unauthorized", + "message": "write:users/09d8462ce0764000 is unauthorized" + } + } + } + } + } + }, + "422": { + "description": "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + }, + "x-codeSamples": [ + { + "label": "cURL: create a user and set a password", + "lang": "Shell", + "source": "# The following steps show how to create a user and then set\n# the user's password:\n#\n# 1. Send a request to this endpoint to create a user--for example:\n\n USER=$(curl --request POST \\\n \"INFLUX_URL/api/v2/users/\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header 'Content-type: application/json' \\\n --data-binary @- << EOF\n {\n \"name\": \"USER_NAME\",\n \"status\": \"active\"\n }\n EOF\n )\n\n# 2. Extract the id property from the response in step 1--for example:\n\n USER_ID=`echo $USER | jq -r '.id'`\n\n# 3. To set the user's password, set the password property in a request\n# to the /api/v2/users/USER_ID/password endpoint--for example:\n\n curl request POST \"INFLUX_URL/api/v2/users/$USER_ID/password/\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header 'Content-type: application/json' \\\n --data '{ \"password\": \"USER_PASSWORD\" }'\n" + } + ] + } + }, + "/users/{userID}": { + "get": { + "operationId": "GetUsersID", + "tags": [ + "Security and access endpoints", + "Users" + ], + "summary": "Retrieve a user", + "description": "Retrieves a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "userID", + "schema": { + "type": "string" + }, + "required": true, + "description": "A user ID.\nRetrieves the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + } + ], + "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": "Updates a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) and returns the user.\n\n#### Required permissions\n\n| Action | Permission required |\n|:------------|:-----------------------------------------------|\n| Update a user | `write-users` or `write-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to update.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "requestBody": { + "description": "In the request body, provide the user properties to update.", + "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.\nSpecifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) to update.\n" + } + ], + "responses": { + "200": { + "description": "Success.\nThe response body contains the user.\n", + "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": "Deletes a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\n#### Required permissions\n\n| Action | Permission required |\n|:------------|:-----------------------------------------------|\n| Delete a user | `write-users` or `write-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to delete.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "path", + "name": "userID", + "schema": { + "type": "string" + }, + "required": true, + "description": "A user ID.\nSpecifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) to delete.\n" + } + ], + "responses": { + "204": { + "description": "Success. The user is deleted." + }, + "400": { + "description": "Bad request.\nThe response body contains detail about the error.\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "$ref": "#/components/responses/AuthorizationError" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, + "/setup": { + "get": { + "operationId": "GetSetup", + "tags": [ + "Setup" + ], + "summary": "Check if database has default user, org, bucket", + "description": "Returns `true` if no default user, organization, or bucket has been created.", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + } + ], + "responses": { + "200": { + "description": "allowed true or false", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IsOnboarding" + } + } + } + } + } + }, + "post": { + "operationId": "PostSetup", + "tags": [ + "Setup" + ], + "summary": "Set up initial user, org and bucket", + "description": "Post an onboarding request to set up initial user, org 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": "Created default user, bucket, org", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OnboardingResponse" + } + } + } + }, + "default": { + "description": "Unexpected error", + "$ref": "#/components/responses/GeneralServerError" + } + } + } + }, + "/authorizations": { + "get": { + "operationId": "GetAuthorizations", + "tags": [ + "Authorizations", + "Security and access endpoints" + ], + "summary": "List authorizations", + "description": "Lists authorizations.\n\nTo limit which authorizations are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all authorizations.\n\n#### InfluxDB OSS\n\n- InfluxDB OSS returns\n [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) values in authorizations.\n- If the request uses an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_,\n InfluxDB OSS returns authorizations for all organizations in the instance.\n\n#### Required permissions\n\n- An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_.\n\n#### Related guides\n\n- [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/)\n", + "parameters": [ + { + "$ref": "#/components/parameters/TraceSpan" + }, + { + "in": "query", + "name": "userID", + "schema": { + "type": "string" + }, + "description": "A user ID.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "user", + "schema": { + "type": "string" + }, + "description": "A user name.\nOnly returns authorizations scoped to the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + }, + { + "in": "query", + "name": "orgID", + "schema": { + "type": "string" + }, + "description": "An organization ID. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization)." + }, + { + "in": "query", + "name": "org", + "schema": { + "type": "string" + }, + "description": "An organization name.\nOnly returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + } + ], + "responses": { + "200": { + "description": "Success. The response body contains a list of authorizations.", + "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" + ], + "summary": "Create an authorization", + "description": "Creates an authorization and returns the authorization with the\ngenerated API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token).\n\nUse this endpoint to create an authorization, which generates an API token\nwith permissions to `read` or `write` to a specific resource or `type` of resource.\nThe response contains the new authorization with the generated API token.\n\n#### Limitations\n\nTo follow best practices for secure API token generation and retrieval,\nInfluxDB enforces access restrictions on API tokens.\n\n- In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any\n user with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_.\n- You can't update an authorization's permissions.\n- Even if an API token has `read-authorizations` permission, the\n token can't be used to view its authorization details.\n- A token stops working when the user who created the authorization is deleted.\n\nWe recommend creating a generic user to create and manage tokens for writing data.\n\n#### Related guides\n\n- [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/)\n", + "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.\nThe response body contains the user.\n", + "description": "Success. The authorization is created. The response body contains the authorization.\n", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserResponse" + "$ref": "#/components/schemas/Authorization" } } } }, - "401": { - "description": "Unauthorized.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - }, - "examples": { - "tokenNotAuthorized": { - "summary": "API token doesn't have `write:users` permission", - "value": { - "code": "unauthorized", - "message": "write:users/09d8462ce0764000 is unauthorized" - } - } - } - } - } + "400": { + "description": "Invalid request", + "$ref": "#/components/responses/GeneralServerError" }, - "422": { - "description": "Unprocessable entity.\n\nThe error may indicate one of the following problems:\n\n- The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors.\n- You passed a parameter combination that InfluxDB doesn't support.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "401": { + "$ref": "#/components/responses/AuthorizationError" }, "500": { "$ref": "#/components/responses/InternalServerError" @@ -12774,46 +12752,38 @@ "description": "Unexpected error", "$ref": "#/components/responses/GeneralServerError" } - }, - "x-codeSamples": [ - { - "label": "cURL: create a user and set a password", - "lang": "Shell", - "source": "# The following steps show how to create a user and then set\n# the user's password:\n#\n# 1. Send a request to this endpoint to create a user--for example:\n\n USER=$(curl --request POST \\\n \"INFLUX_URL/api/v2/users/\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header 'Content-type: application/json' \\\n --data-binary @- << EOF\n {\n \"name\": \"USER_NAME\",\n \"status\": \"active\"\n }\n EOF\n )\n\n# 2. Extract the id property from the response in step 1--for example:\n\n USER_ID=`echo $USER | jq -r '.id'`\n\n# 3. To set the user's password, set the password property in a request\n# to the /api/v2/users/USER_ID/password endpoint--for example:\n\n curl request POST \"INFLUX_URL/api/v2/users/$USER_ID/password/\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header 'Content-type: application/json' \\\n --data '{ \"password\": \"USER_PASSWORD\" }'\n" - } - ] + } } }, - "/users/{userID}": { + "/authorizations/{authID}": { "get": { - "operationId": "GetUsersID", + "operationId": "GetAuthorizationsID", "tags": [ - "Security and access endpoints", - "Users" + "Authorizations", + "Security and access endpoints" ], - "summary": "Retrieve a user", - "description": "Retrieves a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Retrieve an authorization", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "path", - "name": "userID", + "name": "authID", "schema": { "type": "string" }, "required": true, - "description": "A user ID.\nRetrieves the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "The ID of the authorization to get." } ], "responses": { "200": { - "description": "Success. The response body contains the user.", + "description": "Authorization details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserResponse" + "$ref": "#/components/schemas/Authorization" } } } @@ -12825,19 +12795,18 @@ } }, "patch": { - "operationId": "PatchUsersID", + "operationId": "PatchAuthorizationsID", "tags": [ - "Users" + "Authorizations" ], - "summary": "Update a user", - "description": "Updates a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) and returns the user.\n\n#### Required permissions\n\n| Action | Permission required |\n|:------------|:-----------------------------------------------|\n| Update a user | `write-users` or `write-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to update.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Update an authorization to be active or inactive", "requestBody": { - "description": "In the request body, provide the user properties to update.", + "description": "Authorization to update", "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/User" + "$ref": "#/components/schemas/AuthorizationUpdateRequest" } } } @@ -12848,149 +12817,54 @@ }, { "in": "path", - "name": "userID", + "name": "authID", "schema": { "type": "string" }, "required": true, - "description": "A user ID.\nSpecifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) to update.\n" + "description": "The ID of the authorization to update." } ], "responses": { "200": { - "description": "Success.\nThe response body contains the user.\n", + "description": "The active or inactive authorization", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UserResponse" + "$ref": "#/components/schemas/Authorization" } } } }, - "400": { - "$ref": "#/components/responses/BadRequestError" - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "404": { - "$ref": "#/components/responses/ResourceNotFoundError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, "default": { + "description": "Unexpected error", "$ref": "#/components/responses/GeneralServerError" } } }, "delete": { - "operationId": "DeleteUsersID", + "operationId": "DeleteAuthorizationsID", "tags": [ - "Users" + "Authorizations" ], - "summary": "Delete a user", - "description": "Deletes a [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n\n#### Required permissions\n\n| Action | Permission required |\n|:------------|:-----------------------------------------------|\n| Delete a user | `write-users` or `write-user USER_ID` |\n\n*`USER_ID`* is the ID of the user that you want to delete.\n\n#### Related guides\n\n- [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/)\n", + "summary": "Delete an authorization", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" }, { "in": "path", - "name": "userID", + "name": "authID", "schema": { "type": "string" }, "required": true, - "description": "A user ID.\nSpecifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) to delete.\n" + "description": "The ID of the authorization to delete." } ], "responses": { "204": { - "description": "Success. The user is deleted." - }, - "400": { - "description": "Bad request.\nThe response body contains detail about the error.\n", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "$ref": "#/components/responses/AuthorizationError" - }, - "500": { - "$ref": "#/components/responses/InternalServerError" - }, - "default": { - "description": "Unexpected error", - "$ref": "#/components/responses/GeneralServerError" - } - } - } - }, - "/setup": { - "get": { - "operationId": "GetSetup", - "tags": [ - "Setup" - ], - "summary": "Check if database has default user, org, bucket", - "description": "Returns `true` if no default user, organization, or bucket has been created.", - "parameters": [ - { - "$ref": "#/components/parameters/TraceSpan" - } - ], - "responses": { - "200": { - "description": "allowed true or false", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/IsOnboarding" - } - } - } - } - } - }, - "post": { - "operationId": "PostSetup", - "tags": [ - "Setup" - ], - "summary": "Set up initial user, org and bucket", - "description": "Post an onboarding request to set up initial user, org 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": "Created default user, bucket, org", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OnboardingResponse" - } - } - } + "description": "Authorization deleted" }, "default": { "description": "Unexpected error", @@ -15497,7 +15371,7 @@ "Tasks" ], "summary": "List tasks", - "description": "Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n\n#### Related guide\n\n- [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)\n", + "description": "Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n\nTo limit which tasks are returned, pass query parameters in your request.\nIf no query parameters are passed, InfluxDB returns all tasks up to the default `limit`.\n\n#### Related guide\n\n- [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -15505,7 +15379,7 @@ { "in": "query", "name": "name", - "description": "A task name.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nthat have the specified name.\nDifferent tasks may have the same name.\n", + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name.\nOnly returns tasks with the specified name.\nDifferent tasks may have the same name.\n", "schema": { "type": "string" } @@ -15516,7 +15390,7 @@ "schema": { "type": "string" }, - "description": "A task ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID.\nOnly returns tasks created after the specified task.\n" }, { "in": "query", @@ -15524,7 +15398,7 @@ "schema": { "type": "string" }, - "description": "A user ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nowned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user).\n" + "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nOnly returns tasks owned by the specified user.\n" }, { "in": "query", @@ -15532,7 +15406,7 @@ "schema": { "type": "string" }, - "description": "An organization name.\nOnly returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nOnly returns tasks owned by the specified organization.\n" }, { "in": "query", @@ -15540,7 +15414,7 @@ "schema": { "type": "string" }, - "description": "An organization ID.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization).\n" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nOnly returns tasks owned by the specified organization.\n" }, { "in": "query", @@ -15552,7 +15426,7 @@ "inactive" ] }, - "description": "A task status.\nOnly returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status.\n" + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status.\nOnly returns tasks that have the specified status (`active` or `inactive`).\n" }, { "in": "query", @@ -15568,7 +15442,7 @@ { "in": "query", "name": "type", - "description": "A task type.\nSpecifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response.\nDefault is `system`.\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", + "description": "A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) type (`basic` or `system`).\nDefault is `system`.\nSpecifies the level of detail for tasks in the response.\nThe default (`system`) response contains all the metadata properties for tasks.\nTo reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).\n", "required": false, "schema": { "default": "", @@ -15685,24 +15559,19 @@ "Tasks" ], "summary": "Create a task", - "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\nUse this endpoint to create a scheduled task that runs a script.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "description": "Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task.\n\n#### Related guides\n\n- [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/)\n- [Create a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/)\n- [Common tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" } ], "requestBody": { - "description": "In the request body, provide the task.\n\n#### InfluxDB OSS\n\n- Requires either the `org` parameter or the `orgID` parameter.\n", + "description": "The task to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCreateRequest" - }, - "examples": { - "TaskWithFlux": { - "$ref": "#/components/examples/TaskWithFluxRequest" - } } } } @@ -15727,14 +15596,14 @@ }, "examples": { "orgProvidedNotFound": { - "summary": "The organization specified by org or orgID doesn't own the token passed in the header", + "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" } }, "missingFluxError": { - "summary": "The request body doesn't contain a Flux query", + "summary": "Task in request body is missing Flux query", "value": { "code": "invalid", "message": "failed to decode request: missing flux" @@ -15760,7 +15629,14 @@ } } } - } + }, + "x-codeSamples": [ + { + "lang": "Shell", + "label": "cURL: create a task", + "source": "curl http://localhost:8086/api/v2/tasks \\\n --header \"Content-type: application/json\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --data-binary @- << EOF\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"description\": \"IoT Center 30d environment average.\",\n \"flux\": \"option task = {name: \\\"iot-center-task-1\\\", every: 30m}\\\n from(bucket: \\\"iot_center\\\")\\\n |> range(start: -30d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\\\n |> aggregateWindow(every: 1h, fn: mean)\"\n }\nEOF\n" + } + ] } }, "/tasks/{taskID}": { @@ -15771,7 +15647,7 @@ "Tasks" ], "summary": "Retrieve a task", - "description": "Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", + "description": "Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -15783,7 +15659,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve.\n" + "description": "The ID of the task to retrieve." } ], "responses": { @@ -15820,19 +15696,14 @@ "Tasks" ], "summary": "Update a task", - "description": "Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task),\nand then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`.\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\n#### Related guides\n\n- [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/)\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", + "description": "Updates a task and then cancels all scheduled runs of the task.\n\nUse this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`).\nOnce InfluxDB applies the update, it cancels all previously scheduled runs of the task.\n\nTo update a task, pass an object that contains the updated key-value pairs.\nTo activate or inactivate a task, set the `status` property.\n_`\"status\": \"inactive\"`_ cancels scheduled runs and prevents manual runs of the task.\n", "requestBody": { - "description": "In the request body, provide the task properties to update.\n", + "description": "An object that contains updated task properties to apply.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskUpdateRequest" - }, - "examples": { - "TaskWithFlux": { - "$ref": "#/components/examples/TaskWithFluxRequest" - } } } } @@ -15848,7 +15719,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)to update.\n" + "description": "The ID of the task to update." } ], "responses": { @@ -15885,7 +15756,7 @@ "Tasks" ], "summary": "Delete a task", - "description": "Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)\nand all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nTo disable a task instead of delete it, use\n[`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status\n to `inactive`.\n", + "description": "Deletes a task and associated records.\n\nUse this endpoint to delete a task and all associated records (task runs, logs, and labels).\nOnce the task is deleted, InfluxDB cancels all scheduled runs of the task.\n\nIf you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID).\n", "parameters": [ { "$ref": "#/components/parameters/TraceSpan" @@ -15897,7 +15768,7 @@ "type": "string" }, "required": true, - "description": "A task ID.\nSpecifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete.\n" + "description": "The ID of the task to delete." } ], "responses": { @@ -16954,7 +16825,7 @@ "AuthorizationUpdateRequest": { "properties": { "status": { - "description": "Status of the token. If `inactive`, InfluxDB rejects requests that use the token.", + "description": "Status of the token. If `inactive`, requests using the token will be rejected.", "default": "active", "type": "string", "enum": [ @@ -17187,7 +17058,7 @@ "shardGroupDurationSeconds": { "type": "integer", "format": "int64", - "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration).\n" + "description": "The shard group duration.\nThe duration or interval (in seconds) that each shard group covers.\n\n#### InfluxDB Cloud\n\n- Does not use `shardGroupDurationsSeconds`.\n\n#### InfluxDB OSS\n\n- Default value depends on the\n[bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration).\n" } }, "required": [ @@ -18964,42 +18835,6 @@ } } }, - "TaskCron": { - "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", - "format": "cron" - }, - "TaskDescription": { - "description": "A description of the task.", - "type": "string" - }, - "TaskEvery": { - "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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" - }, - "TaskFlux": { - "description": "Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\nand the script for the task to run.\n\n#### Related guides\n\n- [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/)\n", - "type": "string", - "format": "Flux" - }, - "TaskName": { - "description": "The name of the task.", - "type": "string" - }, - "TaskOffset": { - "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" - }, - "TaskOrg": { - "description": "An organization name.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", - "type": "string" - }, - "TaskOrgID": { - "description": "An organization ID.\nIdentifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task.\n", - "type": "string" - }, "TaskStatusType": { "type": "string", "enum": [ @@ -24555,23 +24390,26 @@ "properties": { "id": { "readOnly": true, - "type": "string", - "description": "The resource ID that InfluxDB uses to uniquely identify the task.\n" + "type": "string" }, "orgID": { - "$ref": "#/components/schemas/TaskOrgID" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID.\nSpecifies the organization that owns the task.\n", + "type": "string" }, "org": { - "$ref": "#/components/schemas/TaskOrg" + "description": "An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name.\nSpecifies the organization that owns the task.\n", + "type": "string" }, "name": { - "$ref": "#/components/schemas/TaskName" - }, - "description": { - "$ref": "#/components/schemas/TaskDescription" + "description": "The name of the task.", + "type": "string" }, "ownerID": { - "description": "A user ID.\nIdentifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task.\n\nTo find a user ID, use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", + "description": "A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID.\nSpecifies the owner of the task.\n\nTo find a user ID, you can use the\n[`GET /api/v2/users` endpoint](#operation/GetUsers) to\nlist users.\n", + "type": "string" + }, + "description": { + "description": "A description of the task.", "type": "string" }, "status": { @@ -24581,20 +24419,27 @@ "$ref": "#/components/schemas/Labels" }, "authorizationID": { - "description": "An authorization ID.\nIdentifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", + "description": "An authorization ID.\nSpecifies the authorization used when the task communicates with the query engine.\n\nTo find an authorization ID, use the\n[`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to\nlist authorizations.\n", "type": "string" }, "flux": { - "$ref": "#/components/schemas/TaskFlux" + "description": "The Flux script that the task executes.", + "type": "string", + "format": "flux" }, "every": { - "$ref": "#/components/schemas/TaskEvery" + "description": "The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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": { - "$ref": "#/components/schemas/TaskCron" + "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": { - "$ref": "#/components/schemas/TaskOffset" + "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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.", @@ -24669,22 +24514,23 @@ "type": "object", "properties": { "orgID": { - "$ref": "#/components/schemas/TaskOrgID" + "description": "The ID of the organization that owns this Task.", + "type": "string" }, "org": { - "$ref": "#/components/schemas/TaskOrg" - }, - "name": { - "$ref": "#/components/schemas/TaskName" + "description": "The name of the organization that owns this Task.", + "type": "string" }, - "description": { - "$ref": "#/components/schemas/TaskDescription" + "status": { + "$ref": "#/components/schemas/TaskStatusType" }, "flux": { - "$ref": "#/components/schemas/TaskFlux" + "description": "The Flux script to run for this task.", + "type": "string" }, - "status": { - "$ref": "#/components/schemas/TaskStatusType" + "description": { + "description": "An optional description of the task.", + "type": "string" } }, "required": [ @@ -24698,22 +24544,28 @@ "$ref": "#/components/schemas/TaskStatusType" }, "flux": { - "$ref": "#/components/schemas/TaskFlux" + "description": "The Flux script that the task runs.", + "type": "string" }, "name": { - "$ref": "#/components/schemas/TaskName" + "description": "Update the 'name' option in the flux script.", + "type": "string" }, "every": { - "$ref": "#/components/schemas/TaskEvery" + "description": "Update the 'every' option in the flux script.", + "type": "string" }, "cron": { - "$ref": "#/components/schemas/TaskCron" + "description": "Update the 'cron' option in the flux script.", + "type": "string" }, "offset": { - "$ref": "#/components/schemas/TaskOffset" + "description": "Update the 'offset' option in the flux script.", + "type": "string" }, "description": { - "$ref": "#/components/schemas/TaskDescription" + "description": "Update the description of the task.", + "type": "string" } } } @@ -24881,7 +24733,7 @@ "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\")", + "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." } @@ -24892,7 +24744,7 @@ "type": "apiKey", "name": "Authorization", "in": "header", - "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n" + "description": "Use the [Token authentication](#section/Authentication/TokenAuthentication)\nscheme to authenticate to the InfluxDB API.\n\nIn your API requests, send an `Authorization` header.\nFor the header value, provide the word `Token` followed by a space and an InfluxDB API token.\nThe word `Token` is case-sensitive.\n\n### Syntax\n\n`Authorization: Token INFLUX_API_TOKEN`\n\n### Example\n\n#### Use Token authentication with cURL\n\nThe following example shows how to use cURL to send an API request that uses Token authentication:\n\n```sh\ncurl --request GET \"INFLUX_URL/api/v2/buckets\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\"\n```\n\nReplace the following:\n\n - *`INFLUX_URL`*: your InfluxDB URL\n - *`INFLUX_API_TOKEN`*: your [InfluxDB API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token)\n\n### Related endpoints\n\n- [`/authorizations` endpoints](#tag/Authorizations)\n\n### Related guides\n\n- [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication)\n- [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/)\n" }, "BasicAuthentication": { "type": "http", diff --git a/contracts/oss.yml b/contracts/oss.yml index 2c707f519..9246054dd 100644 --- a/contracts/oss.yml +++ b/contracts/oss.yml @@ -10,7 +10,7 @@ info: servers: - url: /api/v2 tags: - - name: Authorizations (API tokens) + - name: Authorizations description: | Create and manage authorizations (API tokens). @@ -18,9 +18,23 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. + #### Limitations + + 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. + + API tokens are visible to the user who created the authorization and to any + user with an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. + In InfluxDB OSS, even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + We recommend creating a generic user to create and manage tokens for writing data. - ### User sessions with authorizations + #### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If a user signs in with username and password, creating a _user session_, @@ -104,7 +118,7 @@ tags: - ### Properties + #### Properties A `task` object contains information about an InfluxDB task resource. @@ -112,7 +126,7 @@ tags: - ### Related guides + #### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) @@ -136,7 +150,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - ### Related guides + #### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) @@ -147,14 +161,14 @@ tags: To grant a user permission to access data, add them as a member of an organization and provide them with an API token. - ### User sessions with authorizations + #### 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 + #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/) - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) @@ -221,7 +235,7 @@ tags: | `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 + #### 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, @@ -5336,7 +5350,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5352,7 +5366,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5417,7 +5431,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5432,7 +5446,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -5518,7 +5532,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -5534,7 +5548,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -6012,7 +6026,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6109,7 +6123,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6209,7 +6223,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6270,7 +6284,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -6331,7 +6345,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -6341,7 +6355,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -6416,7 +6430,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -6431,7 +6445,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7204,11 +7218,10 @@ paths: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). + Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. - If you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7217,14 +7230,13 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to list runs for. + 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 the specified run. + description: A task run ID. Only returns runs created after this run. - in: query name: limit schema: @@ -7241,7 +7253,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. + Only returns runs scheduled after this time. - in: query name: beforeTime schema: @@ -7249,7 +7261,7 @@ paths: format: date-time description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. + Only returns runs scheduled before this time. responses: '200': description: Success. The response body contains the list of task runs. @@ -7278,10 +7290,6 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7289,10 +7297,6 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to run. requestBody: content: application/json: @@ -7305,18 +7309,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Run' - '400': - description: Bad request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -7330,7 +7322,7 @@ paths: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -7340,16 +7332,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - that the task run belongs to. + description: The ID of the task to retrieve runs for. - in: path name: runID schema: type: string required: true - description: A task run ID. Specifies the run to retrieve. + description: The ID of the run to retrieve. responses: '200': description: Success. The response body contains the task run. @@ -7398,7 +7387,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). - Use this endpoint to cancel a running task. + Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud @@ -7410,18 +7399,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to cancel. + description: The ID of the task to cancel. - in: path name: runID schema: type: string required: true - description: | - A task run ID. - Specifies the task run to cancel. + description: The ID of the task run to cancel. responses: '204': description: | @@ -7463,15 +7447,15 @@ paths: - Tasks summary: Retry a task run description: | - Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to - retry and then returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/latest/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 - - Queuing a task run requires that the task's `status` property be set to `active`. + - The task must be _active_ (`status: "active"`). requestBody: content: application/json; charset=utf-8: @@ -7485,15 +7469,15 @@ paths: type: string required: true description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. + Specifies the task to retry. - in: path name: runID schema: type: string required: true description: | - A task run ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the @@ -7551,12 +7535,12 @@ paths: operationId: GetTasksIDLogs tags: - Tasks - summary: List logs for a task + summary: Retrieve all logs for a task description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). - When a task runs, InfluxDB creates a `run` record in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. + 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. @@ -7567,12 +7551,11 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve logs for.' + description: The task ID. responses: '200': description: | - Success. - The response body contains an `events` list with logs for the task. + 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: @@ -7581,7 +7564,7 @@ paths: $ref: '#/components/schemas/Logs' examples: taskSuccess: - summary: Events for a successful task run + summary: Events for a successful task run. value: events: - runID: 09b070dadaa7d000 @@ -7591,7 +7574,7 @@ paths: time: '2022-07-18T14:46:07.242859Z' message: Completed(success) taskFailure: - summary: Events for a failed task run + summary: Events for a failed task run. value: events: - runID: 09a946fc3167d000 @@ -7618,12 +7601,12 @@ paths: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: List logs for a run + summary: Retrieve all logs for a run description: | - Lists all logs for a task run. + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7631,13 +7614,13 @@ paths: schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the run belongs to.' + description: The ID of the task to get logs for. - in: path name: runID schema: type: string required: true - description: A run ID. Specifies the task run to list logs for. + description: The ID of the run to get logs for. responses: '200': description: | @@ -7689,12 +7672,9 @@ paths: - Tasks summary: List labels for a task description: | - Lists all labels for a task. + Retrieves a list of all labels for a task. - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Labels may be used for grouping and filtering tasks. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7702,9 +7682,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the task to retrieve labels for. + 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. @@ -7728,12 +7706,9 @@ paths: - Tasks summary: Add a label to a task description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Adds a label to a task. - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + 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 @@ -7741,12 +7716,9 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. + description: The ID of the task to label. requestBody: - description: | - In the request body, provide an object that specifies the label. + description: An object that contains a _`labelID`_ to add to the task. required: true content: application/json: @@ -7754,7 +7726,7 @@ paths: $ref: '#/components/schemas/LabelMapping' responses: '201': - description: Success. The response body contains the label. + description: Success. The response body contains a list of all labels for the task. content: application/json: schema: @@ -7776,7 +7748,7 @@ paths: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Deletes a label from a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7784,17 +7756,13 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. + description: The ID of the task to delete the label from. - in: path name: labelID schema: type: string required: true - description: | - A label ID. - Specifies the label to delete. + description: The ID of the label to delete. responses: '204': description: Success. The label is deleted. @@ -7825,7 +7793,7 @@ paths: 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/latest/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -7834,7 +7802,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) parameters: - $ref: '#/components/parameters/TraceSpan' responses: @@ -7965,9 +7933,7 @@ paths: 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/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -7975,16 +7941,12 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. + description: The task ID. responses: '200': description: | Success. The response body contains a list of `users` that have the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -8003,10 +7965,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns - the member. + Adds a user to members of a task and returns the member. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8014,12 +7975,9 @@ paths: schema: type: string required: true - description: | - A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. - Specifies the task for the member. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as a member of the task. required: true content: application/json: @@ -8027,10 +7985,7 @@ paths: $ref: '#/components/schemas/AddResourceMemberRequestBody' responses: '201': - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. + description: Created. The user is added to task members. content: application/json: schema: @@ -8050,9 +8005,7 @@ paths: 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/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8060,16 +8013,16 @@ paths: schema: type: string required: true - description: A user ID. Specifies the member to remove. + description: The ID of the member to remove. - in: path name: taskID schema: type: string required: true - description: 'A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the member from.' + description: The task ID. responses: '204': - description: Success. The member is removed. + description: Member removed default: description: Unexpected error content: @@ -8085,9 +8038,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `owner` role for the specified task. + Retrieves all users that have owner permission for a task. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8095,7 +8048,7 @@ paths: schema: type: string required: true - description: A task ID. Specifies the task to retrieve owners for. + description: The ID of the task to retrieve owners for. responses: '200': description: | @@ -8137,10 +8090,9 @@ paths: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to owners of the specified task and then returns the - owner. + 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. @@ -8151,12 +8103,9 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as an owner of the task. required: true content: application/json: @@ -8214,9 +8163,7 @@ paths: 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. - - Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -8224,18 +8171,16 @@ paths: schema: type: string required: true - description: 'A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task).' + description: The ID of the owner to remove. - in: path name: taskID schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. + description: The task ID. responses: '204': - description: Success. The owner is removed. + description: Owner removed default: description: Unexpected error content: @@ -9330,352 +9275,6 @@ paths: 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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token](https://docs.influxdata.com/influxdb/latest/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/latest/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/latest/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/latest/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/latest/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/latest/security/tokens/view-tokens/) - externalDocs: - url: 'https://docs.influxdata.com/influxdb/latest/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' /debug/pprof/all: get: operationId: GetDebugPprofAllProfiles @@ -10890,6 +10489,216 @@ paths: default: description: Unexpected error $ref: '#/components/responses/GeneralServerError' + /authorizations: + get: + operationId: GetAuthorizations + tags: + - Authorizations + - 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 OSS + + - InfluxDB OSS returns + [API token](https://docs.influxdata.com/influxdb/latest/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. + + #### Required permissions + + - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. + + #### Related guides + + - [View tokens](https://docs.influxdata.com/influxdb/latest/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/latest/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/latest/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/latest/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/latest/reference/glossary/#organization). + responses: + '200': + description: Success. The response body contains a list of authorizations. + 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 + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token](https://docs.influxdata.com/influxdb/latest/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 response contains the new authorization with the generated API token. + + #### Limitations + + To follow best practices for secure API token generation and retrieval, + InfluxDB enforces access restrictions on API tokens. + + - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any + user with an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. + - You can't update an authorization's permissions. + - Even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + - A token stops working when the user who created the authorization is deleted. + + We recommend creating a generic user to create and manage tokens for writing data. + + #### Related guides + + - [Create a token](https://docs.influxdata.com/influxdb/latest/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 + - Security and access endpoints + summary: Retrieve an authorization + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to get. + responses: + '200': + description: Authorization details + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + summary: Update an authorization to be active or inactive + requestBody: + description: Authorization 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: The ID of the authorization to update. + responses: + '200': + description: The active or inactive authorization + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' + delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + summary: Delete an authorization + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: authID + schema: + type: string + required: true + description: The ID of the authorization to delete. + responses: + '204': + description: Authorization deleted + default: + description: Unexpected error + $ref: '#/components/responses/GeneralServerError' /variables: get: operationId: GetVariables @@ -12466,7 +12275,7 @@ paths: - Tasks summary: List tasks description: | - Lists [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/latest/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`. @@ -12479,9 +12288,8 @@ paths: - in: query name: name description: | - A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - that have the specified name. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. schema: type: string @@ -12490,30 +12298,29 @@ paths: schema: type: string description: | - A task ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) created after the specified task. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. + Only returns tasks created after the specified task. - in: query name: user schema: type: string description: | - A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - owned by the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + A [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. - in: query name: org schema: type: string description: | - An organization name. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. - in: query name: orgID schema: type: string description: | - An organization ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. - in: query name: status schema: @@ -12522,8 +12329,8 @@ paths: - active - inactive description: | - A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified status. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). - in: query name: limit schema: @@ -12541,9 +12348,9 @@ paths: - in: query name: type description: | - A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the response. + A [task](https://docs.influxdata.com/influxdb/latest/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 @@ -12647,9 +12454,7 @@ paths: - Tasks summary: Create a task description: | - Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a script. + Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. #### Related guides @@ -12660,20 +12465,12 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' requestBody: - description: | - In the request body, provide the task. - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. + description: The task to create. required: true content: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' responses: '201': description: Success. The response body contains a `tasks` list with the task. @@ -12695,12 +12492,12 @@ paths: $ref: '#/components/schemas/Error' examples: orgProvidedNotFound: - summary: The organization specified by org or orgID doesn't own the token passed in the header + 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' missingFluxError: - summary: The request body doesn't contain a Flux query + summary: Task in request body is missing Flux query value: code: invalid message: 'failed to decode request: missing flux' @@ -12714,6 +12511,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' + x-codeSamples: + - lang: Shell + label: 'cURL: create a task' + source: | + curl http://localhost:8086/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 '/tasks/{taskID}': get: operationId: GetTasksID @@ -12722,7 +12537,7 @@ paths: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12730,9 +12545,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve. + description: The ID of the task to retrieve. responses: '200': description: Success. The response body contains the task. @@ -12756,27 +12569,21 @@ paths: - Tasks summary: Update a task description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task), - and then cancels all scheduled runs of the task. + Updates a 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`. + Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - #### Related guides - - - [Update a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) + 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. requestBody: - description: | - In the request body, provide the task properties to update. + description: An object that contains updated task properties to apply. required: true content: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' parameters: - $ref: '#/components/parameters/TraceSpan' - in: path @@ -12784,9 +12591,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task)to update. + description: The ID of the task to update. responses: '200': description: Success. The response body contains the updated task. @@ -12810,13 +12615,12 @@ paths: - Tasks summary: Delete a task description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + Deletes a 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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status - to `inactive`. + 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 @@ -12824,9 +12628,7 @@ paths: schema: type: string required: true - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete. + description: The ID of the task to delete. responses: '204': description: Success. The task and runs are deleted. Scheduled runs are canceled. @@ -13612,7 +13414,7 @@ components: AuthorizationUpdateRequest: properties: status: - description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' default: active type: string enum: @@ -13853,7 +13655,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds Link: @@ -15169,44 +14971,6 @@ components: Default is the server _now_ time. type: string format: date-time - TaskCron: - 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 - format: cron - TaskDescription: - description: A description of the task. - type: string - TaskEvery: - description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/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 - TaskFlux: - description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) - type: string - format: Flux - TaskName: - description: The name of the task. - type: string - TaskOffset: - 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 - TaskOrg: - description: | - An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. - type: string - TaskOrgID: - description: | - An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. - type: string TaskStatusType: type: string enum: @@ -19065,25 +18829,31 @@ components: id: readOnly: true type: string - description: | - The resource ID that InfluxDB uses to uniquely identify the task. orgID: - $ref: '#/components/schemas/TaskOrgID' + description: | + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: | + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string name: - $ref: '#/components/schemas/TaskName' - description: - $ref: '#/components/schemas/TaskDescription' + description: The name of the task. + type: string ownerID: description: | - A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the task. + A [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + 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: @@ -19091,20 +18861,27 @@ components: authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + 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: - $ref: '#/components/schemas/TaskFlux' + description: The Flux script that the task executes. + type: string + format: flux every: - $ref: '#/components/schemas/TaskEvery' + description: 'The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/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: - $ref: '#/components/schemas/TaskCron' + 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: - $ref: '#/components/schemas/TaskOffset' + 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/latest/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run.' type: string @@ -19160,17 +18937,19 @@ components: type: object properties: orgID: - $ref: '#/components/schemas/TaskOrgID' + description: The ID of the organization that owns this Task. + type: string org: - $ref: '#/components/schemas/TaskOrg' - name: - $ref: '#/components/schemas/TaskName' - description: - $ref: '#/components/schemas/TaskDescription' - flux: - $ref: '#/components/schemas/TaskFlux' + description: The name of the organization that owns this Task. + type: string status: $ref: '#/components/schemas/TaskStatusType' + flux: + description: The Flux script to run for this task. + type: string + description: + description: An optional description of the task. + type: string required: - flux TaskUpdateRequest: @@ -19179,17 +18958,23 @@ components: status: $ref: '#/components/schemas/TaskStatusType' flux: - $ref: '#/components/schemas/TaskFlux' + description: The Flux script that the task runs. + type: string name: - $ref: '#/components/schemas/TaskName' + description: Update the 'name' option in the flux script. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: Update the 'every' option in the flux script. + type: string cron: - $ref: '#/components/schemas/TaskCron' + description: Update the 'cron' option in the flux script. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + description: Update the 'offset' option in the flux script. + type: string description: - $ref: '#/components/schemas/TaskDescription' + description: Update the description of the task. + type: string responses: AuthorizationError: description: | @@ -19319,7 +19104,7 @@ components: 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\")" + 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. securitySchemes: @@ -19357,7 +19142,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides diff --git a/contracts/priv/cloud-priv.yml b/contracts/priv/cloud-priv.yml index f44ab9acf..2697c2137 100644 --- a/contracts/priv/cloud-priv.yml +++ b/contracts/priv/cloud-priv.yml @@ -853,7 +853,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). required: - everySeconds labels: @@ -889,7 +889,7 @@ components: allOf: - properties: status: - description: 'Status of the token. If `inactive`, InfluxDB rejects requests that use the token.' + description: 'Status of the token. If `inactive`, requests using the token will be rejected.' default: active type: string enum: diff --git a/contracts/ref/cloud.yml b/contracts/ref/cloud.yml index aa755cf7d..943ab5808 100644 --- a/contracts/ref/cloud.yml +++ b/contracts/ref/cloud.yml @@ -40,10 +40,10 @@ components: description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. 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\")" + \"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 TaskWithScriptRequest: description: | @@ -387,8 +387,8 @@ components: type: string status: default: active - description: Status of the token. If `inactive`, InfluxDB rejects requests - that use the token. + description: Status of the token. If `inactive`, requests using the token + will be rejected. enum: - active - inactive @@ -2407,23 +2407,22 @@ components: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - properties: orgID: - description: The organization ID. Identifies the organization that the - authorization is scoped to. + description: The ID of the organization that the authorization is scoped + to. type: string permissions: description: | - The list of permissions that provide `read` and `write` access to organization resources. + A list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' minItems: 1 type: array token: - description: The name that you provide for the authorization. + description: A name that you provide for the authorization. type: string userID: - description: The user ID. Identifies the user that the authorization is - scoped to. + description: The ID of the user that the authorization is scoped to. type: string type: object required: @@ -4062,7 +4061,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -4838,7 +4837,7 @@ components: authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + 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 @@ -4849,16 +4848,28 @@ components: readOnly: true type: string cron: - $ref: '#/components/schemas/TaskCron' + 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 description: - $ref: '#/components/schemas/TaskDescription' + description: A description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + 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. + format: duration + type: string flux: - $ref: '#/components/schemas/TaskFlux' - id: description: | - The resource ID that InfluxDB uses to uniquely identify the task. + The Flux script that the task executes. + + #### Limitations + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + format: flux + type: string + id: readOnly: true type: string labels: @@ -4903,26 +4914,58 @@ components: readOnly: true type: object name: - $ref: '#/components/schemas/TaskName' + description: The name of the task. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + 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. + format: duration + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: | + An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string orgID: - $ref: '#/components/schemas/TaskOrgID' + description: | + An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string ownerID: description: | - A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) that owns the task. + A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + To find a user ID, you can use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + 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: - $ref: '#/components/schemas/TaskScriptParameters' + 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 status: $ref: '#/components/schemas/TaskStatusType' updatedAt: @@ -4937,97 +4980,60 @@ components: TaskCreateRequest: properties: cron: - $ref: '#/components/schemas/TaskCron' + 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 description: - $ref: '#/components/schemas/TaskDescription' + description: The description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + 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 flux: - $ref: '#/components/schemas/TaskFlux' + 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 name: - $ref: '#/components/schemas/TaskName' + description: The name of the task + type: string offset: - $ref: '#/components/schemas/TaskOffset' + 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. + format: duration + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: The name of the organization that owns the task. + type: string orgID: - $ref: '#/components/schemas/TaskOrgID' + description: The ID of the organization that owns the task. + type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' - scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' - status: - $ref: '#/components/schemas/TaskStatusType' - type: object - TaskCron: - 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. - format: cron - type: string - TaskDescription: - description: A description of the task. - type: string - TaskEvery: - 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. - format: duration - type: string - TaskFlux: - description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - format: Flux - type: string - TaskName: - description: The name of the task. - type: string - TaskOffset: - 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. - format: duration - type: string - TaskOrg: - description: | - An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. - type: string - TaskOrgID: - description: | - An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) that owns the task. - type: string - TaskScriptID: - description: | - A script ID. - Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. - - #### 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 - TaskScriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified - by the `scriptID` property. - When running the task, InfluxDB executes the script with the parameters - you provide. + description: | + The ID of the script that the task runs. - #### Limitations + #### Limitations - - To use the `scriptParameters` property, you must also set the `scriptID` property - for the task. + - 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. - #### Related guides + #### Limitations - - [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). + - `scriptParameters` requires `scriptID`. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. + type: object + status: + $ref: '#/components/schemas/TaskStatusType' type: object TaskStatusType: description: | @@ -5039,21 +5045,29 @@ components: TaskUpdateRequest: properties: cron: - $ref: '#/components/schemas/TaskCron' + description: Update the 'cron' option in the flux script. + type: string description: - $ref: '#/components/schemas/TaskDescription' + description: Update the description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: Update the 'every' option in the flux script. + type: string flux: - $ref: '#/components/schemas/TaskFlux' + description: Update the Flux script that the task runs. + type: string name: - $ref: '#/components/schemas/TaskName' + description: Update the 'name' option in the flux script. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + description: Update the 'offset' option in the flux script. + type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + description: Update the 'scriptID' of the task. + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + description: Update the 'scriptParameters' of the task. + type: object status: $ref: '#/components/schemas/TaskStatusType' type: object @@ -6772,7 +6786,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides @@ -6818,7 +6832,7 @@ paths: Lists authorizations. To limit which authorizations are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all authorizations. + If no query parameters are passed, InfluxDB returns all authorizations for the organization. #### InfluxDB Cloud @@ -6828,11 +6842,7 @@ paths: #### 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 @@ -6842,46 +6852,39 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + Only returns authorizations scoped to the specified + [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + 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: An organization ID. Only returns authorizations that belong to - the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + - 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: orgID 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). + 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 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. + Returns the authorization for the specified token. in: query name: token schema: @@ -6892,19 +6895,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorizations' - 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. + description: Success. The response body contains a list of authorizations. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6917,8 +6908,7 @@ paths: description: Unexpected error summary: List authorizations tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations post: description: | Creates an authorization and returns the authorization with the @@ -6926,24 +6916,20 @@ paths: 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. + + #### Limitations To follow best practices for secure API token generation and retrieval, - InfluxDB enforces access restrictions on API tokens. + InfluxDB Cloud 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. + - InfluxDB only allows access to the API token value immediately after the authorization is created. + - You can't update an authorization's permissions. + - A token stops working when the user who created the authorization 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 + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. #### Related guides @@ -6972,8 +6958,7 @@ paths: schema: $ref: '#/components/schemas/Authorization' description: | - Success. The authorization is created. The response body contains the - authorization. + Success. The authorization is created. The response body contains the authorization. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6986,21 +6971,13 @@ paths: description: Unexpected error summary: Create an authorization tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations /api/v2/authorizations/{authID}: delete: - 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). operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to delete. + - description: The identifier of the authorization to delete. in: path name: authID required: true @@ -7008,70 +6985,18 @@ paths: type: string responses: "204": - description: Success. The authorization is deleted. - "400": - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - "401": - $ref: '#/components/responses/AuthorizationError' - "404": - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - "500": - $ref: '#/components/responses/InternalServerError' + description: Authorization deleted default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations get: - 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: - description: View tokens - url: https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/ operationId: GetAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to retrieve. + - description: The identifier of the authorization to get. in: path name: authID required: true @@ -7083,56 +7008,19 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the authorization. - "400": - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - "401": - $ref: '#/components/responses/AuthorizationError' - "404": - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - "500": - $ref: '#/components/responses/InternalServerError' + description: Authorization details default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations patch: - 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. + description: Update an authorization's status to `active` or `inactive`. operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to update. + - description: The identifier of the authorization to update. in: path name: authID required: true @@ -7143,8 +7031,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: In the request body, provide the authorization properties to - update. + description: The updated Authorization object. required: true responses: "200": @@ -7152,14 +7039,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the updated authorization. + description: The updated authorization. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: Update an API token to be active or inactive + summary: Update authorization status tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations /api/v2/buckets: get: description: | @@ -8163,7 +8049,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -8179,7 +8065,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -8244,7 +8130,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -8259,7 +8145,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -8345,7 +8231,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -8361,7 +8247,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -10509,7 +10395,7 @@ paths: 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). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/cloud/influxdb/v2.4/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. @@ -10518,7 +10404,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/cloud/influxdb/v2.4/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11820,7 +11706,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -11918,7 +11804,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12017,7 +11903,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12078,7 +11964,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -12140,7 +12026,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -12150,7 +12036,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12224,7 +12110,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12239,7 +12125,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15271,56 +15157,52 @@ paths: /api/v2/tasks: get: description: | - Lists [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + 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`. - - #### Related guide - - - [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/cloud/process-data/) operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) with the specified name. + 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. in: query name: name schema: type: string - description: | - A task ID. - Only returns [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) created after the specified task. + A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. + Only returns tasks created after the specified task. in: query name: after schema: type: string - description: | - A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user). + A [user](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. in: query name: user schema: type: string - description: | - An organization name. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. in: query name: org schema: type: string - description: | - An organization ID. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization). + An [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. in: query name: orgID schema: type: string - description: | - A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that have the specified status. + 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: status schema: @@ -15358,11 +15240,8 @@ paths: minimum: 0 type: integer - description: | - The sort field. - Specifies the task property used to sort records in the list. - Default is `name`. - - The parameter has one supported value: `name`. + The sort field. Only `name` is supported. + Specifies the field used to sort records in the list. in: query name: sortBy required: false @@ -15371,13 +15250,11 @@ paths: - name type: string - description: | - A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) in the response. + 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, set the `type` parameter to `basic` (`type=basic`) - to omit some task properties (`flux`, `createdAt`, `updatedAt`). + To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). in: query name: type required: false @@ -15388,8 +15265,8 @@ paths: - system type: string - description: | - A script ID. - Only returns tasks that use the specified [invokable script](#tag/Invokable-Scripts). + A [script](#tag/Invokable-Scripts) ID. + Only returns tasks that use the specified invokable script. in: query name: scriptID schema: @@ -15474,7 +15351,7 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: List tasks + summary: List all tasks tags: - Data I/O endpoints - Tasks @@ -15489,7 +15366,52 @@ paths: 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 script. + 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 @@ -15503,35 +15425,9 @@ paths: requestBody: content: application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' schema: $ref: '#/components/schemas/TaskCreateRequest' - description: | - In the request body, provide the task. - - Set one of the following properties to provide the script that the task runs: - - `flux` - - `scriptID` - - If you set the `scriptID` property, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, you must provide the `task` configuration option - in the Flux script. - - See [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't use `flux` and `scriptID` in the same task. + description: The task to create required: true responses: "201": @@ -15540,7 +15436,7 @@ paths: schema: $ref: '#/components/schemas/Task' description: Success. The response body contains a `tasks` list with the - task. + new task. "400": content: application/json: @@ -15565,10 +15461,8 @@ paths: #### InfluxDB Cloud - - Returns this error if the task doesn't contain the `flux` property - or the `scriptID` property. - - Returns this error if the task contains `flux` _and_ `scriptID` - properties. + - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_. + - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_. "401": $ref: '#/components/responses/AuthorizationError' "500": @@ -15583,22 +15477,58 @@ paths: tags: - Data I/O endpoints - Tasks + x-codeSamples: + - label: 'cURL: create a Flux script task' + lang: Shell + 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 + - label: 'cURL: create a Flux script reference task' + lang: Shell + 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 /api/v2/tasks/{taskID}: delete: description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + 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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` - property to `inactive`. + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). operationId: DeleteTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete. + - description: A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) + ID. Specifies the task to delete. in: path name: taskID required: true @@ -15623,13 +15553,13 @@ paths: - Tasks get: description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve. + A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to retrieve. in: path name: taskID required: true @@ -15658,25 +15588,66 @@ paths: - Tasks patch: description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task), + 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. - The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. - #### Related guides + #### InfluxDB Cloud - - [Update a task](https://docs.influxdata.com/influxdb/cloud/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) + - 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. operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to update. + A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to update. in: path name: taskID required: true @@ -15685,35 +15656,9 @@ paths: requestBody: content: application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: | - In the request body, provide the task properties to update. - To provide the script that the task runs, - set either the `flux` property or the `scriptID` property. - - If you set `scriptID`, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, provide the `task` configuration option - in the Flux script. - - See [task configuration options](https://docs.influxdata.com/influxdb/cloud/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't set `flux` and `scriptID` properties for the same task--for - example, if you set the `scriptID` property, then InfluxDB sets the `flux` property - to an empty string (`""`). + description: An task update to apply. required: true responses: "200": @@ -15738,18 +15683,13 @@ paths: /api/v2/tasks/{taskID}/labels: get: description: | - Lists all labels for a task. + Retrieves a list of all labels for a task. - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Labels may be used for grouping and filtering tasks. operationId: GetTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the task to retrieve labels for. + - description: The ID of the task to retrieve labels for. in: path name: taskID required: true @@ -15778,18 +15718,13 @@ paths: - Tasks post: description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Adds a label to a task. - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. operationId: PostTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to label. + - description: The ID of the task to label. in: path name: taskID required: true @@ -15800,8 +15735,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelMapping' - description: | - In the request body, provide an object that specifies the label. + description: An object that contains a _`labelID`_ to add to the task. required: true responses: "201": @@ -15809,7 +15743,8 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the label. + description: Success. The response body contains a list of all labels for + the task. "400": $ref: '#/components/responses/BadRequestError' "401": @@ -15826,21 +15761,17 @@ paths: /api/v2/tasks/{taskID}/labels/{labelID}: delete: description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Deletes a label from a task. operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to delete the label from. + - description: The ID of the task to delete the label from. in: path name: taskID required: true schema: type: string - - description: | - A label ID. - Specifies the label to delete. + - description: The ID of the label to delete. in: path name: labelID required: true @@ -15865,18 +15796,17 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - When a task runs, InfluxDB creates a `run` record in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. + 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. operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - to retrieve logs for. + - description: The task ID. in: path name: taskID required: true @@ -15888,7 +15818,7 @@ paths: application/json: examples: taskFailure: - summary: Events for a failed task run + summary: Events for a failed task run. value: events: - message: 'Started task from script: "option task = {name: \"test @@ -15905,7 +15835,7 @@ paths: runID: 09a946fc3167d000 time: "2022-07-13T08:24:37.115323Z" taskSuccess: - summary: Events for a successful task run + summary: Events for a successful task run. value: events: - message: 'Started task from script: "option task = {name: \"task1\", @@ -15920,8 +15850,7 @@ paths: schema: $ref: '#/components/schemas/Logs' description: | - Success. - The response body contains an `events` list with logs for the task. + 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. "400": @@ -15934,7 +15863,7 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: List logs for a task + summary: Retrieve all logs for a task tags: - Tasks /api/v2/tasks/{taskID}/members: @@ -15942,15 +15871,11 @@ paths: deprecated: true 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). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to retrieve members for. + - description: The task ID. in: path name: taskID required: true @@ -15965,8 +15890,6 @@ paths: description: | Success. The response body contains a list of `users` that have the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. default: content: application/json: @@ -15980,16 +15903,13 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) and then returns - the member. + Adds a user to members of a task and returns the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task for the member. + - description: The task ID. in: path name: taskID required: true @@ -16000,8 +15920,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. + description: A user to add as a member of the task. required: true responses: "201": @@ -16009,10 +15928,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceMember' - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. + description: Created. The user is added to task members. default: content: application/json: @@ -16027,20 +15943,17 @@ paths: deprecated: true 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). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the member to remove. + - description: The ID of the member to remove. in: path name: userID required: true schema: type: string - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - to remove the member from. + - description: The task ID. in: path name: taskID required: true @@ -16048,7 +15961,7 @@ paths: type: string responses: "204": - description: Success. The member is removed. + description: Member removed default: content: application/json: @@ -16063,13 +15976,13 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `owner` role for the specified task. + Retrieves all users that have owner permission for a task. operationId: GetTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the task to retrieve owners for. + - description: The ID of the task to retrieve owners for. in: path name: taskID required: true @@ -16115,19 +16028,16 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to owners of the specified task and then returns the - owner. + 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. operationId: PostTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) for the owner. + - description: The task ID. in: path name: taskID required: true @@ -16138,8 +16048,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. + description: A user to add as an owner of the task. required: true responses: "201": @@ -16192,21 +16101,17 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes an owner from a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + - description: The ID of the owner to remove. in: path name: userID required: true schema: type: string - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to remove the owner from. + - description: The task ID. in: path name: taskID required: true @@ -16214,7 +16119,7 @@ paths: type: string responses: "204": - description: Success. The owner is removed. + description: Owner removed default: content: application/json: @@ -16227,25 +16132,22 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/cloud/process-data/). + 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 you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. operationId: GetTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to - to list runs for. + The ID of the task to get runs for. + Only returns runs for this task. in: path name: taskID required: true schema: type: string - - description: A task run ID. Only returns runs created after the specified - run. + - description: A task run ID. Only returns runs created after this run. in: query name: after schema: @@ -16261,7 +16163,7 @@ paths: type: integer - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. + Only returns runs scheduled after this time. in: query name: afterTime schema: @@ -16269,7 +16171,7 @@ paths: type: string - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. + Only returns runs scheduled before this time. in: query name: beforeTime schema: @@ -16301,18 +16203,10 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. operationId: PostTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to - to run. - in: path + - in: path name: taskID required: true schema: @@ -16329,18 +16223,6 @@ paths: schema: $ref: '#/components/schemas/Run' description: Success. The run is scheduled to start. - "400": - content: - application/json: - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: Bad request. "401": $ref: '#/components/responses/AuthorizationError' "500": @@ -16356,7 +16238,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). - Use this endpoint to cancel a running task. + Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud @@ -16364,18 +16246,13 @@ paths: operationId: DeleteTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) to - to cancel. + - description: The ID of the task to cancel. in: path name: taskID required: true schema: type: string - - description: | - A task run ID. - Specifies the task run to cancel. + - description: The ID of the task run to cancel. in: path name: runID required: true @@ -16420,22 +16297,19 @@ paths: - Tasks get: description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task). + 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. operationId: GetTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - that the task run belongs to. + - description: The ID of the task to retrieve runs for. in: path name: taskID required: true schema: type: string - - description: A task run ID. Specifies the run to retrieve. + - description: The ID of the run to retrieve. in: path name: runID required: true @@ -16490,21 +16364,20 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/logs: get: description: | - Lists all logs for a task run. + 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](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) - that the run belongs to. + - description: The ID of the task to get logs for. in: path name: taskID required: true schema: type: string - - description: A run ID. Specifies the task run to list logs for. + - description: The ID of the run to get logs for. in: path name: runID required: true @@ -16561,34 +16434,34 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: List logs for a run + summary: Retrieve all logs for a run tags: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) run to - retry and then returns the scheduled run. + 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 - - Queuing a task run requires that the task's `status` property be set to `active`. + - The task must be _active_ (`status: "active"`). operationId: PostTasksIDRunsIDRetry parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) that the task run belongs to. + A [task](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to retry. in: path name: taskID required: true schema: type: string - description: | - A task run ID. + 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 @@ -18991,12 +18864,24 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. + In InfluxDB Cloud, an authorization with `read-authorizations` permission + can be used to view other authorizations. + + #### Limitations + + 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. - ### User sessions with authorizations + #### 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_, @@ -19014,7 +18899,7 @@ tags: - [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: Authorizations (API tokens) + name: Authorizations - 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 @@ -19058,7 +18943,7 @@ tags: 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 + #### 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) @@ -19087,7 +18972,7 @@ tags: - ### Properties + #### Properties A `task` object contains information about an InfluxDB task resource. @@ -19095,7 +18980,7 @@ tags: - ### Related guides + #### 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/) @@ -19118,7 +19003,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - ### Related guides + #### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/) @@ -19133,14 +19018,14 @@ tags: `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to view specific members. - ### User sessions with authorizations + #### 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 + #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/cloud/organizations/users/) name: Users @@ -19215,7 +19100,7 @@ tags: | `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 + #### 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, diff --git a/contracts/ref/oss.yml b/contracts/ref/oss.yml index 50ba67a64..60a92ce9f 100644 --- a/contracts/ref/oss.yml +++ b/contracts/ref/oss.yml @@ -40,10 +40,10 @@ components: description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. 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\")" + \"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 parameters: After: @@ -372,8 +372,8 @@ components: type: string status: default: active - description: Status of the token. If `inactive`, InfluxDB rejects requests - that use the token. + description: Status of the token. If `inactive`, requests using the token + will be rejected. enum: - active - inactive @@ -2426,23 +2426,22 @@ components: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - properties: orgID: - description: The organization ID. Identifies the organization that the - authorization is scoped to. + description: The ID of the organization that the authorization is scoped + to. type: string permissions: description: | - The list of permissions that provide `read` and `write` access to organization resources. + A list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' minItems: 1 type: array token: - description: The name that you provide for the authorization. + description: A name that you provide for the authorization. type: string userID: - description: The user ID. Identifies the user that the authorization is - scoped to. + description: The ID of the user that the authorization is scoped to. type: string type: object required: @@ -4018,7 +4017,7 @@ components: #### InfluxDB OSS - Default value depends on the - [bucket retention period](https://docs.influxdata.com/influxdb/latest/reference/internals/shards/#shard-group-duration). + [bucket retention period](https://docs.influxdata.com/influxdb/latest/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -4917,7 +4916,7 @@ components: authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + 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 @@ -4928,16 +4927,24 @@ components: readOnly: true type: string cron: - $ref: '#/components/schemas/TaskCron' + 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 description: - $ref: '#/components/schemas/TaskDescription' + description: A description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) + at which the task runs. `every` also determines when the task first runs, + depending on the specified time. + format: duration + type: string flux: - $ref: '#/components/schemas/TaskFlux' + description: The Flux script that the task executes. + format: flux + type: string id: - description: | - The resource ID that InfluxDB uses to uniquely identify the task. readOnly: true type: string labels: @@ -4982,19 +4989,30 @@ components: readOnly: true type: object name: - $ref: '#/components/schemas/TaskName' + description: The name of the task. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + 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. + format: duration + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: | + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string orgID: - $ref: '#/components/schemas/TaskOrgID' + description: | + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string ownerID: description: | - A user ID. - Identifies the [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) that owns the task. + A [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + To find a user ID, you can use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string @@ -5013,64 +5031,22 @@ components: TaskCreateRequest: properties: description: - $ref: '#/components/schemas/TaskDescription' + description: An optional description of the task. + type: string flux: - $ref: '#/components/schemas/TaskFlux' - name: - $ref: '#/components/schemas/TaskName' + description: The Flux script to run for this task. + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: The name of the organization that owns this Task. + type: string orgID: - $ref: '#/components/schemas/TaskOrgID' + description: The ID of the organization that owns this Task. + type: string status: $ref: '#/components/schemas/TaskStatusType' required: - flux type: object - TaskCron: - 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. - format: cron - type: string - TaskDescription: - description: A description of the task. - type: string - TaskEvery: - description: The interval ([duration literal](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)) - at which the task runs. `every` also determines when the task first runs, - depending on the specified time. - format: duration - type: string - TaskFlux: - description: | - Flux with [task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) - format: Flux - type: string - TaskName: - description: The name of the task. - type: string - TaskOffset: - 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. - format: duration - type: string - TaskOrg: - description: | - An organization name. - Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. - type: string - TaskOrgID: - description: | - An organization ID. - Identifies the [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) that owns the task. - type: string TaskStatusType: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. @@ -5081,17 +5057,23 @@ components: TaskUpdateRequest: properties: cron: - $ref: '#/components/schemas/TaskCron' + description: Update the 'cron' option in the flux script. + type: string description: - $ref: '#/components/schemas/TaskDescription' + description: Update the description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: Update the 'every' option in the flux script. + type: string flux: - $ref: '#/components/schemas/TaskFlux' + description: The Flux script that the task runs. + type: string name: - $ref: '#/components/schemas/TaskName' + description: Update the 'name' option in the flux script. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + description: Update the 'offset' option in the flux script. + type: string status: $ref: '#/components/schemas/TaskStatusType' type: object @@ -6805,7 +6787,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides @@ -6853,19 +6835,16 @@ paths: 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 OSS - - InfluxDB Cloud doesn't expose [API token](https://docs.influxdata.com/influxdb/latest/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. + - InfluxDB OSS returns + [API token](https://docs.influxdata.com/influxdb/latest/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. #### 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 + - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. #### Related guides @@ -6900,44 +6879,13 @@ paths: name: org schema: type: string - - description: | - An API [token](https://docs.influxdata.com/influxdb/latest/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. - in: query - name: token - schema: - type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/Authorizations' - 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/latest/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. + description: Success. The response body contains a list of authorizations. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -6950,7 +6898,7 @@ paths: description: Unexpected error summary: List authorizations tags: - - Authorizations (API tokens) + - Authorizations - Security and access endpoints post: description: | @@ -6959,24 +6907,21 @@ paths: 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. + The response contains the new authorization with the generated API token. + + #### Limitations 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: + - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any + user with an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. + - You can't update an authorization's permissions. + - Even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + - A token stops working when the user who created the authorization is deleted. - - 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 + We recommend creating a generic user to create and manage tokens for writing data. #### Related guides @@ -7005,8 +6950,7 @@ paths: schema: $ref: '#/components/schemas/Authorization' description: | - Success. The authorization is created. The response body contains the - authorization. + Success. The authorization is created. The response body contains the authorization. "400": $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -7019,21 +6963,13 @@ paths: description: Unexpected error summary: Create an authorization tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations /api/v2/authorizations/{authID}: delete: - 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). operationId: DeleteAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to delete. + - description: The ID of the authorization to delete. in: path name: authID required: true @@ -7041,70 +6977,18 @@ paths: type: string responses: "204": - description: Success. The authorization is deleted. - "400": - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - "401": - $ref: '#/components/responses/AuthorizationError' - "404": - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - "500": - $ref: '#/components/responses/InternalServerError' + description: Authorization deleted default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Delete an authorization tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations get: - 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/latest/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/latest/security/tokens/view-tokens/) - externalDocs: - description: View tokens - url: https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/ operationId: GetAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to retrieve. + - description: The ID of the authorization to get. in: path name: authID required: true @@ -7116,56 +7000,19 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the authorization. - "400": - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - "401": - $ref: '#/components/responses/AuthorizationError' - "404": - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - "500": - $ref: '#/components/responses/InternalServerError' + description: Authorization details default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error summary: Retrieve an authorization tags: - - Authorizations (API tokens) + - Authorizations - Security and access endpoints patch: - 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. operationId: PatchAuthorizationsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to update. + - description: The ID of the authorization to update. in: path name: authID required: true @@ -7176,8 +7023,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: In the request body, provide the authorization properties to - update. + description: Authorization to update required: true responses: "200": @@ -7185,14 +7031,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the updated authorization. + description: The active or inactive authorization default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: Update an API token to be active or inactive + summary: Update an authorization to be active or inactive tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations /api/v2/backup/kv: get: deprecated: true @@ -8330,7 +8175,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -8346,7 +8191,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -8411,7 +8256,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -8426,7 +8271,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -8512,7 +8357,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -8528,7 +8373,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -11043,7 +10888,7 @@ paths: 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/latest/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/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. @@ -11052,7 +10897,7 @@ paths: #### Related guides - - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/reference/config-options/) + - [InfluxDB configuration options](https://docs.influxdata.com/influxdb/latest/influxdb/v2.4/reference/config-options/) operationId: GetFlags parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12409,7 +12254,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12507,7 +12352,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12606,7 +12451,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12667,7 +12512,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -12729,7 +12574,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -12739,7 +12584,7 @@ paths: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) operationId: PostOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12813,7 +12658,7 @@ paths: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -12828,7 +12673,7 @@ paths: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16316,7 +16161,7 @@ paths: /api/v2/tasks: get: description: | - Lists [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a list of [tasks](https://docs.influxdata.com/influxdb/latest/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`. @@ -16328,46 +16173,44 @@ paths: parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task name. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - that have the specified name. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. in: query name: name schema: type: string - description: | - A task ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) created after the specified task. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. + Only returns tasks created after the specified task. in: query name: after schema: type: string - description: | - A user ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - owned by the specified [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user). + A [user](https://docs.influxdata.com/influxdb/latest/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. in: query name: user schema: type: string - description: | - An organization name. - Only returns tasks owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. in: query name: org schema: type: string - description: | - An organization ID. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) owned by the specified [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization). + An [organization](https://docs.influxdata.com/influxdb/latest/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. in: query name: orgID schema: type: string - description: | - A task status. - Only returns [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that have the specified status. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). in: query name: status schema: @@ -16390,9 +16233,9 @@ paths: minimum: 1 type: integer - description: | - A task type. - Specifies the level of detail for [tasks](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) in the response. + A [task](https://docs.influxdata.com/influxdb/latest/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`). in: query @@ -16497,9 +16340,7 @@ paths: --header 'Authorization: Token INFLUX_API_TOKEN' post: description: | - Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a script. + Creates a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and returns the task. #### Related guides @@ -16513,17 +16354,9 @@ paths: requestBody: content: application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' schema: $ref: '#/components/schemas/TaskCreateRequest' - description: | - In the request body, provide the task. - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. + description: The task to create. required: true responses: "201": @@ -16538,13 +16371,13 @@ paths: application/json: examples: missingFluxError: - summary: The request body doesn't contain a Flux query + summary: Task in request body is missing Flux query value: code: invalid message: 'failed to decode request: missing flux' orgProvidedNotFound: - summary: The organization specified by org or orgID doesn't own - the token passed in the header + 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' @@ -16571,22 +16404,37 @@ paths: tags: - Data I/O endpoints - Tasks + x-codeSamples: + - label: 'cURL: create a task' + lang: Shell + source: | + curl http://localhost:8086/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 /api/v2/tasks/{taskID}: delete: description: | - Deletes the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + Deletes a 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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status - to `inactive`. + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). operationId: DeleteTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete. + - description: The ID of the task to delete. in: path name: taskID required: true @@ -16611,13 +16459,11 @@ paths: - Tasks get: description: | - Retrieves the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve. + - description: The ID of the task to retrieve. in: path name: taskID required: true @@ -16646,22 +16492,18 @@ paths: - Tasks patch: description: | - Updates the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task), - and then cancels all scheduled runs of the task. + Updates a 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`. + Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - #### Related guides - - - [Update a task](https://docs.influxdata.com/influxdb/latest/process-data/manage-tasks/update-task/) - - [Task configuration options](https://docs.influxdata.com/influxdb/latest/process-data/task-options/) + 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. operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task)to update. + - description: The ID of the task to update. in: path name: taskID required: true @@ -16670,13 +16512,9 @@ paths: requestBody: content: application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: | - In the request body, provide the task properties to update. + description: An object that contains updated task properties to apply. required: true responses: "200": @@ -16701,18 +16539,13 @@ paths: /api/v2/tasks/{taskID}/labels: get: description: | - Lists all labels for a task. + Retrieves a list of all labels for a task. - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Labels may be used for grouping and filtering tasks. operationId: GetTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the task to retrieve labels for. + - description: The ID of the task to retrieve labels for. in: path name: taskID required: true @@ -16741,18 +16574,13 @@ paths: - Tasks post: description: | - Adds a label to a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Adds a label to a task. - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. operationId: PostTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to label. + - description: The ID of the task to label. in: path name: taskID required: true @@ -16763,8 +16591,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelMapping' - description: | - In the request body, provide an object that specifies the label. + description: An object that contains a _`labelID`_ to add to the task. required: true responses: "201": @@ -16772,7 +16599,8 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the label. + description: Success. The response body contains a list of all labels for + the task. "400": $ref: '#/components/responses/BadRequestError' "401": @@ -16789,21 +16617,17 @@ paths: /api/v2/tasks/{taskID}/labels/{labelID}: delete: description: | - Deletes a label from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Deletes a label from a task. operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to delete the label from. + - description: The ID of the task to delete the label from. in: path name: taskID required: true schema: type: string - - description: | - A label ID. - Specifies the label to delete. + - description: The ID of the label to delete. in: path name: labelID required: true @@ -16828,18 +16652,17 @@ paths: /api/v2/tasks/{taskID}/logs: get: description: | - Lists all log events for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a list of all logs for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). - When a task runs, InfluxDB creates a `run` record in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. + 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. operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - to retrieve logs for. + - description: The task ID. in: path name: taskID required: true @@ -16851,7 +16674,7 @@ paths: application/json: examples: taskFailure: - summary: Events for a failed task run + summary: Events for a failed task run. value: events: - message: 'Started task from script: "option task = {name: \"test @@ -16868,7 +16691,7 @@ paths: runID: 09a946fc3167d000 time: "2022-07-13T08:24:37.115323Z" taskSuccess: - summary: Events for a successful task run + summary: Events for a successful task run. value: events: - message: 'Started task from script: "option task = {name: \"task1\", @@ -16883,8 +16706,7 @@ paths: schema: $ref: '#/components/schemas/Logs' description: | - Success. - The response body contains an `events` list with logs for the task. + 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. "400": @@ -16897,7 +16719,7 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: List logs for a task + summary: Retrieve all logs for a task tags: - Tasks /api/v2/tasks/{taskID}/members: @@ -16905,15 +16727,11 @@ paths: deprecated: true 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/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to retrieve members for. + - description: The task ID. in: path name: taskID required: true @@ -16928,8 +16746,6 @@ paths: description: | Success. The response body contains a list of `users` that have the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. default: content: application/json: @@ -16943,16 +16759,13 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) and then returns - the member. + Adds a user to members of a task and returns the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. - Specifies the task for the member. + - description: The task ID. in: path name: taskID required: true @@ -16963,8 +16776,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. + description: A user to add as a member of the task. required: true responses: "201": @@ -16972,10 +16784,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceMember' - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. + description: Created. The user is added to task members. default: content: application/json: @@ -16990,20 +16799,17 @@ paths: deprecated: true 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/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the member to remove. + - description: The ID of the member to remove. in: path name: userID required: true schema: type: string - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - to remove the member from. + - description: The task ID. in: path name: taskID required: true @@ -17011,7 +16817,7 @@ paths: type: string responses: "204": - description: Success. The member is removed. + description: Member removed default: content: application/json: @@ -17026,13 +16832,13 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `owner` role for the specified task. + Retrieves all users that have owner permission for a task. operationId: GetTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the task to retrieve owners for. + - description: The ID of the task to retrieve owners for. in: path name: taskID required: true @@ -17078,19 +16884,16 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to owners of the specified task and then returns the - owner. + 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. operationId: PostTasksIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) for the owner. + - description: The task ID. in: path name: taskID required: true @@ -17101,8 +16904,7 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. + description: A user to add as an owner of the task. required: true responses: "201": @@ -17155,21 +16957,17 @@ paths: deprecated: true description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes an owner from a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the owner to remove from the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + - description: The ID of the owner to remove. in: path name: userID required: true schema: type: string - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to remove the owner from. + - description: The task ID. in: path name: taskID required: true @@ -17177,7 +16975,7 @@ paths: type: string responses: "204": - description: Success. The owner is removed. + description: Owner removed default: content: application/json: @@ -17190,25 +16988,22 @@ paths: /api/v2/tasks/{taskID}/runs: get: description: | - Lists runs for the specified [task](https://docs.influxdata.com/influxdb/latest/process-data/). + Retrieves a list of runs for a [task](https://docs.influxdata.com/influxdb/latest/process-data/). To limit which task runs are returned, pass query parameters in your request. - If you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. operationId: GetTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to list runs for. + The ID of the task to get runs for. + Only returns runs for this task. in: path name: taskID required: true schema: type: string - - description: A task run ID. Only returns runs created after the specified - run. + - description: A task run ID. Only returns runs created after this run. in: query name: after schema: @@ -17224,7 +17019,7 @@ paths: type: integer - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. + Only returns runs scheduled after this time. in: query name: afterTime schema: @@ -17232,7 +17027,7 @@ paths: type: string - description: | A timestamp ([RFC3339 date/time format](https://docs.influxdata.com/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. + Only returns runs scheduled before this time. in: query name: beforeTime schema: @@ -17264,18 +17059,10 @@ paths: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. operationId: PostTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to run. - in: path + - in: path name: taskID required: true schema: @@ -17292,18 +17079,6 @@ paths: schema: $ref: '#/components/schemas/Run' description: Success. The run is scheduled to start. - "400": - content: - application/json: - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: Bad request. "401": $ref: '#/components/responses/AuthorizationError' "500": @@ -17319,7 +17094,7 @@ paths: description: | Cancels a running [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). - Use this endpoint to cancel a running task. + Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud @@ -17327,18 +17102,13 @@ paths: operationId: DeleteTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) to - to cancel. + - description: The ID of the task to cancel. in: path name: taskID required: true schema: type: string - - description: | - A task run ID. - Specifies the task run to cancel. + - description: The ID of the task run to cancel. in: path name: runID required: true @@ -17383,22 +17153,19 @@ paths: - Tasks get: description: | - Retrieves the specified run for the specified [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). + Retrieves a specific run for a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - that the task run belongs to. + - description: The ID of the task to retrieve runs for. in: path name: taskID required: true schema: type: string - - description: A task run ID. Specifies the run to retrieve. + - description: The ID of the run to retrieve. in: path name: runID required: true @@ -17453,21 +17220,20 @@ paths: /api/v2/tasks/{taskID}/runs/{runID}/logs: get: description: | - Lists all logs for a task run. + 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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) - that the run belongs to. + - description: The ID of the task to get logs for. in: path name: taskID required: true schema: type: string - - description: A run ID. Specifies the task run to list logs for. + - description: The ID of the run to get logs for. in: path name: runID required: true @@ -17524,34 +17290,34 @@ paths: $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' - summary: List logs for a run + summary: Retrieve all logs for a run tags: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/retry: post: description: | - Queues a [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run to - retry and then returns the scheduled run. + Queues a [task](https://docs.influxdata.com/influxdb/latest/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 - - Queuing a task run requires that the task's `status` property be set to `active`. + - The task must be _active_ (`status: "active"`). operationId: PostTasksIDRunsIDRetry parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - A task ID. - Specifies the [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) that the task run belongs to. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) ID. + Specifies the task to retry. in: path name: taskID required: true schema: type: string - description: | - A task run ID. + A [task](https://docs.influxdata.com/influxdb/latest/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the @@ -19988,9 +19754,23 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. + #### Limitations + + 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. + + API tokens are visible to the user who created the authorization and to any + user with an _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. + In InfluxDB OSS, even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + We recommend creating a generic user to create and manage tokens for writing data. - ### User sessions with authorizations + #### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If a user signs in with username and password, creating a _user session_, @@ -20008,7 +19788,7 @@ tags: - [Authorize API requests](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication) - [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/) - [Assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/) - name: Authorizations (API tokens) + name: Authorizations - description: | Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets @@ -20074,7 +19854,7 @@ tags: - ### Properties + #### Properties A `task` object contains information about an InfluxDB task resource. @@ -20082,7 +19862,7 @@ tags: - ### Related guides + #### Related guides - [Get started with tasks](https://docs.influxdata.com/influxdb/latest/process-data/get-started/) - [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/) @@ -20106,7 +19886,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - ### Related guides + #### Related guides - [InfluxDB stacks](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/) - [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/) @@ -20117,14 +19897,14 @@ tags: To grant a user permission to access data, add them as a member of an organization and provide them with an API token. - ### User sessions with authorizations + #### 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 + #### Related guides - [Manage users](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/) - [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) @@ -20200,7 +19980,7 @@ tags: | `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 + #### 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, diff --git a/src/cloud.yml b/src/cloud.yml index eef11d64c..61ed7d1d9 100644 --- a/src/cloud.yml +++ b/src/cloud.yml @@ -21,6 +21,10 @@ paths: $ref: './cloud/paths/setup.yml' /setup/user: $ref: './cloud/paths/setup_user.yml' + /authorizations: + $ref: './cloud/paths/authorizations.yml' + /authorizations/{authID}: + $ref: './cloud/paths/authorizations_authID.yml' /variables: $ref: './cloud/paths/variables.yml' '/variables/{variableID}': @@ -37,7 +41,7 @@ paths: $ref: './cloud/paths/dashboards.yml' /tasks: $ref: './cloud/paths/tasks.yml' - /tasks/{taskID}: + "/tasks/{taskID}": $ref: "./cloud/paths/tasks_taskID.yml" components: parameters: @@ -78,10 +82,6 @@ components: $ref: "./cloud/schemas/Task.yml" TaskCreateRequest: $ref: "./cloud/schemas/TaskCreateRequest.yml" - TaskScriptID: - $ref: "./cloud/schemas/TaskProperties.yml#/scriptID" - TaskScriptParameters: - $ref: "./cloud/schemas/TaskProperties.yml#/scriptParameters" TaskUpdateRequest: $ref: "./cloud/schemas/TaskUpdateRequest.yml" responses: @@ -96,7 +96,7 @@ components: TaskWithFluxRequest: $ref: "./common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" TaskWithScriptRequest: - $ref: "./cloud/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" + $ref: "./common/requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" securitySchemes: TokenAuthentication: type: apiKey @@ -132,7 +132,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides diff --git a/src/cloud/paths/authorizations.yml b/src/cloud/paths/authorizations.yml new file mode 100644 index 000000000..eb20d6ac9 --- /dev/null +++ b/src/cloud/paths/authorizations.yml @@ -0,0 +1,145 @@ +get: + operationId: GetAuthorizations + tags: + - Authorizations + 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 for the organization. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### Required permissions + + - `read-authorizations` + + #### Related guides + + - [View tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) + parameters: + - $ref: "../../common/parameters/TraceSpan.yml" + - in: query + name: userID + schema: + type: string + description: | + A user ID. + Only returns authorizations scoped to the specified + [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + - in: query + name: user + schema: + type: string + description: | + A user name. + Only returns authorizations scoped to the specified + [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + - in: query + name: orgID + schema: + type: string + description: | + An organization ID. + Only returns authorizations that belong to the specified + [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + - in: query + name: org + schema: + type: string + description: | + An organization name. + Only returns authorizations that belong to the specified + [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + - in: query + name: token + schema: + type: string + description: | + An API [token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) value. + Returns the authorization for the specified token. + responses: + "200": + description: Success. The response body contains a list of authorizations. + content: + application/json: + schema: + $ref: "../../common/schemas/Authorizations.yml" + "400": + description: Invalid request + $ref: '../../common/responses/ServerError.yml' + "401": + $ref: "../../common/responses/AuthorizationError.yml" + "500": + $ref: "../../common/responses/InternalServerError.yml" + default: + description: Unexpected error + $ref: '../../common/responses/ServerError.yml' +post: + operationId: PostAuthorizations + tags: + - Authorizations + summary: Create an authorization + description: | + Creates an authorization and returns the authorization with the + generated API [token]({{% INFLUXDB_DOCS_URL %}}/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. + + #### Limitations + + To follow best practices for secure API token generation and retrieval, + InfluxDB Cloud enforces access restrictions on API tokens. + + - InfluxDB only allows access to the API token value immediately after the authorization is created. + - You can't update an authorization's permissions. + - A token stops working when the user who created the authorization 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. + + #### Related guides + + - [Create a token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/create-token/) + parameters: + - $ref: "../../common/parameters/TraceSpan.yml" + requestBody: + description: The authorization to create. + required: true + content: + application/json: + schema: + $ref: "../../common/schemas/AuthorizationPostRequest.yml" + examples: + AuthorizationPostRequest: + $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationPostRequest" + AuthorizationWithResourcePostRequest: + $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithResourcePostRequest" + AuthorizationWithUserPostRequest: + $ref: "../../common/requestBody/examples/AuthorizationRequestExamples.yml#/AuthorizationWithUserPostRequest" + responses: + "201": + description: | + Success. The authorization is created. The response body contains the authorization. + content: + application/json: + schema: + $ref: "../../common/schemas/Authorization.yml" + "400": + description: Invalid request + $ref: '../../common/responses/ServerError.yml' + "401": + $ref: "../../common/responses/AuthorizationError.yml" + "500": + $ref: "../../common/responses/InternalServerError.yml" + default: + description: Unexpected error + $ref: '../../common/responses/ServerError.yml' diff --git a/src/cloud/paths/authorizations_authID.yml b/src/cloud/paths/authorizations_authID.yml new file mode 100644 index 000000000..c85317bfb --- /dev/null +++ b/src/cloud/paths/authorizations_authID.yml @@ -0,0 +1,73 @@ +get: + operationId: GetAuthorizationsID + tags: + - Authorizations + summary: Retrieve an authorization + parameters: + - $ref: "../../common/parameters/TraceSpan.yml" + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to get. + responses: + "200": + description: Authorization details + content: + application/json: + schema: + $ref: "../../common/schemas/Authorization.yml" + default: + description: Unexpected error + $ref: '../../common/responses/ServerError.yml' +patch: + operationId: PatchAuthorizationsID + tags: + - Authorizations + summary: Update authorization status + description: Update an authorization's status to `active` or `inactive`. + requestBody: + description: The updated Authorization object. + required: true + content: + application/json: + schema: + $ref: "../../common/schemas/AuthorizationUpdateRequest.yml" + parameters: + - $ref: "../../common/parameters/TraceSpan.yml" + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to update. + responses: + "200": + description: The updated authorization. + content: + application/json: + schema: + $ref: "../../common/schemas/Authorization.yml" + default: + description: Unexpected error + $ref: '../../common/responses/ServerError.yml' +delete: + operationId: DeleteAuthorizationsID + tags: + - Authorizations + summary: Delete an authorization + parameters: + - $ref: "../../common/parameters/TraceSpan.yml" + - in: path + name: authID + schema: + type: string + required: true + description: The identifier of the authorization to delete. + responses: + "204": + description: Authorization deleted + default: + description: Unexpected error + $ref: '../../common/responses/ServerError.yml' diff --git a/src/cloud/paths/tasks.yml b/src/cloud/paths/tasks.yml index 7f9384da0..3d305c64f 100644 --- a/src/cloud/paths/tasks.yml +++ b/src/cloud/paths/tasks.yml @@ -3,23 +3,19 @@ get: tags: - Data I/O endpoints - Tasks - summary: List tasks + summary: List all tasks description: | - Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/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`. - - #### Related guide - - - [Process data with InfluxDB tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/) parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: query name: name description: | - A task name. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) with the specified name. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. schema: type: string @@ -28,29 +24,29 @@ get: schema: type: string description: | - A task ID. - Only returns [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Only returns tasks created after the specified task. - in: query name: user schema: type: string description: | - A user ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. - in: query name: org schema: type: string description: | - An organization name. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. - in: query name: orgID schema: type: string description: | - An organization ID. - Only returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. - in: query name: status schema: @@ -59,8 +55,8 @@ get: - active - inactive description: | - A task status. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). - in: query name: limit schema: @@ -93,11 +89,8 @@ get: - in: query name: sortBy description: | - The sort field. - Specifies the task property used to sort records in the list. - Default is `name`. - - The parameter has one supported value: `name`. + The sort field. Only `name` is supported. + Specifies the field used to sort records in the list. required: false schema: type: string @@ -106,13 +99,11 @@ get: - in: query name: type description: | - A task type. - Specifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response. + A [task]({{% INFLUXDB_DOCS_URL %}}/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, set the `type` parameter to `basic` (`type=basic`) - to omit some task properties (`flux`, `createdAt`, `updatedAt`). + To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). required: false schema: default: "" @@ -123,8 +114,8 @@ get: - in: query name: scriptID description: | - A script ID. - Only returns tasks that use the specified [invokable script](#tag/Invokable-Scripts). + A [script](#tag/Invokable-Scripts) ID. + Only returns tasks that use the specified invokable script. schema: type: string responses: @@ -160,7 +151,52 @@ post: description: | Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. - Use this endpoint to create a scheduled task that runs a script. + 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 @@ -171,41 +207,15 @@ post: parameters: - $ref: "../../common/parameters/TraceSpan.yml" requestBody: - description: | - In the request body, provide the task. - - Set one of the following properties to provide the script that the task runs: - - `flux` - - `scriptID` - - If you set the `scriptID` property, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, you must provide the `task` configuration option - in the Flux script. - - See [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't use `flux` and `scriptID` in the same task. + description: The task to create required: true content: application/json: schema: $ref: "../schemas/TaskCreateRequest.yml" - examples: - TaskWithFlux: - $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" - TaskWithScriptID: - $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" responses: "201": - description: Success. The response body contains a `tasks` list with the task. + description: Success. The response body contains a `tasks` list with the new task. content: application/json: schema: @@ -217,10 +227,8 @@ post: #### InfluxDB Cloud - - Returns this error if the task doesn't contain the `flux` property - or the `scriptID` property. - - Returns this error if the task contains `flux` _and_ `scriptID` - properties. + - 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: @@ -250,3 +258,41 @@ post: application/json: schema: $ref: "../../common/schemas/Error.yml" + 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 diff --git a/src/cloud/paths/tasks_taskID.yml b/src/cloud/paths/tasks_taskID.yml index ca5601697..cf9786a3c 100644 --- a/src/cloud/paths/tasks_taskID.yml +++ b/src/cloud/paths/tasks_taskID.yml @@ -5,7 +5,7 @@ get: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -14,8 +14,8 @@ get: type: string required: true description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Specifies the task to retrieve. responses: "200": description: Success. The response body contains the task. @@ -39,52 +39,67 @@ patch: - Tasks summary: Update a task description: | - Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), + Updates a [task]({{% INFLUXDB_DOCS_URL %}}/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. - The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. - #### Related guides + #### InfluxDB Cloud - - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - requestBody: - description: | - In the request body, provide the task properties to update. - To provide the script that the task runs, - set either the `flux` property or the `scriptID` property. + - 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: - If you set `scriptID`, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` + ```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" + } + ``` - If you set the `flux` property, provide the `task` configuration option - in the Flux script. + - `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: - See [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - for detail and examples. + ```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: + #### Limitations: - - You can't set `flux` and `scriptID` properties for the same task--for - example, if you set the `scriptID` property, then InfluxDB sets the `flux` property - to an empty string (`""`). + - 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: "../schemas/TaskUpdateRequest.yml" - examples: - TaskWithFlux: - $ref: "../../common/requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" - TaskWithScriptID: - $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithScriptRequest" parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -93,8 +108,8 @@ patch: type: string required: true description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to update. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Specifies the task to update. responses: "200": description: Success. The response body contains the updated task. @@ -118,13 +133,12 @@ delete: - Tasks summary: Delete a task description: | - Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + Deletes a [task]({{% INFLUXDB_DOCS_URL %}}/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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` - property to `inactive`. + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -132,9 +146,7 @@ delete: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. + description: A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. Specifies the task to delete. responses: "204": description: Success. The task and task runs are deleted. Scheduled runs are canceled. diff --git a/src/cloud/requestBody/examples/TaskRequestExamples.yml b/src/cloud/requestBody/examples/TaskRequestExamples.yml deleted file mode 100644 index 5b4346d28..000000000 --- a/src/cloud/requestBody/examples/TaskRequestExamples.yml +++ /dev/null @@ -1,17 +0,0 @@ -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." - } diff --git a/src/cloud/schemas/Task.yml b/src/cloud/schemas/Task.yml index d8624ed17..408544852 100644 --- a/src/cloud/schemas/Task.yml +++ b/src/cloud/schemas/Task.yml @@ -1,45 +1,142 @@ type: object properties: id: - $ref: ../../common/schemas/TaskProperties.yml#/id + readOnly: true + type: string orgID: - $ref: ../../common/schemas/TaskProperties.yml#/orgID + description: | + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string org: - $ref: ../../common/schemas/TaskProperties.yml#/org + description: | + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string name: - $ref: ../../common/schemas/TaskProperties.yml#/name - description: - $ref: ../../common/schemas/TaskProperties.yml#/description + description: The name of the task. + type: string ownerID: - $ref: ../../common/schemas/TaskProperties.yml#/ownerID + description: | + A [user]({{% INFLUXDB_DOCS_URL %}}/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: ../../common/schemas/TaskProperties.yml#/status + $ref: "../../common/schemas/TaskStatusType.yml" labels: - $ref: ../../common/schemas/TaskProperties.yml#/labels + $ref: "../../common/schemas/Labels.yml" authorizationID: - $ref: ../../common/schemas/TaskProperties.yml#/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: - $ref: ../../common/schemas/TaskProperties.yml#/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: - $ref: ../../common/schemas/TaskProperties.yml#/every + description: >- + The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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: - $ref: ../../common/schemas/TaskProperties.yml#/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: - $ref: ../../common/schemas/TaskProperties.yml#/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: - $ref: ../../common/schemas/TaskProperties.yml#/latestCompleted + description: >- + A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. + type: string + format: date-time + readOnly: true lastRunStatus: - $ref: ../../common/schemas/TaskProperties.yml#/lastRunStatus + readOnly: true + type: string + enum: + - failed + - success + - canceled lastRunError: - $ref: ../../common/schemas/TaskProperties.yml#/lastRunError + readOnly: true + type: string createdAt: - $ref: ../../common/schemas/TaskProperties.yml#/createdAt + type: string + format: date-time + readOnly: true updatedAt: - $ref: ../../common/schemas/TaskProperties.yml#/updatedAt + type: string + format: date-time + readOnly: true links: - $ref: ../../common/schemas/TaskProperties.yml#/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: "../../common/schemas/Link.yml" + owners: + $ref: "../../common/schemas/Link.yml" + members: + $ref: "../../common/schemas/Link.yml" + runs: + $ref: "../../common/schemas/Link.yml" + logs: + $ref: "../../common/schemas/Link.yml" + labels: + $ref: "../../common/schemas/Link.yml" scriptID: - $ref: ./TaskProperties.yml#/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]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) + type: string scriptParameters: - $ref: ./TaskProperties.yml#/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] diff --git a/src/cloud/schemas/TaskCreateRequest.yml b/src/cloud/schemas/TaskCreateRequest.yml index ea1b8c2ba..4fcaead8e 100644 --- a/src/cloud/schemas/TaskCreateRequest.yml +++ b/src/cloud/schemas/TaskCreateRequest.yml @@ -1,24 +1,57 @@ -type: object -properties: - orgID: - $ref: ../../common/schemas/TaskProperties.yml#/orgID - org: - $ref: ../../common/schemas/TaskProperties.yml#/org - name: - $ref: ../../common/schemas/TaskProperties.yml#/name - description: - $ref: ../../common/schemas/TaskProperties.yml#/description - every: - $ref: ../../common/schemas/TaskProperties.yml#/every - cron: - $ref: ../../common/schemas/TaskProperties.yml#/cron - offset: - $ref: ../../common/schemas/TaskProperties.yml#/offset - status: - $ref: ../../common/schemas/TaskProperties.yml#/status - flux: - $ref: ../../common/schemas/TaskProperties.yml#/flux - scriptID: - $ref: ./TaskProperties.yml#/scriptID - scriptParameters: - $ref: ./TaskProperties.yml#/scriptParameters + 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: "../../common/schemas/TaskStatusType.yml" + 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 diff --git a/src/cloud/schemas/TaskProperties.yml b/src/cloud/schemas/TaskProperties.yml deleted file mode 100644 index 488cc2da3..000000000 --- a/src/cloud/schemas/TaskProperties.yml +++ /dev/null @@ -1,26 +0,0 @@ -scriptID: - description: | - A script ID. - Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. - - #### Related guides - - - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/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 [invokable script](#tag/Invokable-Scripts) specified - by the `scriptID` property. - When running the task, InfluxDB executes the script with the parameters - you provide. - - #### Limitations - - - To use the `scriptParameters` property, you must also set the `scriptID` property - for the task. - - #### Related guides - - - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). - type: object diff --git a/src/cloud/schemas/TaskUpdateRequest.yml b/src/cloud/schemas/TaskUpdateRequest.yml index adcd26cf7..3b1b82ee9 100644 --- a/src/cloud/schemas/TaskUpdateRequest.yml +++ b/src/cloud/schemas/TaskUpdateRequest.yml @@ -1,20 +1,28 @@ type: object properties: status: - $ref: ../../common/schemas/TaskProperties.yml#/status + $ref: "../../common/schemas/TaskStatusType.yml" + flux: + description: Update the Flux script that the task runs. + type: string name: - $ref: ../../common/schemas/TaskProperties.yml#/name - description: - $ref: ../../common/schemas/TaskProperties.yml#/description + description: Update the 'name' option in the flux script. + type: string every: - $ref: ../../common/schemas/TaskProperties.yml#/every + description: Update the 'every' option in the flux script. + type: string cron: - $ref: ../../common/schemas/TaskProperties.yml#/cron + description: Update the 'cron' option in the flux script. + type: string offset: - $ref: ../../common/schemas/TaskProperties.yml#/offset - flux: - $ref: ../../common/schemas/TaskProperties.yml#/flux + description: Update the 'offset' option in the flux script. + type: string + description: + description: Update the description of the task. + type: string scriptID: - $ref: ./TaskProperties.yml#/scriptID + description: Update the 'scriptID' of the task. + type: string scriptParameters: - $ref: ./TaskProperties.yml#/scriptParameters + description: Update the 'scriptParameters' of the task. + type: object diff --git a/src/cloud/tags.yml b/src/cloud/tags.yml index 44ac6d00b..863354638 100644 --- a/src/cloud/tags.yml +++ b/src/cloud/tags.yml @@ -1,5 +1,5 @@ tags: - - name: Authorizations (API tokens) + - name: Authorizations description: | Create and manage authorizations (API tokens). @@ -7,12 +7,24 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. + In InfluxDB Cloud, an authorization with `read-authorizations` permission + can be used to view other authorizations. + + #### Limitations + + 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. - ### User sessions with authorizations + #### 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_, @@ -74,7 +86,7 @@ tags: 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 + #### Related guides - [Invoke custom scripts]({{% INFLUXDB_DOCS_URL %}}/api-guide/api-invokable-scripts/) from API requests. - [Create a task that references a script]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) @@ -103,7 +115,7 @@ tags: - ### Properties + #### Properties A `task` object contains information about an InfluxDB task resource. @@ -111,7 +123,7 @@ tags: - ### Related guides + #### Related guides - [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/) - [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/) @@ -134,7 +146,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - ### Related guides + #### Related guides - [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/) - [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/) @@ -149,14 +161,14 @@ tags: `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to view specific members. - ### User sessions with authorizations + #### 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 + #### Related guides - [Manage users]({{% INFLUXDB_DOCS_URL %}}/organizations/users/) - name: Write @@ -237,7 +249,7 @@ tags: | `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 + #### 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, diff --git a/src/common/_paths.yml b/src/common/_paths.yml index 3d9dcfd8d..6f21ef6b9 100644 --- a/src/common/_paths.yml +++ b/src/common/_paths.yml @@ -174,7 +174,3 @@ $ref: "./common/paths/notificationEndpoints_endpointID_labels.yml" "/notificationEndpoints/{endpointID}/labels/{labelID}": $ref: "./common/paths/notificationEndpoints_endpointID_labels_labelID.yml" - /authorizations: - $ref: "./common/paths/authorizations.yml" - /authorizations/{authID}: - $ref: "./common/paths/authorizations_authID.yml" diff --git a/src/common/_schemas.yml b/src/common/_schemas.yml index bbabecfe2..a532d32f7 100644 --- a/src/common/_schemas.yml +++ b/src/common/_schemas.yml @@ -160,22 +160,6 @@ $ref: "./common/schemas/Run.yml" RunManually: $ref: "./common/schemas/RunManually.yml" - TaskCron: - $ref: "./common/schemas/TaskProperties.yml#/cron" - TaskDescription: - $ref: "./common/schemas/TaskProperties.yml#/description" - TaskEvery: - $ref: "./common/schemas/TaskProperties.yml#/every" - TaskFlux: - $ref: "./common/schemas/TaskProperties.yml#/flux" - TaskName: - $ref: "./common/schemas/TaskProperties.yml#/name" - TaskOffset: - $ref: "./common/schemas/TaskProperties.yml#/offset" - TaskOrg: - $ref: "./common/schemas/TaskProperties.yml#/org" - TaskOrgID: - $ref: "./common/schemas/TaskProperties.yml#/orgID" TaskStatusType: $ref: "./common/schemas/TaskStatusType.yml" UserResponse: diff --git a/src/common/paths/authorizations.yml b/src/common/paths/authorizations.yml index 5dd7be749..53491a4fd 100644 --- a/src/common/paths/authorizations.yml +++ b/src/common/paths/authorizations.yml @@ -1,7 +1,7 @@ get: operationId: GetAuthorizations tags: - - Authorizations (API tokens) + - Authorizations - Security and access endpoints summary: List authorizations description: | @@ -10,19 +10,16 @@ get: 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 OSS - - InfluxDB Cloud doesn't expose [API token]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. + - InfluxDB OSS returns + [API token]({{% INFLUXDB_DOCS_URL %}}/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. #### 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 + - An _[operator token](https://docs.influxdata.com/influxdb/latest/security/tokens/#operator-token)_. #### Related guides @@ -57,40 +54,9 @@ get: description: | An organization name. Only returns authorizations that belong to the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). - - in: query - name: token - schema: - type: string - description: | - An API [token]({{% INFLUXDB_DOCS_URL %}}/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]({{% INFLUXDB_DOCS_URL %}}/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. + description: Success. The response body contains a list of authorizations. content: application/json: schema: @@ -108,8 +74,7 @@ get: post: operationId: PostAuthorizations tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations summary: Create an authorization description: | Creates an authorization and returns the authorization with the @@ -117,24 +82,21 @@ post: 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. + The response contains the new authorization with the generated API token. + + #### Limitations 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 + - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any + user with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_. + - You can't update an authorization's permissions. + - Even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + - A token stops working when the user who created the authorization is deleted. - - `write-authorizations` - - `write-user` for the user that the authorization is scoped to + We recommend creating a generic user to create and manage tokens for writing data. #### Related guides @@ -158,8 +120,7 @@ post: responses: "201": description: | - Success. The authorization is created. The response body contains the - authorization. + Success. The authorization is created. The response body contains the authorization. content: application/json: schema: diff --git a/src/common/paths/authorizations_authID.yml b/src/common/paths/authorizations_authID.yml index a31a0d782..768e62822 100644 --- a/src/common/paths/authorizations_authID.yml +++ b/src/common/paths/authorizations_authID.yml @@ -1,28 +1,9 @@ get: operationId: GetAuthorizationsID tags: - - Authorizations (API tokens) + - Authorizations - 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]({{% INFLUXDB_DOCS_URL %}}/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]({{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/) - externalDocs: - url: "{{% INFLUXDB_DOCS_URL %}}/security/tokens/view-tokens/" - description: View tokens parameters: - $ref: "../../common/parameters/TraceSpan.yml" - in: path @@ -30,64 +11,24 @@ get: schema: type: string required: true - description: An authorization ID. Specifies the authorization to retrieve. + description: The ID of the authorization to get. responses: "200": - description: Success. The response body contains the authorization. + description: Authorization details content: application/json: schema: $ref: "../../common/schemas/Authorization.yml" - "400": - description: | - Bad request. - content: - application/json: - schema: - $ref: "../schemas/Error.yml" - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: { - "code": "invalid", - "message": "id must have a length of 16 bytes" - } - "401": - $ref: "../responses/AuthorizationError.yml" - "404": - description: | - Not found. - content: - application/json: - schema: - $ref: "../schemas/Error.yml" - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: { - "code": "not found", - "message": "authorization not found" - } - "500": - $ref: "../responses/InternalServerError.yml" default: description: Unexpected error $ref: '../../common/responses/ServerError.yml' 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. + - Authorizations + summary: Update an authorization to be active or inactive requestBody: - description: In the request body, provide the authorization properties to update. + description: Authorization to update required: true content: application/json: @@ -100,10 +41,10 @@ patch: schema: type: string required: true - description: An authorization ID. Specifies the authorization to update. + description: The ID of the authorization to update. responses: "200": - description: Success. The response body contains the updated authorization. + description: The active or inactive authorization content: application/json: schema: @@ -114,16 +55,8 @@ patch: delete: operationId: DeleteAuthorizationsID tags: - - Authorizations (API tokens) - - Security and access endpoints + - Authorizations 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: "../../common/parameters/TraceSpan.yml" - in: path @@ -131,44 +64,10 @@ delete: schema: type: string required: true - description: An authorization ID. Specifies the authorization to delete. + description: The ID of the authorization to delete. responses: "204": - description: Success. The authorization is deleted. - "400": - description: | - Bad request. - content: - application/json: - schema: - $ref: "../schemas/Error.yml" - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: { - "code": "invalid", - "message": "id must have a length of 16 bytes" - } - "401": - $ref: "../responses/AuthorizationError.yml" - "404": - description: | - Not found. - content: - application/json: - schema: - $ref: "../schemas/Error.yml" - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: { - "code": "not found", - "message": "authorization not found" - } - "500": - $ref: "../responses/InternalServerError.yml" + description: Authorization deleted default: description: Unexpected error $ref: '../../common/responses/ServerError.yml' diff --git a/src/common/paths/buckets_bucketID_owners.yml b/src/common/paths/buckets_bucketID_owners.yml index 6c324a1de..13daf62b9 100644 --- a/src/common/paths/buckets_bucketID_owners.yml +++ b/src/common/paths/buckets_bucketID_owners.yml @@ -13,7 +13,7 @@ get: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -29,7 +29,7 @@ get: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides @@ -84,7 +84,7 @@ post: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -99,7 +99,7 @@ post: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides diff --git a/src/common/paths/buckets_bucketID_owners_userID.yml b/src/common/paths/buckets_bucketID_owners_userID.yml index 1f1880642..e07b24e8b 100644 --- a/src/common/paths/buckets_bucketID_owners_userID.yml +++ b/src/common/paths/buckets_bucketID_owners_userID.yml @@ -11,7 +11,7 @@ delete: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -27,7 +27,7 @@ delete: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) #### Related guides diff --git a/src/common/paths/flags.yml b/src/common/paths/flags.yml index 3fe197944..6154641be 100644 --- a/src/common/paths/flags.yml +++ b/src/common/paths/flags.yml @@ -14,7 +14,7 @@ get: 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]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/#feature-flags). + 2. Follow the instructions to [enable, disable, or override values for feature flags]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/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. @@ -23,7 +23,7 @@ get: #### Related guides - - [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/reference/config-options/) + - [InfluxDB configuration options]({{% INFLUXDB_DOCS_URL %}}/influxdb/v2.4/reference/config-options/) parameters: - $ref: "../parameters/TraceSpan.yml" responses: diff --git a/src/common/paths/orgs_orgID_members.yml b/src/common/paths/orgs_orgID_members.yml index c91c14a1b..64a3e3b19 100644 --- a/src/common/paths/orgs_orgID_members.yml +++ b/src/common/paths/orgs_orgID_members.yml @@ -16,7 +16,7 @@ get: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -99,7 +99,7 @@ post: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations diff --git a/src/common/paths/orgs_orgID_members_userID.yml b/src/common/paths/orgs_orgID_members_userID.yml index 4f149fd44..9c3b66de7 100644 --- a/src/common/paths/orgs_orgID_members_userID.yml +++ b/src/common/paths/orgs_orgID_members_userID.yml @@ -14,7 +14,7 @@ delete: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations diff --git a/src/common/paths/orgs_orgID_owners.yml b/src/common/paths/orgs_orgID_owners.yml index 9d1f3f586..001c1ee57 100644 --- a/src/common/paths/orgs_orgID_owners.yml +++ b/src/common/paths/orgs_orgID_owners.yml @@ -10,7 +10,7 @@ get: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -61,7 +61,7 @@ post: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions @@ -71,7 +71,7 @@ post: #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: "../parameters/TraceSpan.yml" - in: path diff --git a/src/common/paths/orgs_orgID_owners_userID.yml b/src/common/paths/orgs_orgID_owners_userID.yml index bdfa0f626..1d5320c01 100644 --- a/src/common/paths/orgs_orgID_owners_userID.yml +++ b/src/common/paths/orgs_orgID_owners_userID.yml @@ -13,7 +13,7 @@ delete: #### InfluxDB Cloud - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations @@ -28,7 +28,7 @@ delete: remove an owner from. #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) + - [Authorizations](#tag/Authorizations) parameters: - $ref: "../parameters/TraceSpan.yml" - in: path diff --git a/src/common/paths/tasks.yml b/src/common/paths/tasks.yml index e8c6e825f..ae048e773 100644 --- a/src/common/paths/tasks.yml +++ b/src/common/paths/tasks.yml @@ -5,7 +5,7 @@ get: - Tasks summary: List tasks description: | - Lists [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a list of [tasks]({{% INFLUXDB_DOCS_URL %}}/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`. @@ -18,9 +18,8 @@ get: - in: query name: name description: | - A task name. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - that have the specified name. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. schema: type: string @@ -29,30 +28,29 @@ get: schema: type: string description: | - A task ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) created after the specified task. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Only returns tasks created after the specified task. - in: query name: user schema: type: string description: | - A user ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - owned by the specified [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user). + A [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. - in: query name: org schema: type: string description: | - An organization name. - Only returns tasks owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. - in: query name: orgID schema: type: string description: | - An organization ID. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) owned by the specified [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization). + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. - in: query name: status schema: @@ -61,8 +59,8 @@ get: - active - inactive description: | - A task status. - Only returns [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that have the specified status. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). - in: query name: limit schema: @@ -80,9 +78,9 @@ get: - in: query name: type description: | - A task type. - Specifies the level of detail for [tasks]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) in the response. + A [task]({{% INFLUXDB_DOCS_URL %}}/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 @@ -123,9 +121,7 @@ post: - Tasks summary: Create a task description: | - Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a script. + Creates a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and returns the task. #### Related guides @@ -136,20 +132,12 @@ post: parameters: - $ref: "../parameters/TraceSpan.yml" requestBody: - description: | - In the request body, provide the task. - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. + description: The task to create. required: true content: application/json: schema: $ref: "../schemas/TaskCreateRequest.yml" - examples: - TaskWithFlux: - $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" responses: "201": description: Success. The response body contains a `tasks` list with the task. @@ -171,18 +159,18 @@ post: $ref: "../schemas/Error.yml" examples: orgProvidedNotFound: - summary: The organization specified by org or orgID doesn't own the token passed in the header + 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" + "code": "invalid", + "message": "failed to decode request body: organization not found", } missingFluxError: - summary: The request body doesn't contain a Flux query + summary: Task in request body is missing Flux query value: { - "code":"invalid", - "message": "failed to decode request: missing flux" + "code": "invalid", + "message": "failed to decode request: missing flux", } "401": $ref: "../responses/AuthorizationError.yml" @@ -194,3 +182,21 @@ post: application/json: schema: $ref: "../schemas/Error.yml" + x-codeSamples: + - lang: Shell + label: "cURL: create a task" + source: | + curl http://localhost:8086/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 diff --git a/src/common/paths/tasks_taskID.yml b/src/common/paths/tasks_taskID.yml index 9452fbd38..d69400030 100644 --- a/src/common/paths/tasks_taskID.yml +++ b/src/common/paths/tasks_taskID.yml @@ -5,7 +5,7 @@ get: - Tasks summary: Retrieve a task description: | - Retrieves the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -13,9 +13,7 @@ get: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve. + description: The ID of the task to retrieve. responses: "200": description: Success. The response body contains the task. @@ -39,27 +37,21 @@ patch: - Tasks summary: Update a task description: | - Updates the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task), - and then cancels all scheduled runs of the task. + Updates a 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`. + Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - #### Related guides - - - [Update a task]({{% INFLUXDB_DOCS_URL %}}/process-data/manage-tasks/update-task/) - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) + 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. requestBody: - description: | - In the request body, provide the task properties to update. + description: An object that contains updated task properties to apply. required: true content: application/json: schema: $ref: "../schemas/TaskUpdateRequest.yml" - examples: - TaskWithFlux: - $ref: "../requestBody/examples/TaskRequestExamples.yml#/TaskWithFluxRequest" parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -67,9 +59,7 @@ patch: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task)to update. + description: The ID of the task to update. responses: "200": description: Success. The response body contains the updated task. @@ -93,13 +83,12 @@ delete: - Tasks summary: Delete a task description: | - Deletes the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - and all associated records (task runs, logs, and labels). + Deletes a 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. - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status - to `inactive`. + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -107,9 +96,7 @@ delete: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete. + description: The ID of the task to delete. responses: "204": description: Success. The task and runs are deleted. Scheduled runs are canceled. diff --git a/src/common/paths/tasks_taskID_labels.yml b/src/common/paths/tasks_taskID_labels.yml index b1f252d34..9e45af5ea 100644 --- a/src/common/paths/tasks_taskID_labels.yml +++ b/src/common/paths/tasks_taskID_labels.yml @@ -4,12 +4,9 @@ get: - Tasks summary: List labels for a task description: | - Lists all labels for a task. + Retrieves a list of all labels for a task. - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Labels may be used for grouping and filtering tasks. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -17,9 +14,7 @@ get: schema: type: string required: true - description: | - A task ID. - Specifies the task to retrieve labels for. + 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. @@ -43,12 +38,9 @@ post: - Tasks summary: Add a label to a task description: | - Adds a label to a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Adds a label to a task. - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. + Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -56,12 +48,9 @@ post: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to label. + description: The ID of the task to label. requestBody: - description: | - In the request body, provide an object that specifies the label. + description: An object that contains a _`labelID`_ to add to the task. required: true content: application/json: @@ -69,7 +58,7 @@ post: $ref: "../schemas/LabelMapping.yml" responses: "201": - description: Success. The response body contains the label. + description: Success. The response body contains a list of all labels for the task. content: application/json: schema: diff --git a/src/common/paths/tasks_taskID_labels_labelID.yml b/src/common/paths/tasks_taskID_labels_labelID.yml index f94089011..4057d15e3 100644 --- a/src/common/paths/tasks_taskID_labels_labelID.yml +++ b/src/common/paths/tasks_taskID_labels_labelID.yml @@ -4,7 +4,7 @@ delete: - Tasks summary: Delete a label from a task description: | - Deletes a label from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Deletes a label from a task. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -12,17 +12,13 @@ delete: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to delete the label from. + description: The ID of the task to delete the label from. - in: path name: labelID schema: type: string required: true - description: | - A label ID. - Specifies the label to delete. + description: The ID of the label to delete. responses: "204": description: Success. The label is deleted. diff --git a/src/common/paths/tasks_taskID_logs.yml b/src/common/paths/tasks_taskID_logs.yml index 433137665..5e7f760b2 100644 --- a/src/common/paths/tasks_taskID_logs.yml +++ b/src/common/paths/tasks_taskID_logs.yml @@ -2,12 +2,12 @@ get: operationId: GetTasksIDLogs tags: - Tasks - summary: List logs for a task + summary: Retrieve all logs for a task description: | - Lists all log events for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a list of all logs for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). - When a task runs, InfluxDB creates a `run` record in the task’s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. + 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. @@ -18,21 +18,20 @@ get: schema: type: string required: true - description: A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve logs for. + 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. + 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: "../schemas/Logs.yml" examples: taskSuccess: - summary: Events for a successful task run + summary: Events for a successful task run. value: "events": [ { @@ -47,7 +46,7 @@ get: } ] taskFailure: - summary: Events for a failed task run + summary: Events for a failed task run. value: { "events": [ { diff --git a/src/common/paths/tasks_taskID_members.yml b/src/common/paths/tasks_taskID_members.yml index 479c4ef4f..0b72dd50b 100644 --- a/src/common/paths/tasks_taskID_members.yml +++ b/src/common/paths/tasks_taskID_members.yml @@ -6,9 +6,7 @@ get: 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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -16,16 +14,12 @@ get: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to retrieve members for. + description: The task ID. responses: "200": description: | Success. The response body contains a list of `users` that have the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. content: application/json: schema: @@ -44,10 +38,9 @@ post: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to members of the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) and then returns - the member. + Adds a user to members of a task and returns the member. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -55,12 +48,9 @@ post: schema: type: string required: true - description: | - A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. - Specifies the task for the member. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as a member of the task. required: true content: application/json: @@ -68,10 +58,7 @@ post: $ref: "../schemas/AddResourceMemberRequestBody.yml" responses: "201": - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. + description: Created. The user is added to task members. content: application/json: schema: diff --git a/src/common/paths/tasks_taskID_members_userID.yml b/src/common/paths/tasks_taskID_members_userID.yml index abc08c313..dfb3ae26e 100644 --- a/src/common/paths/tasks_taskID_members_userID.yml +++ b/src/common/paths/tasks_taskID_members_userID.yml @@ -6,9 +6,7 @@ delete: 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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -16,16 +14,16 @@ delete: schema: type: string required: true - description: A user ID. Specifies the member to remove. + description: The ID of the member to remove. - in: path name: taskID schema: type: string required: true - description: A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the member from. + description: The task ID. responses: "204": - description: Success. The member is removed. + description: Member removed default: description: Unexpected error content: diff --git a/src/common/paths/tasks_taskID_owners.yml b/src/common/paths/tasks_taskID_owners.yml index 874137695..08e6a586f 100644 --- a/src/common/paths/tasks_taskID_owners.yml +++ b/src/common/paths/tasks_taskID_owners.yml @@ -6,9 +6,9 @@ get: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Lists all users that have the `owner` role for the specified task. + Retrieves all users that have owner permission for a task. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -16,7 +16,7 @@ get: schema: type: string required: true - description: A task ID. Specifies the task to retrieve owners for. + description: The ID of the task to retrieve owners for. responses: "200": description: | @@ -58,10 +58,9 @@ post: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Adds a specified user to owners of the specified task and then returns the - owner. + 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. @@ -72,12 +71,9 @@ post: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) for the owner. + description: The task ID. requestBody: - description: | - In the request body, provide an object that specifies the user. + description: A user to add as an owner of the task. required: true content: application/json: diff --git a/src/common/paths/tasks_taskID_owners_userID.yml b/src/common/paths/tasks_taskID_owners_userID.yml index 7f65d1280..4df6d8773 100644 --- a/src/common/paths/tasks_taskID_owners_userID.yml +++ b/src/common/paths/tasks_taskID_owners_userID.yml @@ -6,9 +6,8 @@ delete: 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. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Removes an owner from a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -16,18 +15,16 @@ delete: schema: type: string required: true - description: A user ID. Specifies the owner to remove from the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + description: The ID of the owner to remove. - in: path name: taskID schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to remove the owner from. + description: The task ID. responses: "204": - description: Success. The owner is removed. + description: Owner removed default: description: Unexpected error content: diff --git a/src/common/paths/tasks_taskID_runs.yml b/src/common/paths/tasks_taskID_runs.yml index 8e9146e9a..31c4728dc 100644 --- a/src/common/paths/tasks_taskID_runs.yml +++ b/src/common/paths/tasks_taskID_runs.yml @@ -4,11 +4,10 @@ get: - Tasks summary: List runs for a task description: | - Lists runs for the specified [task]({{% INFLUXDB_DOCS_URL %}}/process-data/). + Retrieves a list of runs for a [task]({{% INFLUXDB_DOCS_URL %}}/process-data/). To limit which task runs are returned, pass query parameters in your request. - If you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -17,16 +16,15 @@ get: type: string required: true description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to - to list runs for. + 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 the specified run. + Only returns runs created after this run. - in: query name: limit schema: @@ -43,7 +41,7 @@ get: format: date-time description: | A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. + Only returns runs scheduled after this time. - in: query name: beforeTime schema: @@ -51,7 +49,7 @@ get: format: date-time description: | A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. + Only returns runs scheduled before this time. responses: "200": description: Success. The response body contains the list of task runs. @@ -80,10 +78,6 @@ post: To _retry_ a previous run (and avoid creating a new run), use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -91,10 +85,6 @@ post: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to - to run. requestBody: content: application/json: @@ -107,19 +97,6 @@ post: application/json: schema: $ref: "../schemas/Run.yml" - "400": - description: Bad request. - content: - application/json: - schema: - $ref: "../schemas/Error.yml" - examples: - inactiveTask: - summary: Can't run an inactive task - value: { - "code": "invalid", - "message": "failed to force run: inactive task" - } "401": $ref: "../responses/AuthorizationError.yml" "500": diff --git a/src/common/paths/tasks_taskID_runs_runID.yml b/src/common/paths/tasks_taskID_runs_runID.yml index 6dd5325c9..ecf6571f9 100644 --- a/src/common/paths/tasks_taskID_runs_runID.yml +++ b/src/common/paths/tasks_taskID_runs_runID.yml @@ -4,7 +4,7 @@ get: - Tasks summary: Retrieve a run for a task. description: | - Retrieves the specified run for the specified [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). + Retrieves a specific run for a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). Use this endpoint to retrieve detail and logs for a specific task run. parameters: @@ -14,16 +14,13 @@ get: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) - that the task run belongs to. + description: The ID of the task to retrieve runs for. - in: path name: runID schema: type: string required: true - description: A task run ID. Specifies the run to retrieve. + description: The ID of the run to retrieve. responses: "200": description: Success. The response body contains the task run. @@ -80,7 +77,7 @@ delete: description: | Cancels a running [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task). - Use this endpoint to cancel a running task. + Use this endpoint with InfluxDB OSS to cancel a running task. #### InfluxDB Cloud @@ -92,18 +89,13 @@ delete: schema: type: string required: true - description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) to - to cancel. + description: The ID of the task to cancel. - in: path name: runID schema: type: string required: true - description: | - A task run ID. - Specifies the task run to cancel. + description: The ID of the task run to cancel. responses: "204": description: | diff --git a/src/common/paths/tasks_taskID_runs_runID_logs.yml b/src/common/paths/tasks_taskID_runs_runID_logs.yml index fd8939231..8a1fc79e3 100644 --- a/src/common/paths/tasks_taskID_runs_runID_logs.yml +++ b/src/common/paths/tasks_taskID_runs_runID_logs.yml @@ -2,12 +2,12 @@ get: operationId: GetTasksIDRunsIDLogs tags: - Tasks - summary: List logs for a run + summary: Retrieve all logs for a run description: | - Lists all logs for a task run. + 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]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) performance and troubleshoot failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. parameters: - $ref: "../parameters/TraceSpan.yml" - in: path @@ -15,13 +15,13 @@ get: schema: type: string required: true - description: A task ID. Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the run belongs to. + description: The ID of the task to get logs for. - in: path name: runID schema: type: string required: true - description: A run ID. Specifies the task run to list logs for. + description: The ID of the run to get logs for. responses: "200": description: | diff --git a/src/common/paths/tasks_taskID_runs_runID_retry.yml b/src/common/paths/tasks_taskID_runs_runID_retry.yml index 5af3ab68d..8406bcf31 100644 --- a/src/common/paths/tasks_taskID_runs_runID_retry.yml +++ b/src/common/paths/tasks_taskID_runs_runID_retry.yml @@ -4,15 +4,15 @@ post: - Tasks summary: Retry a task run description: | - Queues a [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run to - retry and then returns the scheduled run. + Queues a [task]({{% INFLUXDB_DOCS_URL %}}/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 - - Queuing a task run requires that the task's `status` property be set to `active`. + - The task must be _active_ (`status: "active"`). requestBody: content: application/json; charset=utf-8: @@ -26,15 +26,15 @@ post: type: string required: true description: | - A task ID. - Specifies the [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) that the task run belongs to. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) ID. + Specifies the task to retry. - in: path name: runID schema: type: string required: true description: | - A task run ID. + A [task]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#task) run ID. Specifies the task run to retry. To find a task run ID, use the diff --git a/src/common/requestBody/examples/AuthorizationRequestExamples.yml b/src/common/requestBody/examples/AuthorizationRequestExamples.yml index 7a488f855..110b0b1d3 100644 --- a/src/common/requestBody/examples/AuthorizationRequestExamples.yml +++ b/src/common/requestBody/examples/AuthorizationRequestExamples.yml @@ -1,48 +1,48 @@ 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" + 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" + } } - } - ] - } -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", + ] + } +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" + } + } + ] + } diff --git a/src/common/requestBody/examples/TaskRequestExamples.yml b/src/common/requestBody/examples/TaskRequestExamples.yml index f0248cead..65bb39b4c 100644 --- a/src/common/requestBody/examples/TaskRequestExamples.yml +++ b/src/common/requestBody/examples/TaskRequestExamples.yml @@ -4,13 +4,31 @@ TaskWithFluxRequest: 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\")", + 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." + "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." } diff --git a/src/common/schemas/AuthorizationUpdateRequest.yml b/src/common/schemas/AuthorizationUpdateRequest.yml index c07b46ce1..598a251a4 100644 --- a/src/common/schemas/AuthorizationUpdateRequest.yml +++ b/src/common/schemas/AuthorizationUpdateRequest.yml @@ -1,6 +1,6 @@ properties: status: - description: Status of the token. If `inactive`, InfluxDB rejects requests that use the token. + description: Status of the token. If `inactive`, requests using the token will be rejected. default: active type: string enum: diff --git a/src/common/schemas/RetentionRule.yml b/src/common/schemas/RetentionRule.yml index eff37f335..68bd9ca51 100644 --- a/src/common/schemas/RetentionRule.yml +++ b/src/common/schemas/RetentionRule.yml @@ -29,5 +29,5 @@ #### InfluxDB OSS - Default value depends on the - [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/reference/internals/shards/#shard-group-duration). + [bucket retention period]({{% INFLUXDB_DOCS_URL %}}/v2.3/reference/internals/shards/#shard-group-duration). required: [everySeconds] diff --git a/src/common/schemas/Task.yml b/src/common/schemas/Task.yml index 019b28683..e338d771d 100644 --- a/src/common/schemas/Task.yml +++ b/src/common/schemas/Task.yml @@ -1,41 +1,113 @@ type: object properties: id: - $ref: ./TaskProperties.yml#/id + readOnly: true + type: string orgID: - $ref: ./TaskProperties.yml#/orgID + description: | + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string org: - $ref: ./TaskProperties.yml#/org + description: | + An [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string name: - $ref: ./TaskProperties.yml#/name - description: - $ref: ./TaskProperties.yml#/description + description: The name of the task. + type: string ownerID: - $ref: ./TaskProperties.yml#/ownerID + description: | + A [user]({{% INFLUXDB_DOCS_URL %}}/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: ./TaskProperties.yml#/status + $ref: "./TaskStatusType.yml" labels: - $ref: ./TaskProperties.yml#/labels + $ref: "./Labels.yml" authorizationID: - $ref: ./TaskProperties.yml#/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: - $ref: ./TaskProperties.yml#/flux + description: The Flux script that the task executes. + type: string + format: flux every: - $ref: ./TaskProperties.yml#/every + description: >- + The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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: - $ref: ./TaskProperties.yml#/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: - $ref: ./TaskProperties.yml#/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: - $ref: ./TaskProperties.yml#/latestCompleted + description: >- + A timestamp ([RFC3339 date/time format]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. + type: string + format: date-time + readOnly: true lastRunStatus: - $ref: ./TaskProperties.yml#/lastRunStatus + readOnly: true + type: string + enum: + - failed + - success + - canceled lastRunError: - $ref: ./TaskProperties.yml#/lastRunError + readOnly: true + type: string createdAt: - $ref: ./TaskProperties.yml#/createdAt + type: string + format: date-time + readOnly: true updatedAt: - $ref: ./TaskProperties.yml#/updatedAt + type: string + format: date-time + readOnly: true links: - $ref: ./TaskProperties.yml#/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: "./Link.yml" + owners: + $ref: "./Link.yml" + members: + $ref: "./Link.yml" + runs: + $ref: "./Link.yml" + logs: + $ref: "./Link.yml" + labels: + $ref: "./Link.yml" + required: [id, name, orgID, flux] diff --git a/src/common/schemas/TaskCreateRequest.yml b/src/common/schemas/TaskCreateRequest.yml index 8034983e4..9758cca91 100644 --- a/src/common/schemas/TaskCreateRequest.yml +++ b/src/common/schemas/TaskCreateRequest.yml @@ -1,16 +1,18 @@ type: object properties: orgID: - $ref: ./TaskProperties.yml#/orgID + description: The ID of the organization that owns this Task. + type: string org: - $ref: ./TaskProperties.yml#/org - name: - $ref: ./TaskProperties.yml#/name - description: - $ref: ./TaskProperties.yml#/description - flux: - $ref: ./TaskProperties.yml#/flux + description: The name of the organization that owns this Task. + type: string status: - $ref: ./TaskProperties.yml#/status - required: - - flux + $ref: "./TaskStatusType.yml" + flux: + description: The Flux script to run for this task. + type: string + description: + description: An optional description of the task. + type: string + + required: [flux] diff --git a/src/common/schemas/TaskProperties.yml b/src/common/schemas/TaskProperties.yml deleted file mode 100644 index 4f64c13fd..000000000 --- a/src/common/schemas/TaskProperties.yml +++ /dev/null @@ -1,118 +0,0 @@ -id: - readOnly: true - type: string - description: | - The resource ID that InfluxDB uses to uniquely identify the task. -orgID: - description: | - An organization ID. - Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. - type: string -org: - description: | - An organization name. - Identifies the [organization]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#organization) that owns the task. - type: string -name: - description: The name of the task. - type: string -description: - description: A description of the task. - type: string -ownerID: - description: | - A user ID. - Identifies the [user]({{% INFLUXDB_DOCS_URL %}}/reference/glossary/#user) that owns the task. - - To find a user ID, use the - [`GET /api/v2/users` endpoint](#operation/GetUsers) to - list users. - type: string -status: - $ref: "./TaskStatusType.yml" -labels: - $ref: "./Labels.yml" -authorizationID: - description: | - An authorization ID. - Identifies 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: | - Flux with [task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options]({{% INFLUXDB_DOCS_URL %}}/process-data/task-options/) - type: string - format: Flux -every: - description: >- - The interval ([duration literal]({{% INFLUXDB_DOCS_URL %}}/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 - format: cron -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]({{% INFLUXDB_DOCS_URL %}}/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: "./Link.yml" - owners: - $ref: "./Link.yml" - members: - $ref: "./Link.yml" - runs: - $ref: "./Link.yml" - logs: - $ref: "./Link.yml" - labels: - $ref: "./Link.yml" diff --git a/src/common/schemas/TaskUpdateRequest.yml b/src/common/schemas/TaskUpdateRequest.yml index 3195eac1a..4f0f1289c 100644 --- a/src/common/schemas/TaskUpdateRequest.yml +++ b/src/common/schemas/TaskUpdateRequest.yml @@ -1,16 +1,22 @@ type: object properties: status: - $ref: ./TaskProperties.yml#/status + $ref: "./TaskStatusType.yml" flux: - $ref: ./TaskProperties.yml#/flux + description: The Flux script that the task runs. + type: string name: - $ref: ./TaskProperties.yml#/name + description: Update the 'name' option in the flux script. + type: string every: - $ref: ./TaskProperties.yml#/every + description: Update the 'every' option in the flux script. + type: string cron: - $ref: ./TaskProperties.yml#/cron + description: Update the 'cron' option in the flux script. + type: string offset: - $ref: ./TaskProperties.yml#/offset + description: Update the 'offset' option in the flux script. + type: string description: - $ref: ./TaskProperties.yml#/description + description: Update the description of the task. + type: string diff --git a/src/legacy/schemas/LegacyAuthorizationPostRequest.yml b/src/legacy/schemas/LegacyAuthorizationPostRequest.yml index 818c5a012..5b572add1 100644 --- a/src/legacy/schemas/LegacyAuthorizationPostRequest.yml +++ b/src/legacy/schemas/LegacyAuthorizationPostRequest.yml @@ -5,18 +5,18 @@ allOf: properties: orgID: type: string - description: The organization ID. Identifies the organization that the authorization is scoped to. + description: The ID of the organization that the authorization is scoped to. userID: type: string - description: The user ID. Identifies the user that the authorization is scoped to. + description: The ID of the user that the authorization is scoped to. token: type: string - description: The name that you provide for the authorization. + description: A name that you provide for the authorization. permissions: type: array minItems: 1 description: | - The list of permissions that provide `read` and `write` access to organization resources. + A list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: "../../common/schemas/Permission.yml" diff --git a/src/oss.yml b/src/oss.yml index a8938a4dd..a16b7ef5c 100644 --- a/src/oss.yml +++ b/src/oss.yml @@ -45,6 +45,10 @@ paths: $ref: "./common/paths/users_userID.yml" /setup: $ref: "./common/paths/setup.yml" + /authorizations: + $ref: "./common/paths/authorizations.yml" + /authorizations/{authID}: + $ref: "./common/paths/authorizations_authID.yml" /variables: $ref: "./common/paths/variables.yml" "/variables/{variableID}": @@ -105,7 +109,7 @@ paths: $ref: "./common/paths/dashboards.yml" /tasks: $ref: "./common/paths/tasks.yml" - /tasks/{taskID}: + "/tasks/{taskID}": $ref: "./common/paths/tasks_taskID.yml" components: parameters: @@ -221,7 +225,7 @@ components: # # For more information and examples, see the following: # - # - [`/authorizations`(#tag/Authorizations-(API-tokens)) endpoints] + # - [`/authorizations`(#tag/Authorizations) endpoints] # - [Authorize API requests]({{% INFLUXDB_DOCS_URL %}}/api-guide/api_intro/#authentication) # - [Manage API tokens]({{% INFLUXDB_DOCS_URL %}}/security/tokens/) TokenAuthentication: @@ -258,7 +262,7 @@ components: ### Related endpoints - - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + - [`/authorizations` endpoints](#tag/Authorizations) ### Related guides diff --git a/src/oss/tags.yml b/src/oss/tags.yml index ac52996e7..11dfb2de0 100644 --- a/src/oss/tags.yml +++ b/src/oss/tags.yml @@ -1,5 +1,5 @@ tags: - - name: Authorizations (API tokens) + - name: Authorizations description: | Create and manage authorizations (API tokens). @@ -7,9 +7,23 @@ tags: permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization. + #### Limitations + + 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. + + API tokens are visible to the user who created the authorization and to any + user with an _[operator token]({{% INFLUXDB_DOCS_URL %}}/security/tokens/#operator-token)_. + In InfluxDB OSS, even if an API token has `read-authorizations` permission, the + token can't be used to view its authorization details. + We recommend creating a generic user to create and manage tokens for writing data. - ### User sessions with authorizations + #### User sessions with authorizations Optionally, when creating an authorization, you can scope it to a specific user. If a user signs in with username and password, creating a _user session_, @@ -93,7 +107,7 @@ tags: - ### Properties + #### Properties A `task` object contains information about an InfluxDB task resource. @@ -101,7 +115,7 @@ tags: - ### Related guides + #### Related guides - [Get started with tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/get-started/) - [Common data processing tasks]({{% INFLUXDB_DOCS_URL %}}/process-data/common-tasks/) @@ -125,7 +139,7 @@ tags: Use the `/api/v2/stacks` endpoints to manage installed template resources. - ### Related guides + #### Related guides - [InfluxDB stacks]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/stacks/) - [InfluxDB templates]({{% INFLUXDB_DOCS_URL %}}/influxdb-templates/) @@ -136,14 +150,14 @@ tags: To grant a user permission to access data, add them as a member of an organization and provide them with an API token. - ### User sessions with authorizations + #### 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 + #### Related guides - [Manage users]({{% INFLUXDB_DOCS_URL %}}/influxdb/latest/users/) - [Create a token scoped to a user]({{% INFLUXDB_DOCS_URL %}}/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) @@ -225,7 +239,7 @@ tags: | `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 + #### 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,