From b15f2fdfdc629f46ceec6aa3b995158b6b4bc1a5 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 19 Jul 2022 14:58:35 -0500 Subject: [PATCH] Api/update specs (#4226) * chore(api): update specs - tasks with scripts for cloud - improve task endpoint docs * chore: update cloud and oss api specs for cloud tasks-with-scripts. - Tasks can be used with invokable scripts. - Reset docs-release/oss branch to head of master due to changes for tasks. Doesn't appear to be anything new in OSS that would break. --- api-docs/cloud/ref.yml | 1448 ++++++++++++++++++++++++---- api-docs/v2.3/ref.yml | 1470 +++++++++++++++++++++++++---- api-docs/v2.3/swaggerV1Compat.yml | 13 +- 3 files changed, 2550 insertions(+), 381 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 0583003ce..460a8a593 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -72,20 +72,26 @@ components: content: application/json: examples: - orgNotFound: - summary: Organization not found + orgProvidedNotFound: + summary: >- + The org or orgID passed doesn't own the token passed in the + header value: code: invalid message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/Error' - description: | + description: > Bad request. + The response body contains detail about the error. + #### InfluxDB OSS - - Returns this error if `org` or `orgID` does not match an organization. + + - Returns this error if an incorrect value is passed for `org` or + `orgID`. GeneralServerError: content: application/json: @@ -1278,7 +1284,7 @@ components: $ref: '#/components/schemas/NodeType' type: object DictItem: - description: A key/value pair in a dictionary + description: A key-value pair in a dictionary. properties: key: $ref: '#/components/schemas/Expression' @@ -2124,9 +2130,11 @@ components: properties: additionalProperties: type: string - description: >- - Key/Value pairs associated with this label. Keys can be removed by - sending an update with an empty value. + 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 @@ -2141,9 +2149,12 @@ components: properties: additionalProperties: type: string - description: >- - Key/Value pairs associated with this label. Keys can be removed by - sending an update with an empty value. + 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 @@ -2170,10 +2181,13 @@ components: type: string properties: additionalProperties: + description: > + Key-value pairs associated with this label. + + + To remove a property, send an update with an empty value (`""`) + for the key. type: string - description: >- - Key/Value pairs associated with this label. Keys can be removed by - sending an update with an empty value. example: color: ffb3b3 description: this is a description @@ -2194,7 +2208,8 @@ components: description: Flux query to be analyzed. properties: query: - description: Flux query script to be analyzed + description: | + The Flux query script to be analyzed. type: string required: - query @@ -3501,13 +3516,6 @@ components: type: string name: type: string - users: - description: >- - An optional list of email address's to be invited to the - organization - items: - type: string - type: array required: - name type: object @@ -3526,27 +3534,55 @@ components: - $ref: '#/components/schemas/Identifier' - $ref: '#/components/schemas/StringLiteral' Query: - description: Query influx using the Flux language + description: Query InfluxDB with the Flux language properties: dialect: $ref: '#/components/schemas/Dialect' extern: $ref: '#/components/schemas/File' now: - description: >- - Specifies the time that should be reported as "now" in the query. - Default is the server's now time. + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. format: date-time type: string params: additionalProperties: true description: > - Enumeration of key/value pairs that respresent parameters to be - injected into query (can only specify either this field or extern - and not both) + Key-value pairs passed as parameters during query execution. + + + To use parameters in your query, pass a _`query`_ with `params` + references (in dot notation)--for example: + + + ```json + query: "from(bucket: params.mybucket) |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + + and pass _`params`_ with the key-value pairs--for example: + + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + + During query execution, InfluxDB passes _`params`_ to your script + and substitutes the values. + + + #### Limitations + + + - If you use _`params`_, you can't use _`extern`_. type: object query: - description: Query script to execute. + description: The query script to execute. type: string type: description: The type of query. Must be "flux". @@ -4505,23 +4541,31 @@ components: type: string cron: description: >- - [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. + 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: description: The description of the task. type: string every: description: >- - An interval ([duration + 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. format: duration type: string flux: - description: The Flux script to run for this task. + 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 id: readOnly: true @@ -4587,13 +4631,35 @@ components: description: The ID of the organization that owns the task. type: string ownerID: - description: The ID of the user who owns this Task. + description: The ID of the user who owns 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 status: $ref: '#/components/schemas/TaskStatusType' - type: - description: The type of the task, useful for filtering a task list. - type: string updatedAt: format: date-time readOnly: true @@ -4602,28 +4668,86 @@ components: - id - name - orgID - - flux type: object TaskCreateRequest: properties: + 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 description: - description: An optional description of the task. + description: The description 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 flux: - description: The Flux script to run for this task. + 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: + description: The name of the task + 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. + format: duration type: string org: - description: The name of the organization that owns this Task. + description: The name of the organization that owns the task. type: string orgID: - description: The ID of the organization that owns this Task. + description: The ID of the organization that owns 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 status: $ref: '#/components/schemas/TaskStatusType' - required: - - flux type: object TaskStatusType: + description: | + `inactive` cancels scheduled runs and prevents manual runs of the task. enum: - active - inactive @@ -4631,23 +4755,29 @@ components: TaskUpdateRequest: properties: cron: - description: Override the 'cron' option in the flux script. + description: Update the 'cron' option in the flux script. type: string description: - description: An optional description of the task. + description: Update the description of the task. type: string every: - description: Override the 'every' option in the flux script. + description: Update the 'every' option in the flux script. type: string flux: - description: The Flux script to run for this task. + description: Update the Flux script that the task runs. type: string name: - description: Override the 'name' option in the flux script. + description: Update the 'name' option in the flux script. type: string offset: - description: Override the 'offset' option in the flux script. + description: Update the 'offset' option in the flux script. type: string + scriptID: + description: Update the 'scriptID' of the task. + type: string + scriptParameters: + description: Update the 'scriptParameters' of the task. + type: object status: $ref: '#/components/schemas/TaskStatusType' type: object @@ -8496,7 +8626,27 @@ paths: - Deleted the data. '400': - $ref: '#/components/responses/BadRequestError' + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: > + Bad request. + + The response body contains detail about the error. + + + #### InfluxDB OSS + + + - Returns this error if `org` or `orgID` does not match an + organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -8716,6 +8866,11 @@ paths: - Users /api/v2/me/password: put: + description: | + #### InfluxDB Cloud + + InfluxDB Cloud does not support changing user passwords through the API. + Use the InfluxDB Cloud user interface to update your password. operationId: PutMePassword parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8729,6 +8884,12 @@ paths: responses: '204': description: Success. The password was updated. + '400': + description: > + Bad request. + + InfluxDB Cloud does not support changing passwords through the API + and always responds with this status. default: content: application/json: @@ -10114,7 +10275,27 @@ paths: description: Trace ID of a request. type: string '400': - $ref: '#/components/responses/BadRequestError' + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: > + Bad request. + + The response body contains detail about the error. + + + #### InfluxDB OSS + + + - Returns this error if `org` or `orgID` does not match an + organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -10159,6 +10340,44 @@ paths: |> filter(fn: (r) => r._measurement == "example-measurement")' /api/v2/query/analyze: post: + description: > + Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for + syntax + + errors and returns the list of errors. + + + In the following example `Query` object, `query` is missing a `from()` + property key: + + ```json + { "query": "from(: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + ``` + + Passing this to `/api/v2/analyze` returns an `errors` list that contains + an error object for the missing key. + + + #### Limitations + + + - The endpoint doesn't validate values in the query--for example: + + - The following query has correct syntax, but contains an incorrect `from()` property key: + + ```json + { "query": "from(foo: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + ``` + + Passing this to `/api/v2/analyze` returns an empty `errors` list. operationId: PostQueryAnalyze parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10178,30 +10397,156 @@ paths: '200': content: application/json: + examples: + missingQueryPropertyKey: + description: > + Returns an error object if the Flux query is missing a + property key. + + + The following example is missing the `bucket` property key: + + ```json + { + "query": "from(: \"iot_center\")\ + + ... + + } + ``` + summary: Missing property key error + value: + errors: + - character: 0 + column: 6 + line: 1 + message: missing property key schema: $ref: '#/components/schemas/AnalyzeQueryResponse' - description: Query analyze results. Errors will be empty if the query is valid. + description: > + Success. + + The response body contains the list of `errors`. + + If the query syntax is valid, the endpoint returns an empty `errors` + list. + '400': + content: + application/json: + examples: + invalidJSONStringValue: + description: >- + If the request body contains invalid JSON, returns `invalid` + and problem detail. + summary: Invalid JSON + value: + code: invalid + message: >- + invalid json: invalid character '\'' looking for beginning + of value + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the problem. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: invalid + type: string default: content: application/json: + examples: + emptyJSONObject: + description: > + If the request body contains an empty JSON object, returns + `internal error`. + summary: Empty JSON object in request body + value: + code: internal error + message: An internal error has occurred - check server logs schema: $ref: '#/components/schemas/Error' description: Internal server error headers: X-Influx-Error: - description: Error string describing the problem + description: A string that describes the problem. schema: type: string X-Influx-Reference: - description: Reference code unique to the error type + description: The numeric reference code for the error type. schema: type: integer + X-Platform-Error-Code: + description: The reason for the error. + schema: + example: internal error + type: string summary: Analyze a Flux query tags: - Query + x-codeSamples: + - label: 'cURL: Analyze a Flux query' + lang: Shell + source: | + curl -v --request POST \ + "http://localhost:8086/api/v2/query/analyze" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header 'Content-type: application/json' \ + --header 'Accept: application/json' \ + --data-binary @- << EOF + { "query": "from(bucket: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + EOF /api/v2/query/ast: post: - description: Analyzes flux query and generates a query specification. + description: > + Analyzes a Flux query and returns a complete package source [Abstract + Syntax + + Tree + (AST)](https:///influxdb/v2.3/reference/glossary/#abstract-syntax-tree) + + for the query. + + + Use this endpoint for deep query analysis such as debugging unexpected + query + + results. + + + A Flux query AST provides a semantic, tree-like representation with + contextual + + information about the query. The AST illustrates how the query is + distributed + + into different components for execution. + + + + #### Limitations + + + - The endpoint doesn't validate values in the query--for example: + + The following query has correct syntax, but contains an incorrect `from()` property key: + ```json + { "query": "from(foo: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")" + } + ``` + Passing this to `/api/v2/query/ast` will return a successful response + with a generated AST. operationId: PostQueryAst parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10216,23 +10561,410 @@ paths: application/json: schema: $ref: '#/components/schemas/LanguageRequest' - description: Analyzed Flux query to generate abstract syntax tree. + description: The Flux query to analyze. responses: '200': content: application/json: + examples: + successResponse: + value: + ast: + files: + - body: + - expression: + argument: + argument: + arguments: + - location: + end: + column: 25 + line: 1 + source: 'bucket: "example-bucket"' + start: + column: 6 + line: 1 + properties: + - key: + location: + end: + column: 12 + line: 1 + source: bucket + start: + column: 6 + line: 1 + name: bucket + type: Identifier + location: + end: + column: 25 + line: 1 + source: 'bucket: "example-bucket"' + start: + column: 6 + line: 1 + type: Property + value: + location: + end: + column: 25 + line: 1 + source: '"example-bucket"' + start: + column: 14 + line: 1 + type: StringLiteral + value: example-bucket + type: ObjectExpression + callee: + location: + end: + column: 5 + line: 1 + source: from + start: + column: 1 + line: 1 + name: from + type: Identifier + location: + end: + column: 26 + line: 1 + source: 'from(bucket: "example-bucket")' + start: + column: 1 + line: 1 + type: CallExpression + call: + arguments: + - location: + end: + column: 46 + line: 1 + source: 'start: -5m' + start: + column: 36 + line: 1 + properties: + - key: + location: + end: + column: 41 + line: 1 + source: start + start: + column: 36 + line: 1 + name: start + type: Identifier + location: + end: + column: 46 + line: 1 + source: 'start: -5m' + start: + column: 36 + line: 1 + type: Property + value: + argument: + location: + end: + column: 46 + line: 1 + source: 5m + start: + column: 44 + line: 1 + type: DurationLiteral + values: + - magnitude: 5 + unit: m + location: + end: + column: 46 + line: 1 + source: '-5m' + start: + column: 43 + line: 1 + operator: '-' + type: UnaryExpression + type: ObjectExpression + callee: + location: + end: + column: 35 + line: 1 + source: range + start: + column: 30 + line: 1 + name: range + type: Identifier + location: + end: + column: 47 + line: 1 + source: 'range(start: -5m)' + start: + column: 30 + line: 1 + type: CallExpression + location: + end: + column: 47 + line: 1 + source: >- + from(bucket: "example-bucket") |> + range(start: -5m) + start: + column: 1 + line: 1 + type: PipeExpression + call: + arguments: + - location: + end: + column: 108 + line: 1 + source: >- + fn: (r) => r._measurement == + "example-measurement" + start: + column: 58 + line: 1 + properties: + - key: + location: + end: + column: 60 + line: 1 + source: fn + start: + column: 58 + line: 1 + name: fn + type: Identifier + location: + end: + column: 108 + line: 1 + source: >- + fn: (r) => r._measurement == + "example-measurement" + start: + column: 58 + line: 1 + type: Property + value: + body: + left: + location: + end: + column: 83 + line: 1 + source: r._measurement + start: + column: 69 + line: 1 + object: + location: + end: + column: 70 + line: 1 + source: r + start: + column: 69 + line: 1 + name: r + type: Identifier + property: + location: + end: + column: 83 + line: 1 + source: _measurement + start: + column: 71 + line: 1 + name: _measurement + type: Identifier + type: MemberExpression + location: + end: + column: 108 + line: 1 + source: r._measurement == "example-measurement" + start: + column: 69 + line: 1 + operator: '==' + right: + location: + end: + column: 108 + line: 1 + source: '"example-measurement"' + start: + column: 87 + line: 1 + type: StringLiteral + value: example-measurement + type: BinaryExpression + location: + end: + column: 108 + line: 1 + source: >- + (r) => r._measurement == + "example-measurement" + start: + column: 62 + line: 1 + params: + - key: + location: + end: + column: 64 + line: 1 + source: r + start: + column: 63 + line: 1 + name: r + type: Identifier + location: + end: + column: 64 + line: 1 + source: r + start: + column: 63 + line: 1 + type: Property + value: null + type: FunctionExpression + type: ObjectExpression + callee: + location: + end: + column: 57 + line: 1 + source: filter + start: + column: 51 + line: 1 + name: filter + type: Identifier + location: + end: + column: 109 + line: 1 + source: >- + filter(fn: (r) => r._measurement == + "example-measurement") + start: + column: 51 + line: 1 + type: CallExpression + location: + end: + column: 109 + line: 1 + source: >- + from(bucket: "example-bucket") |> + range(start: -5m) |> filter(fn: (r) => + r._measurement == "example-measurement") + start: + column: 1 + line: 1 + type: PipeExpression + location: + end: + column: 109 + line: 1 + source: >- + from(bucket: "example-bucket") |> range(start: + -5m) |> filter(fn: (r) => r._measurement == + "example-measurement") + start: + column: 1 + line: 1 + type: ExpressionStatement + imports: null + location: + end: + column: 109 + line: 1 + source: >- + from(bucket: "example-bucket") |> range(start: + -5m) |> filter(fn: (r) => r._measurement == + "example-measurement") + start: + column: 1 + line: 1 + metadata: parser-type=rust + package: null + type: File + package: main + type: Package schema: $ref: '#/components/schemas/ASTResponse' - description: Abstract syntax tree of the flux query. + description: > + Success. + + The response body contains an Abstract Syntax Tree (AST) of the Flux + query. + '400': + content: + application/json: + examples: + invalidASTValue: + description: > + If the request body contains a missing property key in + `from()`, + + returns `invalid` and problem detail. + summary: Invalid AST + value: + code: invalid + message: 'invalid AST: loc 1:6-1:19: missing property key' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the problem. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: invalid + type: string default: content: application/json: schema: $ref: '#/components/schemas/Error' - description: Any response other than 200 is an internal server error - summary: Generate an Abstract Syntax Tree (AST) from a query + description: Internal server error. + summary: Generate a query Abstract Syntax Tree (AST) tags: - Query + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST 'INFLUX_URL/api/v2/query/ast' \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json \ + --header 'Authorization: Token INFLUX_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' /api/v2/query/suggestions: get: operationId: GetQuerySuggestions @@ -10811,43 +11543,80 @@ paths: - Templates /api/v2/tasks: get: + description: > + Retrieves a list of [tasks](/influxdb/cloud/process-data/). + + + 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`. operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - - description: Returns task with a specific name. + - description: | + Task name. + Only returns tasks with this name. + Different tasks may have the same name. in: query name: name schema: type: string - - description: Return tasks after a specified ID. + - description: | + Task ID. + Only returns tasks created after this task. in: query name: after schema: type: string - - description: Filter tasks to a specific user ID. + - description: | + User ID. + Only returns tasks owned by this user. in: query name: user schema: type: string - - description: Filter tasks to a specific organization name. + - description: | + Organization name. + Only returns tasks owned by this organization. in: query name: org schema: type: string - - description: Filter tasks to a specific organization ID. + - description: | + Organization ID. + Only returns tasks owned by this organization. in: query name: orgID schema: type: string - - description: Filter tasks by a status--"inactive" or "active". - in: query + - in: query name: status schema: + description: | + Task status (`active` or `inactive`). + Only returns tasks with this status. enum: - active - inactive type: string - - description: The non-zero number of tasks to return + - description: > + Limits the number of tasks returned. Default is `100`. + + + To reduce the payload size, combine _`type=basic`_ and _`limit`_ + (see _Request samples_) + + For more information about the `basic` response, see the _`type`_ + parameter. + examples: + all: + summary: Return all tasks, without pagination. + value: '-1' + minPaginated: + summary: Return a maximum of 50 tasks. + value: '50' in: query name: limit schema: @@ -10871,7 +11640,15 @@ paths: enum: - name type: string - - description: Type of task, unset by default. + - description: > + Task type (`basic` or `system`). + + + The default (`system`) response contains all the metadata properties + for tasks. + + To reduce the payload size, pass `basic` to omit some task + properties (`flux`, `createdAt`, `updatedAt`) from the response. in: query name: type required: false @@ -10887,18 +11664,54 @@ paths: application/json: schema: $ref: '#/components/schemas/Tasks' - description: A list of tasks + description: | + Success. + The response body contains the list of tasks. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: List all tasks tags: - Data I/O endpoints - Tasks + x-codeSamples: + - label: 'cURL: all tasks, `basic` output' + lang: Shell + source: > + curl https://cloud2.influxdata.com/api/v2/tasks/?limit=-1&type=basic + \ + --header 'Content-Type: application/json' \ + --header 'Authorization: Token INFLUX_API_TOKEN' post: + description: > + Creates a [task](/influxdb/cloud/process-data/) and returns the created + task. + + + Use this endpoint to create a scheduled task that runs a Flux script. + + In your task, provide one of the following: + + - _`flux`_ property with an inline Flux script + - _`scriptID`_ property with an [invokable script](#tag/Invokable-Scripts) ID + + #### InfluxDB Cloud + + - Requires either _`flux`_ (Flux query) or _`scriptID`_ (invokable script ID) in the task. + + #### Related guides + + + - [Create a + task](/influxdb/cloud/process-data/manage-tasks/create-task/). + + - [Common tasks](/influxdb/cloud/process-data/common-tasks/) + + - [Task configuration + options](/influxdb/cloud/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10907,7 +11720,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - description: Task to create + description: The task to create required: true responses: '201': @@ -10915,20 +11728,103 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: Task created + description: >- + Success. The response body contains a `tasks` list with the new + task. + '400': + content: + application/json: + examples: + fluxAndScriptError: + summary: The request body can't contain both flux and scriptID + value: + code: invalid + message: >- + failed to decode request: can not provide both scriptID + and flux + missingFluxError: + summary: The request body requires either flux or scriptID + value: + code: invalid + message: 'failed to decode request: flux required' + schema: + $ref: '#/components/responses/BadRequestError' + description: | + Bad request + + #### InfluxDB Cloud + + - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_. + - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error - summary: Create a new task + summary: Create a task tags: - Data I/O endpoints - Tasks + x-codeSamples: + - label: 'cURL: create a flux query task' + lang: Shell + source: | + curl -v --request POST \ + https://cloud2.influxdata.com/api/v2/tasks \ + --header "Content-type: application/json" \ + --header "Authorization: Token INFLUX_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 script task' + lang: Shell + source: | + curl -v --request POST \ + https://cloud2.influxdata.com/api/v2/tasks \ + --header "Content-type: application/json" \ + --header "Authorization: Token INFLUX_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 a task and all associated records + description: > + 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. + + + 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' @@ -10940,17 +11836,24 @@ paths: type: string responses: '204': - description: Task deleted + description: Success. Task and runs are deleted. Scheduled runs are canceled. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Delete a task tags: - Tasks get: + description: | + Retrieves a [task](/influxdb/cloud/reference/glossary/#task) + by task ID. operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10966,19 +11869,40 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: Task details + description: Success. The response body contains the task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve a task tags: - Data I/O endpoints - Tasks patch: - description: Update a task. This will cancel all queued runs. + description: > + Updates a task and then cancels all scheduled runs of the task. + + + Use this endpoint to modify task properties (for example: `cron`, + `name`, `flux`, `status`). + + Once InfluxDB applies the update, it cancels all scheduled runs of the + task. + + + To update a task, pass an object that contains the updated key-value + pairs. + + To activate or inactivate a task, set the `status` property. + + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs + of the task. operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10993,7 +11917,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: Task update to apply + description: An object that contains updated task properties to apply. required: true responses: '200': @@ -11001,22 +11925,30 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: Task updated + description: Success. The response body contains the updated task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Update a task tags: - Tasks /api/v2/tasks/{taskID}/labels: get: + description: | + Retrieves a list of all labels for a task. + + Labels may be used for grouping and filtering tasks. operationId: GetTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: The ID of the task to retrieve labels for. in: path name: taskID required: true @@ -11028,21 +11960,33 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a task + description: >- + Success. The response body contains a list of all labels for the + task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a task + $ref: '#/components/responses/GeneralServerError' + summary: List labels for a task tags: - Tasks post: + description: > + Adds a label to a task. + + + Use this endpoint to add a label that you can use to filter tasks in the + InfluxDB UI. operationId: PostTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: The ID of the task to label. in: path name: taskID required: true @@ -11053,7 +11997,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelMapping' - description: Label to add + description: An object that contains a _`labelID`_ to add to the task. required: true responses: '201': @@ -11061,28 +12005,36 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: A list of all labels for a task + description: >- + Success. The response body contains a list of all labels for the + task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Add a label to a task tags: - Tasks /api/v2/tasks/{taskID}/labels/{labelID}: delete: + description: | + Deletes a label from a task. operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: The ID of the task to delete the label from. in: path name: taskID required: true schema: type: string - - description: The label ID. + - description: The ID of the label to delete. in: path name: labelID required: true @@ -11090,24 +12042,37 @@ paths: type: string responses: '204': - description: Delete has been accepted + description: Success. The label is deleted. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Task not found + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Delete a label from a task tags: - Tasks /api/v2/tasks/{taskID}/logs: get: + description: > + Retrieves a list of all logs for a + [task](/influxdb/cloud/reference/glossary/#task). + + + When an InfluxDB task runs, a “run” record is created in the task’s + history. + + Logs associated with each run provide relevant log messages, timestamps, + and the exit status of the run attempt. + + + Use this endpoint to retrieve only the log events for a task, + + without additional task metadata. operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11121,15 +12086,62 @@ paths: '200': content: application/json: + examples: + taskFailure: + summary: Events for a failed task. + value: + events: + - message: >- + Started task from script: "option task = {name: \"test + task\", every: 3d, offset: 0s}" + runID: 09a946fc3167d000 + time: '2022-07-13T07:06:54.198167Z' + - message: Completed(failed) + runID: 09a946fc3167d000 + time: '2022-07-13T07:07:13.104037Z' + - message: >- + error exhausting result iterator: error in query + specification while starting program: this Flux script + returns no streaming data. Consider adding a "yield" + or invoking streaming functions directly, without + performing an assignment + runID: 09a946fc3167d000 + time: '2022-07-13T08:24:37.115323Z' + taskSuccess: + summary: Events for successful task. + value: + events: + - message: >- + Started task from script: "option task = {name: + \"task1\", every: 30m} from(bucket: \"iot_center\") |> + range(start: -90d) |> filter(fn: (r) => r._measurement + == \"environment\") |> aggregateWindow(every: 1h, fn: + mean)" + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' schema: $ref: '#/components/schemas/Logs' - description: All logs for a task + 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. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve all logs for a task tags: - Tasks @@ -11396,6 +12408,14 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs/{runID}: delete: + description: | + Cancels a running [task](/influxdb/cloud/reference/glossary/#task). + + Use this endpoint with InfluxDB OSS to cancel a running task. + + #### InfluxDB Cloud + + - Doesn't support this operation. operationId: DeleteTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11405,7 +12425,7 @@ paths: required: true schema: type: string - - description: The run ID. + - description: The ID of the task run to cancel. in: path name: runID required: true @@ -11413,7 +12433,18 @@ paths: type: string responses: '204': - description: Delete has been accepted. + description: | + Success. The `DELETE` is accepted and the run will be cancelled. + + #### InfluxDB Cloud + + - Doesn't support this operation. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' '405': content: application/json: @@ -11424,26 +12455,25 @@ paths: #### InfluxDB Cloud - - Cancelling task runs is not supported in InfluxDB Cloud. + - Always returns this error; cancelling a task run is not supported. #### InfluxDB OSS - Doesn't return this error. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: | - Cancel a running task. - - #### InfluxDB Cloud - - - Doesn't support this operation. + $ref: '#/components/responses/GeneralServerError' + summary: Cancel a running task tags: - Tasks get: + description: > + Retrieves a specific run for a + [task](/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' @@ -11463,16 +12493,50 @@ paths: '200': content: application/json: + examples: + runSuccess: + summary: A successful task run. + value: + finishedAt: '2022-07-18T14:46:07.308254Z' + id: 09b070dadaa7d000 + links: + logs: >- + /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs + retry: >- + /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry + self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 + task: /api/v2/tasks/0996e56b2f378000 + log: + - message: >- + Started task from script: "option task = {name: + \"task1\", every: 30m} from(bucket: \"iot_center\") |> + range(start: -90d) |> filter(fn: (r) => r._measurement + == \"environment\") |> + aggregateWindow(every: 1h, fn: mean)" + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' + requestedAt: '2022-07-18T14:46:06Z' + scheduledFor: '2022-07-18T14:46:06Z' + startedAt: '2022-07-18T14:46:07.16222Z' + status: success + taskID: 0996e56b2f378000 schema: $ref: '#/components/schemas/Run' - description: Returns the run record. + description: Success. The response body contains the task run. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Retrieve a single run for a task. + $ref: '#/components/responses/GeneralServerError' + summary: Retrieve a run for a task. tags: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/logs: @@ -12216,6 +13280,11 @@ paths: - Users /api/v2/users/{userID}/password: post: + description: | + #### InfluxDB Cloud + + InfluxDB Cloud does not support changing user passwords through the API. + Use the InfluxDB Cloud user interface to update your password. operationId: PostUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12235,6 +13304,12 @@ paths: responses: '204': description: Password successfully updated + '400': + description: > + Bad request. + + InfluxDB Cloud doesn't support changing passwords through the API + and always responds with this status. default: content: application/json: @@ -12766,8 +13841,8 @@ paths: examples: measurementSchemaFieldTypeConflict: summary: >- - InfluxDB Cloud field type conflict thrown by an explicit - bucket schema + (Cloud) field type conflict thrown by an explicit bucket + schema value: code: invalid message: >- @@ -12776,13 +13851,36 @@ paths: temperature="90.5",humidity=70.0 1632850122': schema: field type for field "temperature" not permitted by schema; got String but expected Float + orgNotFound: + summary: (OSS) organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/LineProtocolError' - description: | - Bad request. - The line protocol data in the request is malformed. + description: > + Bad request. The response body contains detail about the error. + + + InfluxDB returns this error if the line protocol data in the request + is malformed. + The response body contains the first malformed line in the data. + InfluxDB rejected the batch and did not write any data. + + + #### InfluxDB Cloud + + + - Returns this error for bucket schema conflicts. + + + #### InfluxDB OSS + + + - Returns this error if `org` or `orgID` does not match an + organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -13577,7 +14675,31 @@ tags: - name: Signin - name: Signout - name: System information endpoints - - name: Tasks + - description: > + Process and analyze your data with tasks in the InfluxDB task engine. + + With tasks, you can schedule Flux scripts to query, analyze, modify, and + act on data. + + In InfluxDB Cloud, you can create tasks that run [invokable + scripts](#tag/Invokable-Scripts) + + with parameters. + + + Use the `/api/v2/tasks` endpoints to create and manage tasks, retry task + runs, and retrieve run logs. + + + #### Related guides + + + - [Common data processing + tasks](/influxdb/cloud/process-data/common-tasks/) + + - [Invoke custom scripts as API + endpoints](/influxdb/cloud/api-guide/api-invokable-scripts/) + name: Tasks - name: Telegraf Plugins - name: Telegrafs - name: Templates diff --git a/api-docs/v2.3/ref.yml b/api-docs/v2.3/ref.yml index 031dc1b36..2f164fc14 100644 --- a/api-docs/v2.3/ref.yml +++ b/api-docs/v2.3/ref.yml @@ -72,20 +72,26 @@ components: content: application/json: examples: - orgNotFound: - summary: Organization not found + orgProvidedNotFound: + summary: >- + The org or orgID passed doesn't own the token passed in the + header value: code: invalid message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/Error' - description: | + description: > Bad request. + The response body contains detail about the error. + #### InfluxDB OSS - - Returns this error if `org` or `orgID` does not match an organization. + + - Returns this error if an incorrect value is passed for `org` or + `orgID`. GeneralServerError: content: application/json: @@ -1334,7 +1340,7 @@ components: $ref: '#/components/schemas/NodeType' type: object DictItem: - description: A key/value pair in a dictionary + description: A key-value pair in a dictionary. properties: key: $ref: '#/components/schemas/Expression' @@ -2180,9 +2186,11 @@ components: properties: additionalProperties: type: string - description: >- - Key/Value pairs associated with this label. Keys can be removed by - sending an update with an empty value. + 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 @@ -2197,9 +2205,12 @@ components: properties: additionalProperties: type: string - description: >- - Key/Value pairs associated with this label. Keys can be removed by - sending an update with an empty value. + 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 @@ -2226,10 +2237,13 @@ components: type: string properties: additionalProperties: + description: > + Key-value pairs associated with this label. + + + To remove a property, send an update with an empty value (`""`) + for the key. type: string - description: >- - Key/Value pairs associated with this label. Keys can be removed by - sending an update with an empty value. example: color: ffb3b3 description: this is a description @@ -2250,7 +2264,8 @@ components: description: Flux query to be analyzed. properties: query: - description: Flux query script to be analyzed + description: | + The Flux query script to be analyzed. type: string required: - query @@ -3312,13 +3327,6 @@ components: type: string name: type: string - users: - description: >- - An optional list of email address's to be invited to the - organization - items: - type: string - type: array required: - name type: object @@ -3337,27 +3345,55 @@ components: - $ref: '#/components/schemas/Identifier' - $ref: '#/components/schemas/StringLiteral' Query: - description: Query influx using the Flux language + description: Query InfluxDB with the Flux language properties: dialect: $ref: '#/components/schemas/Dialect' extern: $ref: '#/components/schemas/File' now: - description: >- - Specifies the time that should be reported as "now" in the query. - Default is the server's now time. + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. format: date-time type: string params: additionalProperties: true description: > - Enumeration of key/value pairs that respresent parameters to be - injected into query (can only specify either this field or extern - and not both) + Key-value pairs passed as parameters during query execution. + + + To use parameters in your query, pass a _`query`_ with `params` + references (in dot notation)--for example: + + + ```json + query: "from(bucket: params.mybucket) |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + + and pass _`params`_ with the key-value pairs--for example: + + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + + During query execution, InfluxDB passes _`params`_ to your script + and substitutes the values. + + + #### Limitations + + + - If you use _`params`_, you can't use _`extern`_. type: object query: - description: Query script to execute. + description: The query script to execute. type: string type: description: The type of query. Must be "flux". @@ -4679,7 +4715,7 @@ components: format: duration type: string flux: - description: The Flux script to run for this task. + description: The Flux script that the task runs. type: string id: readOnly: true @@ -4745,13 +4781,10 @@ components: description: The ID of the organization that owns the task. type: string ownerID: - description: The ID of the user who owns this Task. + description: The ID of the user who owns the Task. type: string status: $ref: '#/components/schemas/TaskStatusType' - type: - description: The type of the task, useful for filtering a task list. - type: string updatedAt: format: date-time readOnly: true @@ -4782,6 +4815,8 @@ components: - flux type: object TaskStatusType: + description: | + `inactive` cancels scheduled runs and prevents manual runs of the task. enum: - active - inactive @@ -4789,22 +4824,22 @@ components: TaskUpdateRequest: properties: cron: - description: Override the 'cron' option in the flux script. + description: Update the 'cron' option in the flux script. type: string description: - description: An optional description of the task. + description: Update the description of the task. type: string every: - description: Override the 'every' option in the flux script. + description: Update the 'every' option in the flux script. type: string flux: - description: The Flux script to run for this task. + description: The Flux script that the task runs. type: string name: - description: Override the 'name' option in the flux script. + description: Update the 'name' option in the flux script. type: string offset: - description: Override the 'offset' option in the flux script. + description: Update the 'offset' option in the flux script. type: string status: $ref: '#/components/schemas/TaskStatusType' @@ -6337,6 +6372,7 @@ paths: summary: List all top level routes tags: - Routes + - System information endpoints /api/v2/authorizations: get: operationId: GetAuthorizations @@ -6375,6 +6411,7 @@ paths: summary: List all authorizations tags: - Authorizations + - Security and access endpoints post: operationId: PostAuthorizations parameters: @@ -6445,6 +6482,7 @@ paths: summary: Retrieve an authorization tags: - Authorizations + - Security and access endpoints patch: operationId: PatchAuthorizationsID parameters: @@ -7407,6 +7445,7 @@ paths: summary: Retrieve runtime configuration tags: - Config + - System information endpoints /api/v2/dashboards: get: operationId: GetDashboards @@ -8411,7 +8450,7 @@ paths: externalDocs: description: InfluxDB duration url: >- - https://docs.influxdata.com/influxdb/v2.1/reference/glossary/#duration + https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration format: duration type: string responses: @@ -8438,6 +8477,7 @@ paths: summary: Retrieve all runtime profiles tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: Get all profiles' lang: Shell @@ -8570,6 +8610,7 @@ paths: summary: Retrieve the memory allocations runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -8669,6 +8710,7 @@ paths: summary: Retrieve the block runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -8713,6 +8755,7 @@ paths: summary: Retrieve the command line invocation tags: - Debug + - System information endpoints /debug/pprof/goroutine: get: description: > @@ -8789,6 +8832,7 @@ paths: summary: Retrieve the goroutines runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -8907,6 +8951,7 @@ paths: summary: Retrieve the heap runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -9017,6 +9062,7 @@ paths: summary: Retrieve the mutual exclusion (mutex) runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -9081,6 +9127,7 @@ paths: summary: Retrieve the CPU runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -9177,6 +9224,7 @@ paths: summary: Retrieve the threadcreate runtime profile tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell @@ -9233,6 +9281,7 @@ paths: summary: Retrieve the runtime execution trace tags: - Debug + - System information endpoints x-codeSamples: - label: 'Shell: go tool trace' lang: Shell @@ -9429,7 +9478,27 @@ paths: - Deleted the data. '400': - $ref: '#/components/responses/BadRequestError' + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: > + Bad request. + + The response body contains detail about the error. + + + #### InfluxDB OSS + + + - Returns this error if `org` or `orgID` does not match an + organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -9440,7 +9509,21 @@ paths: $ref: '#/components/responses/GeneralServerError' summary: Delete data tags: + - Data I/O endpoints - Delete + x-codeSamples: + - label: cURL + lang: Shell + source: > + curl --request POST + INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ + --header 'Authorization: Token INFLUX_TOKEN' \ + --header 'Content-Type: application/json' \ + --data '{ + "start": "2020-03-01T00:00:00Z", + "stop": "2020-11-14T00:00:00Z", + "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")" + }' /api/v2/flags: get: operationId: GetFlags @@ -9490,6 +9573,7 @@ paths: summary: Retrieve the health of the instance tags: - Health + - System information endpoints /api/v2/labels: get: operationId: GetLabels @@ -9663,6 +9747,11 @@ paths: - Users /api/v2/me/password: put: + description: | + #### InfluxDB Cloud + + InfluxDB Cloud does not support changing user passwords through the API. + Use the InfluxDB Cloud user interface to update your password. operationId: PutMePassword parameters: - $ref: '#/components/parameters/TraceSpan' @@ -9676,6 +9765,12 @@ paths: responses: '204': description: Success. The password was updated. + '400': + description: > + Bad request. + + InfluxDB Cloud does not support changing passwords through the API + and always responds with this status. default: content: application/json: @@ -9703,7 +9798,7 @@ paths: metrics](/influxdb/v2.3/reference/internals/metrics/). - Learn how to use InfluxDB to [scrape Prometheus - metrics](/influxdb/v2.3write-data/developer-tools/scrape-prometheus-metrics/). + metrics](/influxdb/v2.3/write-data/developer-tools/scrape-prometheus-metrics/). - Learn how InfluxDB [parses the Prometheus exposition format](/influxdb/v2.3/reference/prometheus-metrics/). @@ -9768,6 +9863,7 @@ paths: summary: Retrieve workload performance metrics tags: - Metrics + - System information endpoints /api/v2/notificationEndpoints: get: operationId: GetNotificationEndpoints @@ -10428,6 +10524,7 @@ paths: summary: List all organizations tags: - Organizations + - Security and access endpoints post: operationId: PostOrgs parameters: @@ -10510,6 +10607,7 @@ paths: summary: Retrieve an organization tags: - Organizations + - Security and access endpoints patch: operationId: PatchOrgsID parameters: @@ -10576,6 +10674,7 @@ paths: summary: List all members of an organization tags: - Organizations + - Security and access endpoints post: operationId: PostOrgsIDMembers parameters: @@ -10638,6 +10737,7 @@ paths: summary: Remove a member from an organization tags: - Organizations + - Security and access endpoints /api/v2/orgs/{orgID}/owners: get: operationId: GetOrgsIDOwners @@ -10671,6 +10771,7 @@ paths: summary: List all owners of an organization tags: - Organizations + - Security and access endpoints post: operationId: PostOrgsIDOwners parameters: @@ -10733,6 +10834,7 @@ paths: summary: Remove an owner from an organization tags: - Organizations + - Security and access endpoints /api/v2/orgs/{orgID}/secrets: get: operationId: GetOrgsIDSecrets @@ -10760,6 +10862,7 @@ paths: summary: List all secret keys for an organization tags: - Secrets + - Security and access endpoints patch: operationId: PatchOrgsIDSecrets parameters: @@ -10815,6 +10918,7 @@ paths: summary: Delete a secret from an organization tags: - Secrets + - Security and access endpoints /api/v2/orgs/{orgID}/secrets/delete: post: deprecated: true @@ -10846,6 +10950,7 @@ paths: summary: Delete secrets from an organization tags: - Secrets + - Security and access endpoints /ping: get: description: Returns the status and InfluxDB version of the instance. @@ -10868,6 +10973,7 @@ paths: summary: Get the status and version of the instance tags: - Ping + - System information endpoints head: description: Returns the status and InfluxDB version of the instance. operationId: HeadPing @@ -10895,7 +11001,7 @@ paths: Retrieves data from buckets. - Use this endpoint to send a Flux query request and retreive data from a + Use this endpoint to send a Flux query request and retrieve data from a bucket. @@ -10998,13 +11104,16 @@ paths: responses: '200': content: - text/csv: + application/csv: + example: > + result,table,_start,_stop,_time,region,host,_value + + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 schema: - example: > - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 type: string description: Success. The response body contains query results. headers: @@ -11027,7 +11136,27 @@ paths: description: Trace ID of a request. type: string '400': - $ref: '#/components/responses/BadRequestError' + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: > + Bad request. + + The response body contains detail about the error. + + + #### InfluxDB OSS + + + - Returns this error if `org` or `orgID` does not match an + organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -11057,9 +11186,59 @@ paths: $ref: '#/components/responses/GeneralServerError' summary: Query data tags: + - Data I/O endpoints - Query + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' /api/v2/query/analyze: post: + description: > + Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for + syntax + + errors and returns the list of errors. + + + In the following example `Query` object, `query` is missing a `from()` + property key: + + ```json + { "query": "from(: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + ``` + + Passing this to `/api/v2/analyze` returns an `errors` list that contains + an error object for the missing key. + + + #### Limitations + + + - The endpoint doesn't validate values in the query--for example: + + - The following query has correct syntax, but contains an incorrect `from()` property key: + + ```json + { "query": "from(foo: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + ``` + + Passing this to `/api/v2/analyze` returns an empty `errors` list. operationId: PostQueryAnalyze parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11079,30 +11258,156 @@ paths: '200': content: application/json: + examples: + missingQueryPropertyKey: + description: > + Returns an error object if the Flux query is missing a + property key. + + + The following example is missing the `bucket` property key: + + ```json + { + "query": "from(: \"iot_center\")\ + + ... + + } + ``` + summary: Missing property key error + value: + errors: + - character: 0 + column: 6 + line: 1 + message: missing property key schema: $ref: '#/components/schemas/AnalyzeQueryResponse' - description: Query analyze results. Errors will be empty if the query is valid. + description: > + Success. + + The response body contains the list of `errors`. + + If the query syntax is valid, the endpoint returns an empty `errors` + list. + '400': + content: + application/json: + examples: + invalidJSONStringValue: + description: >- + If the request body contains invalid JSON, returns `invalid` + and problem detail. + summary: Invalid JSON + value: + code: invalid + message: >- + invalid json: invalid character '\'' looking for beginning + of value + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the problem. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: invalid + type: string default: content: application/json: + examples: + emptyJSONObject: + description: > + If the request body contains an empty JSON object, returns + `internal error`. + summary: Empty JSON object in request body + value: + code: internal error + message: An internal error has occurred - check server logs schema: $ref: '#/components/schemas/Error' description: Internal server error headers: X-Influx-Error: - description: Error string describing the problem + description: A string that describes the problem. schema: type: string X-Influx-Reference: - description: Reference code unique to the error type + description: The numeric reference code for the error type. schema: type: integer + X-Platform-Error-Code: + description: The reason for the error. + schema: + example: internal error + type: string summary: Analyze a Flux query tags: - Query + x-codeSamples: + - label: 'cURL: Analyze a Flux query' + lang: Shell + source: | + curl -v --request POST \ + "http://localhost:8086/api/v2/query/analyze" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header 'Content-type: application/json' \ + --header 'Accept: application/json' \ + --data-binary @- << EOF + { "query": "from(bucket: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + EOF /api/v2/query/ast: post: - description: Analyzes flux query and generates a query specification. + description: > + Analyzes a Flux query and returns a complete package source [Abstract + Syntax + + Tree + (AST)](https:///influxdb/v2.3/reference/glossary/#abstract-syntax-tree) + + for the query. + + + Use this endpoint for deep query analysis such as debugging unexpected + query + + results. + + + A Flux query AST provides a semantic, tree-like representation with + contextual + + information about the query. The AST illustrates how the query is + distributed + + into different components for execution. + + + + #### Limitations + + + - The endpoint doesn't validate values in the query--for example: + + The following query has correct syntax, but contains an incorrect `from()` property key: + ```json + { "query": "from(foo: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")" + } + ``` + Passing this to `/api/v2/query/ast` will return a successful response + with a generated AST. operationId: PostQueryAst parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11117,23 +11422,410 @@ paths: application/json: schema: $ref: '#/components/schemas/LanguageRequest' - description: Analyzed Flux query to generate abstract syntax tree. + description: The Flux query to analyze. responses: '200': content: application/json: + examples: + successResponse: + value: + ast: + files: + - body: + - expression: + argument: + argument: + arguments: + - location: + end: + column: 25 + line: 1 + source: 'bucket: "example-bucket"' + start: + column: 6 + line: 1 + properties: + - key: + location: + end: + column: 12 + line: 1 + source: bucket + start: + column: 6 + line: 1 + name: bucket + type: Identifier + location: + end: + column: 25 + line: 1 + source: 'bucket: "example-bucket"' + start: + column: 6 + line: 1 + type: Property + value: + location: + end: + column: 25 + line: 1 + source: '"example-bucket"' + start: + column: 14 + line: 1 + type: StringLiteral + value: example-bucket + type: ObjectExpression + callee: + location: + end: + column: 5 + line: 1 + source: from + start: + column: 1 + line: 1 + name: from + type: Identifier + location: + end: + column: 26 + line: 1 + source: 'from(bucket: "example-bucket")' + start: + column: 1 + line: 1 + type: CallExpression + call: + arguments: + - location: + end: + column: 46 + line: 1 + source: 'start: -5m' + start: + column: 36 + line: 1 + properties: + - key: + location: + end: + column: 41 + line: 1 + source: start + start: + column: 36 + line: 1 + name: start + type: Identifier + location: + end: + column: 46 + line: 1 + source: 'start: -5m' + start: + column: 36 + line: 1 + type: Property + value: + argument: + location: + end: + column: 46 + line: 1 + source: 5m + start: + column: 44 + line: 1 + type: DurationLiteral + values: + - magnitude: 5 + unit: m + location: + end: + column: 46 + line: 1 + source: '-5m' + start: + column: 43 + line: 1 + operator: '-' + type: UnaryExpression + type: ObjectExpression + callee: + location: + end: + column: 35 + line: 1 + source: range + start: + column: 30 + line: 1 + name: range + type: Identifier + location: + end: + column: 47 + line: 1 + source: 'range(start: -5m)' + start: + column: 30 + line: 1 + type: CallExpression + location: + end: + column: 47 + line: 1 + source: >- + from(bucket: "example-bucket") |> + range(start: -5m) + start: + column: 1 + line: 1 + type: PipeExpression + call: + arguments: + - location: + end: + column: 108 + line: 1 + source: >- + fn: (r) => r._measurement == + "example-measurement" + start: + column: 58 + line: 1 + properties: + - key: + location: + end: + column: 60 + line: 1 + source: fn + start: + column: 58 + line: 1 + name: fn + type: Identifier + location: + end: + column: 108 + line: 1 + source: >- + fn: (r) => r._measurement == + "example-measurement" + start: + column: 58 + line: 1 + type: Property + value: + body: + left: + location: + end: + column: 83 + line: 1 + source: r._measurement + start: + column: 69 + line: 1 + object: + location: + end: + column: 70 + line: 1 + source: r + start: + column: 69 + line: 1 + name: r + type: Identifier + property: + location: + end: + column: 83 + line: 1 + source: _measurement + start: + column: 71 + line: 1 + name: _measurement + type: Identifier + type: MemberExpression + location: + end: + column: 108 + line: 1 + source: r._measurement == "example-measurement" + start: + column: 69 + line: 1 + operator: '==' + right: + location: + end: + column: 108 + line: 1 + source: '"example-measurement"' + start: + column: 87 + line: 1 + type: StringLiteral + value: example-measurement + type: BinaryExpression + location: + end: + column: 108 + line: 1 + source: >- + (r) => r._measurement == + "example-measurement" + start: + column: 62 + line: 1 + params: + - key: + location: + end: + column: 64 + line: 1 + source: r + start: + column: 63 + line: 1 + name: r + type: Identifier + location: + end: + column: 64 + line: 1 + source: r + start: + column: 63 + line: 1 + type: Property + value: null + type: FunctionExpression + type: ObjectExpression + callee: + location: + end: + column: 57 + line: 1 + source: filter + start: + column: 51 + line: 1 + name: filter + type: Identifier + location: + end: + column: 109 + line: 1 + source: >- + filter(fn: (r) => r._measurement == + "example-measurement") + start: + column: 51 + line: 1 + type: CallExpression + location: + end: + column: 109 + line: 1 + source: >- + from(bucket: "example-bucket") |> + range(start: -5m) |> filter(fn: (r) => + r._measurement == "example-measurement") + start: + column: 1 + line: 1 + type: PipeExpression + location: + end: + column: 109 + line: 1 + source: >- + from(bucket: "example-bucket") |> range(start: + -5m) |> filter(fn: (r) => r._measurement == + "example-measurement") + start: + column: 1 + line: 1 + type: ExpressionStatement + imports: null + location: + end: + column: 109 + line: 1 + source: >- + from(bucket: "example-bucket") |> range(start: + -5m) |> filter(fn: (r) => r._measurement == + "example-measurement") + start: + column: 1 + line: 1 + metadata: parser-type=rust + package: null + type: File + package: main + type: Package schema: $ref: '#/components/schemas/ASTResponse' - description: Abstract syntax tree of the flux query. + description: > + Success. + + The response body contains an Abstract Syntax Tree (AST) of the Flux + query. + '400': + content: + application/json: + examples: + invalidASTValue: + description: > + If the request body contains a missing property key in + `from()`, + + returns `invalid` and problem detail. + summary: Invalid AST + value: + code: invalid + message: 'invalid AST: loc 1:6-1:19: missing property key' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the problem. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: invalid + type: string default: content: application/json: schema: $ref: '#/components/schemas/Error' - description: Any response other than 200 is an internal server error - summary: Generate an Abstract Syntax Tree (AST) from a query + description: Internal server error. + summary: Generate a query Abstract Syntax Tree (AST) tags: - Query + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST 'INFLUX_URL/api/v2/query/ast' \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json \ + --header 'Authorization: Token INFLUX_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' /api/v2/query/suggestions: get: operationId: GetQuerySuggestions @@ -11201,6 +11893,7 @@ paths: summary: Get the readiness of an instance at startup tags: - Ready + - System information endpoints /api/v2/remotes: get: operationId: GetRemoteConnections @@ -11526,6 +12219,7 @@ paths: summary: List all known resources tags: - Resources + - System information endpoints /api/v2/restore/bucket/{bucketID}: post: deprecated: true @@ -12715,35 +13409,57 @@ paths: - Templates /api/v2/tasks: get: + description: > + Retrieves a list of [tasks](/influxdb/v2.3/process-data/). + + + 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`. operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - - description: Returns task with a specific name. + - description: | + Task name. + Only returns tasks with this name. + Different tasks may have the same name. in: query name: name schema: type: string - - description: Return tasks after a specified ID. + - description: | + Task ID. + Only returns tasks created after this task. in: query name: after schema: type: string - - description: Filter tasks to a specific user ID. + - description: | + User ID. + Only returns tasks owned by this user. in: query name: user schema: type: string - - description: Filter tasks to a specific organization name. + - description: | + Organization name. + Only returns tasks owned by this organization. in: query name: org schema: type: string - - description: Filter tasks to a specific organization ID. + - description: | + Organization ID. + Only returns tasks owned by this organization. in: query name: orgID schema: type: string - - description: Filter tasks by a status--"inactive" or "active". + - description: | + Task status (`active` or `inactive`). + Only returns tasks with this status. in: query name: status schema: @@ -12751,7 +13467,9 @@ paths: - active - inactive type: string - - description: The number of tasks to return + - description: | + Limits the number of tasks returned. + The minimum is `1`, the maximum is `500`, and the default is `100`. in: query name: limit schema: @@ -12759,7 +13477,15 @@ paths: maximum: 500 minimum: 1 type: integer - - description: Type of task, unset by default. + - description: > + Task type (`basic` or `system`). + + + The default (`system`) response contains all the metadata properties + for tasks. + + To reduce the payload size, pass `basic` to omit some task + properties (`flux`, `createdAt`, `updatedAt`) from the response. in: query name: type required: false @@ -12773,19 +13499,97 @@ paths: '200': content: application/json: + examples: + basicTypeTaskOutput: + description: Task fields returned with `?type=basic` + summary: Basic output + value: + links: + self: /api/v2/tasks?limit=100 + tasks: + - every: 30m + flux: '' + id: 09956cbb6d378000 + labels: [] + lastRunStatus: success + latestCompleted: '2022-06-30T15:00:00Z' + links: + labels: /api/v2/tasks/09956cbb6d378000/labels + logs: /api/v2/tasks/09956cbb6d378000/logs + members: /api/v2/tasks/09956cbb6d378000/members + owners: /api/v2/tasks/09956cbb6d378000/owners + runs: /api/v2/tasks/09956cbb6d378000/runs + self: /api/v2/tasks/09956cbb6d378000 + name: task1 + org: '' + orgID: 48c88459ee424a04 + ownerID: 0772396d1f411000 + status: active + systemTypeTaskOutput: + description: Task fields returned with `?type=system` + summary: System output + value: + links: + self: /api/v2/tasks?limit=100 + tasks: + - createdAt: '2022-06-27T15:09:06Z' + description: IoT Center 90-day environment average. + every: 30m + flux: |- + option task = {name: "task1", every: 30m} + + from(bucket: "iot_center") + |> range(start: -90d) + |> filter(fn: (r) => r._measurement == "environment") + |> aggregateWindow(every: 1h, fn: mean) + id: 09956cbb6d378000 + labels: [] + lastRunStatus: success + latestCompleted: '2022-06-30T15:00:00Z' + links: + labels: /api/v2/tasks/09956cbb6d378000/labels + logs: /api/v2/tasks/09956cbb6d378000/logs + members: /api/v2/tasks/09956cbb6d378000/members + owners: /api/v2/tasks/09956cbb6d378000/owners + runs: /api/v2/tasks/09956cbb6d378000/runs + self: /api/v2/tasks/09956cbb6d378000 + name: task1 + org: my-iot-center + orgID: 48c88459ee424a04 + ownerID: 0772396d1f411000 + status: active + updatedAt: '2022-06-28T18:10:15Z' schema: $ref: '#/components/schemas/Tasks' - description: A list of tasks + description: | + Success. + The response body contains the list of tasks. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all tasks + $ref: '#/components/responses/GeneralServerError' + summary: List tasks tags: + - Data I/O endpoints - Tasks post: + description: > + Creates a [task](/influxdb/v2.3/process-data/) and returns the created + task. + + + #### Related guides + + + - [Create a + task](/influxdb/v2.3/process-data/manage-tasks/create-task/). + + - [Common tasks](/influxdb/v2.3/process-data/common-tasks/) + + - [Task configuration + options](/influxdb/v2.3/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12794,7 +13598,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskCreateRequest' - description: Task to create + description: The task to create. required: true responses: '201': @@ -12802,19 +13606,69 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: Task created + description: >- + Success. The response body contains a `tasks` list with the new + task. + '400': + content: + application/json: + examples: + missingFluxError: + summary: Task in request body is missing Flux query + value: + code: invalid + message: 'failed to decode request: missing flux' + schema: + $ref: '#/components/responses/BadRequestError' + description: Bad request + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error - summary: Create a new task + summary: Create a task tags: + - Data I/O endpoints - Tasks + x-codeSamples: + - label: 'cURL: create a task' + lang: Shell + source: | + curl -v --request POST \ + http://localhost:8086/api/v2/tasks \ + --header "Content-type: application/json" \ + --header "Authorization: Token INFLUX_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 a task and all associated records + description: > + 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. + + + 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' @@ -12826,17 +13680,24 @@ paths: type: string responses: '204': - description: Task deleted + description: Success. Task and runs are deleted. Scheduled runs are canceled. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Delete a task tags: - Tasks get: + description: | + Retrieves a [task](/influxdb/v2.3/reference/glossary/#task) + by task ID. operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12852,18 +13713,40 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: Task details + description: Success. The response body contains the task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve a task tags: + - Data I/O endpoints - Tasks patch: - description: Update a task. This will cancel all queued runs. + description: > + Updates a task and then cancels all scheduled runs of the task. + + + Use this endpoint to modify task properties (for example: `cron`, + `name`, `flux`, `status`). + + Once InfluxDB applies the update, it cancels all scheduled runs of the + task. + + + To update a task, pass an object that contains the updated key-value + pairs. + + To activate or inactivate a task, set the `status` property. + + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs + of the task. operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12878,7 +13761,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: Task update to apply + description: An object that contains updated task properties to apply. required: true responses: '200': @@ -12886,22 +13769,30 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: Task updated + description: Success. The response body contains the updated task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Update a task tags: - Tasks /api/v2/tasks/{taskID}/labels: get: + description: | + Retrieves a list of all labels for a task. + + Labels may be used for grouping and filtering tasks. operationId: GetTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: The ID of the task to retrieve labels for. in: path name: taskID required: true @@ -12913,21 +13804,33 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a task + description: >- + Success. The response body contains a list of all labels for the + task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a task + $ref: '#/components/responses/GeneralServerError' + summary: List labels for a task tags: - Tasks post: + description: > + Adds a label to a task. + + + Use this endpoint to add a label that you can use to filter tasks in the + InfluxDB UI. operationId: PostTasksIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: The ID of the task to label. in: path name: taskID required: true @@ -12938,7 +13841,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelMapping' - description: Label to add + description: An object that contains a _`labelID`_ to add to the task. required: true responses: '201': @@ -12946,28 +13849,36 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: A list of all labels for a task + description: >- + Success. The response body contains a list of all labels for the + task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Add a label to a task tags: - Tasks /api/v2/tasks/{taskID}/labels/{labelID}: delete: + description: | + Deletes a label from a task. operationId: DeleteTasksIDLabelsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The task ID. + - description: The ID of the task to delete the label from. in: path name: taskID required: true schema: type: string - - description: The label ID. + - description: The ID of the label to delete. in: path name: labelID required: true @@ -12975,24 +13886,37 @@ paths: type: string responses: '204': - description: Delete has been accepted + description: Success. The label is deleted. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Task not found + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Delete a label from a task tags: - Tasks /api/v2/tasks/{taskID}/logs: get: + description: > + Retrieves a list of all logs for a + [task](/influxdb/v2.3/reference/glossary/#task). + + + When an InfluxDB task runs, a “run” record is created in the task’s + history. + + Logs associated with each run provide relevant log messages, timestamps, + and the exit status of the run attempt. + + + Use this endpoint to retrieve only the log events for a task, + + without additional task metadata. operationId: GetTasksIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13006,15 +13930,62 @@ paths: '200': content: application/json: + examples: + taskFailure: + summary: Events for a failed task. + value: + events: + - message: >- + Started task from script: "option task = {name: \"test + task\", every: 3d, offset: 0s}" + runID: 09a946fc3167d000 + time: '2022-07-13T07:06:54.198167Z' + - message: Completed(failed) + runID: 09a946fc3167d000 + time: '2022-07-13T07:07:13.104037Z' + - message: >- + error exhausting result iterator: error in query + specification while starting program: this Flux script + returns no streaming data. Consider adding a "yield" + or invoking streaming functions directly, without + performing an assignment + runID: 09a946fc3167d000 + time: '2022-07-13T08:24:37.115323Z' + taskSuccess: + summary: Events for successful task. + value: + events: + - message: >- + Started task from script: "option task = {name: + \"task1\", every: 30m} from(bucket: \"iot_center\") |> + range(start: -90d) |> filter(fn: (r) => r._measurement + == \"environment\") |> aggregateWindow(every: 1h, fn: + mean)" + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' schema: $ref: '#/components/schemas/Logs' - description: All logs for a task + 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. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error + $ref: '#/components/responses/GeneralServerError' summary: Retrieve all logs for a task tags: - Tasks @@ -13277,9 +14248,18 @@ paths: description: Unexpected error summary: Manually start a task run, overriding the current schedule tags: + - Data I/O endpoints - Tasks /api/v2/tasks/{taskID}/runs/{runID}: delete: + description: | + Cancels a running [task](/influxdb/v2.3/reference/glossary/#task). + + Use this endpoint with InfluxDB OSS to cancel a running task. + + #### InfluxDB Cloud + + - Doesn't support this operation. operationId: DeleteTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13289,7 +14269,7 @@ paths: required: true schema: type: string - - description: The run ID. + - description: The ID of the task run to cancel. in: path name: runID required: true @@ -13297,7 +14277,18 @@ paths: type: string responses: '204': - description: Delete has been accepted. + description: | + Success. The `DELETE` is accepted and the run will be cancelled. + + #### InfluxDB Cloud + + - Doesn't support this operation. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' '405': content: application/json: @@ -13308,26 +14299,25 @@ paths: #### InfluxDB Cloud - - Cancelling task runs is not supported in InfluxDB Cloud. + - Always returns this error; cancelling a task run is not supported. #### InfluxDB OSS - Doesn't return this error. + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: | - Cancel a running task. - - #### InfluxDB Cloud - - - Doesn't support this operation. + $ref: '#/components/responses/GeneralServerError' + summary: Cancel a running task tags: - Tasks get: + description: > + Retrieves a specific run for a + [task](/influxdb/v2.3/reference/glossary/#task). + + + Use this endpoint to retrieve detail and logs for a specific task run. operationId: GetTasksIDRunsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13347,16 +14337,50 @@ paths: '200': content: application/json: + examples: + runSuccess: + summary: A successful task run. + value: + finishedAt: '2022-07-18T14:46:07.308254Z' + id: 09b070dadaa7d000 + links: + logs: >- + /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs + retry: >- + /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry + self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 + task: /api/v2/tasks/0996e56b2f378000 + log: + - message: >- + Started task from script: "option task = {name: + \"task1\", every: 30m} from(bucket: \"iot_center\") |> + range(start: -90d) |> filter(fn: (r) => r._measurement + == \"environment\") |> + aggregateWindow(every: 1h, fn: mean)" + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' + requestedAt: '2022-07-18T14:46:06Z' + scheduledFor: '2022-07-18T14:46:06Z' + startedAt: '2022-07-18T14:46:07.16222Z' + status: success + taskID: 0996e56b2f378000 schema: $ref: '#/components/schemas/Run' - description: Returns the run record. + description: Success. The response body contains the task run. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Retrieve a single run for a task. + $ref: '#/components/responses/GeneralServerError' + summary: Retrieve a run for a task. tags: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/logs: @@ -14011,6 +15035,7 @@ paths: description: Unexpected error summary: List all users tags: + - Security and access endpoints - Users post: operationId: PostUsers @@ -14078,6 +15103,7 @@ paths: description: Unexpected error summary: Retrieve a user tags: + - Security and access endpoints - Users patch: operationId: PatchUsersID @@ -14111,6 +15137,11 @@ paths: - Users /api/v2/users/{userID}/password: post: + description: | + #### InfluxDB Cloud + + InfluxDB Cloud does not support changing user passwords through the API. + Use the InfluxDB Cloud user interface to update your password. operationId: PostUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' @@ -14130,6 +15161,12 @@ paths: responses: '204': description: Password successfully updated + '400': + description: > + Bad request. + + InfluxDB Cloud doesn't support changing passwords through the API + and always responds with this status. default: content: application/json: @@ -14140,6 +15177,7 @@ paths: - BasicAuthentication: [] summary: Update a password tags: + - Security and access endpoints - Users /api/v2/variables: get: @@ -14660,8 +15698,8 @@ paths: examples: measurementSchemaFieldTypeConflict: summary: >- - InfluxDB Cloud field type conflict thrown by an explicit - bucket schema + (Cloud) field type conflict thrown by an explicit bucket + schema value: code: invalid message: >- @@ -14670,13 +15708,36 @@ paths: temperature="90.5",humidity=70.0 1632850122': schema: field type for field "temperature" not permitted by schema; got String but expected Float + orgNotFound: + summary: (OSS) organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/LineProtocolError' - description: | - Bad request. - The line protocol data in the request is malformed. + description: > + Bad request. The response body contains detail about the error. + + + InfluxDB returns this error if the line protocol data in the request + is malformed. + The response body contains the first malformed line in the data. + InfluxDB rejected the batch and did not write any data. + + + #### InfluxDB Cloud + + + - Returns this error for bucket schema conflicts. + + + #### InfluxDB OSS + + + - Returns this error if `org` or `orgID` does not match an + organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -14726,11 +15787,13 @@ paths: #### InfluxDB Cloud - - Returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](/influxdb/cloud/account-management/limits/#global-limits). - - Returns `Retry-After` header that describes when to try the write again. + - Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits). + - For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. + - For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header. + + Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. + Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. #### InfluxDB OSS @@ -14746,20 +15809,14 @@ paths: '500': $ref: '#/components/responses/InternalServerError' '503': - description: | + description: > Service unavailable. - #### InfluxDB Cloud - - Returns this error if series cardinality exceeds your plan's - [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas). - See [how to resolve high series cardinality](/influxdb/v2.3/write-data/best-practices/resolve-high-cardinality/). - - #### InfluxDB OSS - - - Returns this error if - the server is temporarily unavailable to accept writes. - - Returns `Retry-After` header that describes when to try the write again. + - Returns this error if + the server is temporarily unavailable to accept writes. + - Returns a `Retry-After` header that describes when to try the + write again. headers: Retry-After: description: >- @@ -14772,6 +15829,7 @@ paths: $ref: '#/components/responses/GeneralServerError' summary: Write data tags: + - Data I/O endpoints - Write /legacy/authorizations: get: @@ -15322,9 +16380,10 @@ tags: x-traitTag: true - name: Config - name: Dashboards + - name: Data I/O endpoints - name: DBRPs - description: > - Generates profiling and trace reports. + Generate profiling and trace reports. Use routes under `/debug/pprof` to analyze the Go runtime of InfluxDB. @@ -15345,7 +16404,9 @@ tags: - [Google pprof tool](https://github.com/google/pprof) - [Golang diagnostics](https://go.dev/doc/diagnostics) name: Debug - - name: Delete + - description: | + Delete data from an InfluxDB bucket. + name: Delete - description: > InfluxDB API endpoints use standard HTTP request and response headers. @@ -15441,8 +16502,8 @@ tags: following:
  • `Authorization: Token` header is missing or malformed
  • API token value is missing from the header
  • API token does not have permission. For more information about token types and - permissions, see [Manage API tokens](/influxdb/v2.1/security/tokens/)
    • - | + permissions, see [Manage API + tokens](/influxdb/latest/security/tokens/) | | `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested @@ -15470,11 +16531,29 @@ tags: - name: Rules - name: Scraper Targets - name: Secrets + - name: Security and access endpoints - name: Setup - name: Signin - name: Signout - name: Sources - - name: Tasks + - name: System information endpoints + - description: > + Process and analyze your data with tasks in the InfluxDB task engine. + + With tasks, you can schedule Flux scripts to query, analyze, modify, and + act on data. + + + Use the `/api/v2/tasks` endpoints to create and manage tasks, retry task + runs, and retrieve run logs. + + + #### Related guides + + + - [Common data processing + tasks](/influxdb/v2.3/process-data/common-tasks/) + name: Tasks - name: Telegraf Plugins - name: Telegrafs - name: Templates @@ -15491,32 +16570,11 @@ x-tagGroups: - Authentication - Headers - Response codes - - name: Data I/O endpoints + - name: '' tags: - - Write - - Query - - Delete - - Tasks - - name: Resource endpoints - tags: - - Buckets - - Dashboards - - Tasks - - Resources - - name: Security and access endpoints - tags: - - Authorizations - - Organizations - - Users - - name: System information endpoints - tags: - - Config - - Debug - - Health - - Metrics - - Ping - - Ready - - Routes + - Data I/O endpoints + - Security and access endpoints + - System information endpoints - name: All endpoints tags: - Authorizations diff --git a/api-docs/v2.3/swaggerV1Compat.yml b/api-docs/v2.3/swaggerV1Compat.yml index f75339d46..34926f5ea 100644 --- a/api-docs/v2.3/swaggerV1Compat.yml +++ b/api-docs/v2.3/swaggerV1Compat.yml @@ -509,15 +509,4 @@ tags: x-traitTag: true - name: Query - name: Write -x-tagGroups: - - name: Overview - tags: - - Authentication - - name: Data I/O endpoints - tags: - - Write - - Query - - name: All endpoints - tags: - - Query - - Write +x-tagGroups: []