From eeaab0f240011ed68b5092b1a2415089cdd1b60a Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 21 Sep 2022 09:22:49 -0500 Subject: [PATCH] chore(api): Updates API specs for users and auths. Fixes whitespace, punctuation, grammar, links, and other style issues. (#4469) --- api-docs/cloud/ref.yml | 3977 +++++++++++----------------- api-docs/cloud/swaggerV1Compat.yml | 163 +- api-docs/v2.4/ref.yml | 3758 +++++++++----------------- api-docs/v2.4/swaggerV1Compat.yml | 163 +- 4 files changed, 2929 insertions(+), 5132 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index d43efda90..f5fefc0ce 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -1,9 +1,8 @@ components: parameters: After: - description: > - Resource ID to seek from. Results are not inclusive of this ID. Use - `after` instead of `offset`. + description: | + Resource ID to seek from. Results are not inclusive of this ID. Use `after` instead of `offset`. in: query name: after required: false @@ -75,9 +74,7 @@ components: readOnly: true type: string message: - description: >- - A human-readable message that may contain detail about the - error. + description: A human-readable message that may contain detail about the error. readOnly: true type: string description: | @@ -91,25 +88,19 @@ components: application/json: examples: orgProvidedNotFound: - summary: >- - The org or orgID passed doesn't own the token passed in the - header + summary: The org or orgID passed doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/Error' - description: > + description: | Bad request. - The response body contains detail about the error. - #### InfluxDB OSS - - - Returns this error if an incorrect value is passed for `org` or - `orgID`. + - Returns this error if an incorrect value is passed for `org` or `orgID`. GeneralServerError: content: application/json: @@ -145,21 +136,14 @@ components: message: organization not found schema: $ref: '#/components/schemas/Error' - description: > + description: | Not found. - A requested resource was not found. - - The response body contains the requested resource type and the name - value - + The response body contains the requested resource type and the name value (if you passed it)--for example: - - `"organization name \"my-org\" not found"` - - - `"organization not found"`: indicates you passed an ID that did not - match + - `"organization not found"`: indicates you passed an ID that did not match an organization. ServerError: content: @@ -223,6 +207,7 @@ components: readOnly: true type: string id: + description: The authorization ID. readOnly: true type: string links: @@ -239,15 +224,19 @@ components: readOnly: true type: object org: - description: The name of the organization that owns the token. + description: | + The organization name. + Specifies the [organization](/influxdb/cloud/reference/glossary/#organization) that the token is scoped to. readOnly: true type: string orgID: - description: The ID of the organization. + description: | + The organization ID. + Specifies the [organization](/influxdb/cloud/reference/glossary/#organization) that the authorization is scoped to. type: string permissions: description: | - A list of permissions for an authorization. + The list of permissions. An authorization must have at least one permission. items: $ref: '#/components/schemas/Permission' @@ -255,7 +244,11 @@ components: type: array token: description: | - The API token for authenticating InfluxDB API and CLI requests. + The API token. + [Tokens](/influxdb/cloud/reference/glossary/#token) are + used to authenticate InfluxDB API requests and `influx` CLI commands. + If authenticated, the token is allowed the permissions of the _authorization_. + The token value is unique to the authorization. readOnly: true type: string updatedAt: @@ -263,11 +256,15 @@ components: readOnly: true type: string user: - description: The name of the user that the token is scoped to. + description: | + The user name. + Specifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the authorization. + If the authorization is _scoped_ to a user, the user; + otherwise, the creator of the authorization. readOnly: true type: string userID: - description: The ID of the user that the token is scoped to. + description: The user ID. Specifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization. readOnly: true type: string type: object @@ -281,9 +278,7 @@ components: type: string status: default: active - description: >- - Status of the token. If `inactive`, requests using the token will be - rejected. + description: Status of the token. If `inactive`, requests using the token will be rejected. enum: - active - inactive @@ -320,9 +315,7 @@ components: - '10' type: string bounds: - description: >- - The extents of the axis in the form [lower, upper]. Clients - determine whether bounds are inclusive or exclusive of their limits. + description: The extents of the axis in the form [lower, upper]. Clients determine whether bounds are inclusive or exclusive of their limits. items: type: string maxItems: 2 @@ -347,9 +340,7 @@ components: - linear type: string BadStatement: - description: >- - A placeholder for statements for which no correct statement nodes can be - created + description: A placeholder for statements for which no correct statement nodes can be created properties: text: description: Raw source text @@ -711,10 +702,7 @@ components: readOnly: true type: string latestCompleted: - description: >- - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) - of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -851,10 +839,7 @@ components: ColorMapping: additionalProperties: type: string - description: >- - A color mapping is an object that maps time series data to a UI color - scheme to allow the UI to render graphs consistent colors across - reloads. + description: A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. example: configcat_deployments-autopromotionblocker: '#663cd0' measurement_birdmigration_europe: '#663cd0' @@ -877,9 +862,7 @@ components: nullable: false type: string ConditionalExpression: - description: >- - Selects one of two expressions, `Alternate` or `Consequent`, depending - on a third boolean expression, `Test` + description: Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test` properties: alternate: $ref: '#/components/schemas/Expression' @@ -954,9 +937,7 @@ components: description: InfluxDB v1 database type: string default: - description: >- - Mapping represents the default retention policy for the database - specified. + description: Mapping represents the default retention policy for the database specified. type: boolean id: description: The ID of the DBRP mapping. @@ -971,9 +952,7 @@ components: description: InfluxDB v1 retention policy type: string virtual: - description: >- - Indicates an autogenerated, virtual mapping based on the bucket - name. Currently only available in OSS. + description: Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. type: boolean required: - id @@ -992,9 +971,7 @@ components: description: InfluxDB v1 database type: string default: - description: >- - Mapping represents the default retention policy for the database - specified. + description: Mapping represents the default retention policy for the database specified. type: boolean org: description: The name of the organization that owns this mapping. @@ -1174,10 +1151,7 @@ components: $ref: '#/components/schemas/Links' type: object DateTimeLiteral: - description: >- - Represents an instant in time with nanosecond precision in [RFC3339Nano - date/time - format](/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp). + description: Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp). properties: type: $ref: '#/components/schemas/NodeType' @@ -1201,9 +1175,7 @@ components: description: If only zero values reported since time, trigger an alert type: boolean staleTime: - description: >- - String duration for time that a series is considered stale and - should not trigger deadman. + description: String duration for time that a series is considered stale and should not trigger deadman. type: string statusMessageTemplate: description: The template used to generate and write a status message. @@ -1229,9 +1201,7 @@ components: - type type: object DecimalPlaces: - description: >- - Indicates whether decimal places should be enforced, and how many digits - it should show. + description: Indicates whether decimal places should be enforced, and how many digits it should show. properties: digits: description: The number of digits after decimal to display @@ -1245,24 +1215,19 @@ components: description: The delete predicate request. properties: predicate: - description: > - An expression in [delete predicate - syntax](https://docs.influxdata.com/influxdb/cloud/reference/syntax/delete-predicate/). + description: | + An expression in [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: - description: > - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - + description: | + A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. format: date-time type: string stop: - description: > - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - + description: | + A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. format: date-time type: string @@ -1271,39 +1236,24 @@ components: - stop type: object Dialect: - description: > + description: | Options for tabular data output. - - Default output is [annotated - CSV](/influxdb/cloud/reference/syntax/annotated-csv/#csv-response-format) - with headers. - + Default output is [annotated CSV](/influxdb/cloud/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, - - see [W3 metadata vocabulary for tabular - data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). properties: annotations: - description: > + description: | Annotation rows to include in the results. - - An _annotation_ is metadata associated with an object (column) in - the data model. - + An _annotation_ is metadata associated with an object (column) in the data model. #### Related guides - - - See [Annotated CSV - annotations](https://docs.influxdata.com/influxdb/cloud/reference/syntax/annotated-csv/#annotations) - for examples and more information. - + - See [Annotated CSV annotations](/influxdb/cloud/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, - - see [W3 metadata vocabulary for tabular - data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). items: enum: - group @@ -1314,32 +1264,22 @@ components: uniqueItems: true commentPrefix: default: '#' - description: >- - The character prefixed to comment strings. Default is a number sign - (`#`). + description: The character prefixed to comment strings. Default is a number sign (`#`). maxLength: 1 minLength: 0 type: string dateTimeFormat: default: RFC3339 - description: > + description: | The format for timestamps in results. - - Default is [`RFC3339` date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp). - + Default is [`RFC3339` date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values - | Format | Value | - |:------------|:----------------------------| - | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | - | `RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | enum: - RFC3339 @@ -1378,9 +1318,7 @@ components: $ref: '#/components/schemas/Expression' type: object Duration: - description: >- - A pair consisting of length of time and the unit of time measured. It is - the atomic unit from which all duration literals are composed. + description: A pair consisting of length of time and the unit of time measured. It is the atomic unit from which all duration literals are composed. properties: magnitude: type: integer @@ -1390,9 +1328,7 @@ components: type: string type: object DurationLiteral: - description: >- - Represents the elapsed time between two instants as an int64 nanosecond - count with syntax of golang's time.Duration + description: Represents the elapsed time between two instants as an int64 nanosecond count with syntax of golang's time.Duration properties: type: $ref: '#/components/schemas/NodeType' @@ -1424,9 +1360,7 @@ components: readOnly: true type: string err: - description: >- - Stack of errors that occurred during processing of the request. - Useful for debugging. + description: Stack of errors that occurred during processing of the request. Useful for debugging. readOnly: true type: string message: @@ -1434,9 +1368,7 @@ components: readOnly: true type: string op: - description: >- - Describes the logical code operation when the error occurred. Useful - for debugging. + description: Describes the logical code operation when the error occurred. Useful for debugging. readOnly: true type: string required: @@ -1485,9 +1417,7 @@ components: - $ref: '#/components/schemas/UnsignedIntegerLiteral' - $ref: '#/components/schemas/Identifier' ExpressionStatement: - description: >- - May consist of an expression that doesn't return a value and is executed - solely for its side-effects + description: May consist of an expression that doesn't return a value and is executed solely for its side-effects properties: expression: $ref: '#/components/schemas/Expression' @@ -1497,9 +1427,7 @@ components: Field: properties: alias: - description: >- - Alias overrides the field name in the returned response. Applies - only if type is `func` + description: Alias overrides the field name in the returned response. Applies only if type is `func` type: string args: description: Args are the arguments to the function @@ -1507,9 +1435,7 @@ components: $ref: '#/components/schemas/Field' type: array type: - description: >- - `type` describes the field type. `func` is a function. `field` is a - field reference. + description: '`type` describes the field type. `func` is a function. `field` is a field reference.' enum: - func - field @@ -1519,9 +1445,7 @@ components: - wildcard type: string value: - description: >- - value is the value of the field. Meaning of the value is implied by - the `type` key + description: value is the value of the field. Meaning of the value is implied by the `type` key type: string type: object File: @@ -1549,9 +1473,7 @@ components: additionalProperties: true type: object FloatLiteral: - description: >- - Represents floating point numbers according to the double - representations defined by the IEEE-754-1985 + description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 properties: type: $ref: '#/components/schemas/NodeType' @@ -1796,9 +1718,7 @@ components: type: array detectCoordinateFields: default: true - description: >- - If true, search results get automatically regroupped so that lon,lat - and value are treated as columns + description: If true, search results get automatically regroupped so that lon,lat and value are treated as columns type: boolean latLonColumns: $ref: '#/components/schemas/LatLonColumns' @@ -2146,11 +2066,8 @@ components: type: object InfluxqlCsvResponse: description: CSV Response to InfluxQL Query - example: > - name,tags,time,test_field,test_tag - test_measurement,,1603740794286107366,1,tag_value - test_measurement,,1603740870053205649,2,tag_value - test_measurement,,1603741221085428881,3,tag_value + example: | + name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value type: string InfluxqlJsonResponse: description: JSON Response to InfluxQL Query @@ -2216,11 +2133,9 @@ components: properties: additionalProperties: type: string - description: > + description: | Key-value pairs associated with this label. - - To remove a property, send an update with an empty value (`""`) for - the key. + To remove a property, send an update with an empty value (`""`) for the key. example: color: ffb3b3 description: this is a description @@ -2235,12 +2150,10 @@ components: properties: additionalProperties: type: string - description: > + description: | Key-value pairs associated with this label. - - To remove a property, send an update with an empty value (`""`) for - the key. + To remove a property, send an update with an empty value (`""`) for the key. example: color: ffb3b3 description: this is a description @@ -2270,12 +2183,10 @@ components: type: string properties: additionalProperties: - description: > + description: | Key-value pairs associated with this label. - - To remove a property, send an update with an empty value (`""`) - for the key. + To remove a property, send an update with an empty value (`""`) for the key. type: string example: color: ffb3b3 @@ -2335,10 +2246,8 @@ components: description: The ID of the organization that the authorization is scoped to. type: string permissions: - description: > - A list of permissions that provide `read` and `write` access to - organization resources. - + description: | + A list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' @@ -2592,9 +2501,7 @@ components: readOnly: true type: string err: - description: >- - Stack of errors that occurred during processing of the request. - Useful for debugging. + description: Stack of errors that occurred during processing of the request. Useful for debugging. readOnly: true type: string line: @@ -2607,9 +2514,7 @@ components: readOnly: true type: string op: - description: >- - Describes the logical code operation when the error occurred. Useful - for debugging. + description: Describes the logical code operation when the error occurred. Useful for debugging. readOnly: true type: string required: @@ -2659,19 +2564,14 @@ components: readOnly: true type: string time: - description: >- - The time ([RFC3339Nano date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp)) - that the event occurred. + description: The time ([RFC3339Nano date/time format](/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true type: string type: object LogicalExpression: - description: >- - Represents the rule conditions that collectively evaluate to either true - or false + description: Represents the rule conditions that collectively evaluate to either true or false properties: left: $ref: '#/components/schemas/Expression' @@ -3147,22 +3047,15 @@ components: readOnly: true type: string latestCompleted: - description: >- - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) - of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string limit: - description: >- - Don't notify me more than times every seconds. - If set, limitEvery cannot be empty. + description: Don't notify me more than times every seconds. If set, limitEvery cannot be empty. type: integer limitEvery: - description: >- - Don't notify me more than times every seconds. - If set, limit cannot be empty. + description: Don't notify me more than times every seconds. If set, limit cannot be empty. type: integer links: example: @@ -3494,31 +3387,21 @@ components: minimum: 0 type: integer shardGroupDurationSeconds: - description: > - The [shard group - duration](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#shard). - + description: | + The [shard group duration](/influxdb/cloud/reference/glossary/#shard). The number of seconds that each shard group covers. - #### InfluxDB Cloud - - Doesn't use `shardGroupDurationsSeconds`. - #### InfluxDB OSS - - - Default value depends on the [bucket retention - period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration). - + - Default value depends on the [bucket retention period](/influxdb/cloud/reference/internals/shards/#shard-group-duration). #### Related guides - - - InfluxDB [shards and shard - groups](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/) + - InfluxDB [shards and shard groups](/influxdb/cloud/reference/internals/shards/) format: int64 type: integer type: @@ -3545,11 +3428,9 @@ components: $ref: '#/components/schemas/Resource' properties: id: - description: > + description: | The ID of a specific resource. - - In a `permission`, applies the permission to only the resource - with this ID. + In a `permission`, applies the permission to only the resource with this ID. type: string name: description: | @@ -3561,18 +3442,14 @@ components: Optional: The name of the organization with `orgID`. type: string orgID: - description: > + description: | The ID of the organization that owns the resource. - - In a `permission`, applies the permission to all resources of - `type` owned by this organization. + In a `permission`, applies the permission to all resources of `type` owned by this organization. type: string type: - description: > + description: | The type of resource. - - In a `permission`, applies the permission to all resources of - this type. + In a `permission`, applies the permission to all resources of this type. enum: - authorizations - buckets @@ -3615,9 +3492,7 @@ components: $ref: '#/components/schemas/NodeType' type: object PipeLiteral: - description: >- - Represents a specialized literal value, indicating the left hand value - of a pipe expression + description: Represents a specialized literal value, indicating the left hand value of a pipe expression properties: type: $ref: '#/components/schemas/NodeType' @@ -3641,41 +3516,27 @@ components: $ref: '#/components/schemas/RetentionRules' rp: default: '0' - description: > - Retention policy is an InfluxDB 1.x concept that represents the - duration - - of time that each data point in the retention policy persists. Use - `rp` - + description: | + Retention policy is an InfluxDB 1.x concept that represents the duration + of time that each data point in the retention policy persists. Use `rp` for compatibility with InfluxDB 1.x. - The InfluxDB 2.x and Cloud equivalent is - - [retention - period](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-period). + [retention period](/influxdb/cloud/reference/glossary/#retention-period). type: string schemaType: $ref: '#/components/schemas/SchemaType' default: implicit - description: > + description: | Schema Type. - - Use `explicit` to enforce column names, tags, fields, and data types - for - + Use `explicit` to enforce column names, tags, fields, and data types for your data. - #### InfluxDB Cloud - - Default is `implicit`. - #### InfluxDB OSS - - Doesn't support `schemaType`. required: - orgID @@ -3731,22 +3592,18 @@ components: type: string params: additionalProperties: true - description: > + description: | Key-value pairs passed as parameters during query execution. - - To use parameters in your query, pass a _`query`_ with `params` - references (in dot notation)--for example: - + 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)" + 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", @@ -3754,14 +3611,10 @@ components: } ``` - - During query execution, InfluxDB passes _`params`_ to your script - and substitutes the values. - + 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: @@ -3830,9 +3683,7 @@ components: type: string type: object RegexpLiteral: - description: >- - Expressions begin and end with `/` and are regular expressions with - syntax accepted by RE2 + description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 properties: type: $ref: '#/components/schemas/NodeType' @@ -3856,9 +3707,7 @@ components: Resource: properties: id: - description: >- - If ID is set that is a permission for a specific resource. if it is - not set it is a permission for all resources of that resource type. + description: If ID is set that is a permission for a specific resource. if it is not set it is a permission for all resources of that resource type. nullable: true type: string name: @@ -3870,10 +3719,7 @@ components: nullable: true type: string orgID: - description: >- - If orgID is set that is a permission for all resources owned my that - org. if it is not set it is a permission for all resources of that - resource type. + description: If orgID is set that is a permission for all resources owned my that org. if it is not set it is a permission for all resources of that resource type. nullable: true type: string type: @@ -3951,37 +3797,27 @@ components: properties: everySeconds: default: 2592000 - description: > - The duration in seconds for how long data will be kept in the - database. - + description: | + The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). - 0 represents infinite retention. example: 86400 format: int64 minimum: 0 type: integer shardGroupDurationSeconds: - description: > + description: | The shard group duration. - The duration or interval (in seconds) that each shard group covers. - #### InfluxDB Cloud - - Does not use `shardGroupDurationsSeconds`. - #### InfluxDB OSS - - Default value depends on the - - [bucket retention - period](https://docs.influxdata.com/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](/influxdb/cloud/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -4106,10 +3942,7 @@ components: Run: properties: finishedAt: - description: >- - The time ([RFC3339Nano date/time - format](https://go.dev/src/time/format.go)) the run finished - executing. + description: The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true @@ -4145,26 +3978,17 @@ components: readOnly: true type: array requestedAt: - description: >- - The time ([RFC3339Nano date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp)) - the run was manually requested. + description: The time ([RFC3339Nano date/time format](/influxdb/cloud/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true type: string scheduledFor: - description: >- - The time [RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp) - used for the run's `now` option. + description: The time [RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. format: date-time type: string startedAt: - description: >- - The time ([RFC3339Nano date/time - format](https://go.dev/src/time/format.go)) the run started - executing. + description: The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true @@ -4184,12 +4008,9 @@ components: RunManually: properties: scheduledFor: - description: > - The time [RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp) - + description: | + The time [RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. - Default is the server _now_ time. format: date-time nullable: true @@ -4367,14 +4188,14 @@ components: orgID: type: string script: - description: script to be executed + description: The script to execute. type: string updatedAt: format: date-time readOnly: true type: string url: - description: invocation endpoint address + description: The invocation endpoint address. type: string required: - name @@ -4409,17 +4230,11 @@ components: properties: params: additionalProperties: true - description: > + description: | The script parameters. - - `params` contains key-value pairs that map values to the - **params.keys** - + `params` contains key-value pairs that map values to the **params.keys** in a script. - - When you invoke a script with `params`, InfluxDB passes the values - as - + When you invoke a script with `params`, InfluxDB passes the values as invocation parameters to the script. type: object type: object @@ -4555,9 +4370,7 @@ components: description: Specifies the API token string. Specify either `URL` or `Token`. type: string url: - description: >- - Specifies the URL of the Slack endpoint. Specify either `URL` or - `Token`. + description: Specifies the URL of the Slack endpoint. Specify either `URL` or `Token`. type: string type: object type: object @@ -4700,9 +4513,7 @@ components: decimalPlaces: $ref: '#/components/schemas/DecimalPlaces' fieldOptions: - description: >- - fieldOptions represent the fields retrieved by the query with - customization options + description: fieldOptions represent the fields retrieved by the query with customization options items: $ref: '#/components/schemas/RenamableField' type: array @@ -4722,21 +4533,15 @@ components: tableOptions: properties: fixFirstColumn: - description: >- - fixFirstColumn indicates whether the first column of the table - should be locked + description: fixFirstColumn indicates whether the first column of the table should be locked type: boolean sortBy: $ref: '#/components/schemas/RenamableField' verticalTimeAxis: - description: >- - verticalTimeAxis describes the orientation of the table by - indicating whether the time axis will be displayed vertically + description: verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically type: boolean wrapping: - description: >- - Wrapping describes the text wrapping style to be used in table - views + description: Wrapping describes the text wrapping style to be used in table views enum: - truncate - wrap @@ -4744,9 +4549,7 @@ components: type: string type: object timeFormat: - description: >- - timeFormat describes the display format for time values according to - moment.js date formatting + description: timeFormat describes the display format for time values according to moment.js date formatting type: string type: enum: @@ -4781,41 +4584,35 @@ components: Task: properties: authorizationID: - description: >- - The ID of the authorization used when the task communicates with the - query engine. + description: | + An authorization ID. + Specifies the authorization used when the task communicates with the query engine. + + To find an authorization ID, use the + [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to + list authorizations. type: string createdAt: format: date-time readOnly: true type: string cron: - description: >- - A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) - that defines the schedule on which the task runs. InfluxDB uses the - system time when evaluating Cron expressions. + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. type: string description: - description: The description of the task. + description: A description of the task. type: string every: - description: >- - The interval ([duration - literal](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) - at which the task runs. `every` also determines when the task first - runs, depending on the specified time. + description: The interval ([duration literal](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. format: duration type: string flux: - description: > - The Flux script that the task runs. - + description: | + The Flux script that the task executes. #### Limitations - - - - If you use the `flux` property, you can't use the `scriptID` and - `scriptParameters` properties. + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + format: flux type: string id: readOnly: true @@ -4833,10 +4630,7 @@ components: readOnly: true type: string latestCompleted: - description: >- - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) - of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -4867,46 +4661,52 @@ components: 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. + 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 the task. + description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) name. + Specifies the organization that owns the task. type: string orgID: - description: The ID of the organization that owns the task. + description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) ID. + Specifies the organization that owns the task. type: string ownerID: - description: The ID of the user who owns the task. + description: | + A [user](/influxdb/cloud/reference/glossary/#user) ID. + Specifies the owner of the task. + + To find a user ID, you can use the + [`GET /api/v2/users` endpoint](#operation/GetUsers) to + list users. type: string scriptID: - description: > - The ID of the script that the task runs. - + description: | + A script ID. + Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. #### Limitations + - If you use the `scriptID` property, you can't use the `flux` property. - - If you use the `scriptID` property, you can't use the `flux` - property. + #### Related guides + + - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) type: string scriptParameters: - description: > - The parameter key-value pairs passed to the script (referenced by - `scriptID`) during the task run. - + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the script specified by `scriptID`. + When running the task, InfluxDB executes the script with the parameters + you provide. #### Limitations - - - `scriptParameters` requires `scriptID`. - - - If you use the `scriptID` and `scriptParameters` properties, you - can't use the `flux` property. + - To use `scriptParameters`, you must provide a `scriptID`. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. type: object status: $ref: '#/components/schemas/TaskStatusType' @@ -4922,43 +4722,29 @@ components: 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. + 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: 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. + 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: > + description: | The Flux script that the task runs. - #### Limitations - - - If you use the `flux` property, you can't use the `scriptID` and - `scriptParameters` properties. + - 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. + 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: @@ -4968,29 +4754,21 @@ components: description: The ID of the organization that owns the task. type: string scriptID: - description: > + description: | The ID of the script that the task runs. - #### Limitations - - - If you use the `scriptID` property, you can't use the `flux` - property. + - 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. - + 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. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. type: object status: $ref: '#/components/schemas/TaskStatusType' @@ -5155,14 +4933,10 @@ components: - $ref: '#/components/schemas/NotificationEndpointBase' - properties: channel: - description: >- - The ID of the telegram channel; a chat_id in - https://core.telegram.org/bots/api#sendmessage . + description: The ID of the telegram channel; a chat_id in https://core.telegram.org/bots/api#sendmessage . type: string token: - description: >- - Specifies the Telegram bot token. See - https://core.telegram.org/bots#creating-a-new-bot . + description: Specifies the Telegram bot token. See https://core.telegram.org/bots#creating-a-new-bot . type: string required: - token @@ -5176,27 +4950,20 @@ components: TelegramNotificationRuleBase: properties: disableWebPagePreview: - description: >- - Disables preview of web links in the sent messages when "true". - Defaults to "false". + description: Disables preview of web links in the sent messages when "true". Defaults to "false". type: boolean messageTemplate: description: The message template as a flux interpolated string. type: string parseMode: - description: >- - Parse mode of the message text per - https://core.telegram.org/bots/api#formatting-options. Defaults to - "MarkdownV2". + description: Parse mode of the message text per https://core.telegram.org/bots/api#formatting-options. Defaults to "MarkdownV2". enum: - MarkdownV2 - HTML - Markdown type: string type: - description: >- - The discriminator between other types of notification rules is - "telegram". + description: The discriminator between other types of notification rules is "telegram". enum: - telegram type: string @@ -5217,72 +4984,58 @@ components: kind: $ref: '#/components/schemas/TemplateKind' metadata: - description: > - Metadata properties used for the resource when the template is - applied. + description: | + Metadata properties used for the resource when the template is applied. properties: name: type: string type: object spec: - description: > - Configuration properties used for the resource when the template - is applied. - + description: | + Configuration properties used for the resource when the template is applied. Key-value pairs map to the specification for the resource. - - The following code samples show `spec` configurations for template - resources: - + The following code samples show `spec` configurations for template resources: - A bucket: - ```json - { "spec": { - "name": "iot_center", - "retentionRules": [{ - "everySeconds": 2.592e+06, - "type": "expire" - }] - } + ```json + { "spec": { + "name": "iot_center", + "retentionRules": [{ + "everySeconds": 2.592e+06, + "type": "expire" + }] } - ``` + } + ``` - A variable: - ```json - { "spec": { - "language": "flux", - "name": "Node_Service", - "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", - tag: \"service\")", - "type": "query" - } + ```json + { "spec": { + "language": "flux", + "name": "Node_Service", + "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", + tag: \"service\")", + "type": "query" } - ``` + } + ``` type: object type: object type: array TemplateApply: properties: actions: - description: > + description: | A list of `action` objects. + Actions let you customize how InfluxDB applies templates in the request. - Actions let you customize how InfluxDB applies templates in the - request. + You can use the following actions to prevent creating or updating resources: - - You can use the following actions to prevent creating or updating - resources: - - - - A `skipKind` action skips template resources of a specified - `kind`. - - - A `skipResource` action skips template resources with a specified - `metadata.name` + - A `skipKind` action skips template resources of a specified `kind`. + - A `skipResource` action skips template resources with a specified `metadata.name` and `kind`. items: oneOf: @@ -5317,14 +5070,11 @@ components: type: object type: array dryRun: - description: > + description: | Only applies a dry run of the templates passed in the request. - - Validates the template and generates a resource diff and summary. - - - Doesn't install templates or make changes to the InfluxDB - instance. + - Doesn't install templates or make changes to the InfluxDB instance. type: boolean envRefs: additionalProperties: @@ -5333,30 +5083,17 @@ components: - type: integer - type: number - type: boolean - description: > - An object with key-value pairs that map to **environment - references** in templates. - - - Environment references in templates are `envRef` objects with an - `envRef.key` + description: | + An object with key-value pairs that map to **environment references** in templates. + Environment references in templates are `envRef` objects with an `envRef.key` property. - - To substitute a custom environment reference value when applying - templates, - + To substitute a custom environment reference value when applying templates, pass `envRefs` with the `envRef.key` and the value. - - When you apply a template, InfluxDB replaces `envRef` objects in the - template - + When you apply a template, InfluxDB replaces `envRef` objects in the template with the values that you provide in the `envRefs` parameter. - - For more examples, see how to [define environment - references](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#define-environment-references). - + For more examples, see how to [define environment references](/influxdb/cloud/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -5364,25 +5101,17 @@ components: - `spec.endpointName` - `spec.associations.name` - For more information about including environment references in - template fields, see how to - - [include user-definable resource - names](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names). + For more information about including environment references in template fields, see how to + [include user-definable resource names](/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names). type: object orgID: - description: > + description: | Organization ID. - InfluxDB applies templates to this organization. - The organization owns all resources created by the template. - To find your organization, see how to - - [view - organizations](https://docs.influxdata.com/influxdb/cloud/organizations/view-orgs/). + [view organizations](/influxdb/cloud/organizations/view-orgs/). type: string remotes: description: | @@ -5403,99 +5132,72 @@ components: secrets: additionalProperties: type: string - description: > + description: | An object with key-value pairs that map to **secrets** in queries. - Queries may reference secrets stored in InfluxDB--for example, - - the following Flux script retrieves `POSTGRES_USERNAME` and - `POSTGRES_PASSWORD` - + the following Flux script retrieves `POSTGRES_USERNAME` and `POSTGRES_PASSWORD` secrets and then uses them to connect to a PostgreSQL database: - ```js - import "sql" - import "influxdata/influxdb/secrets" + ```js + import "sql" + import "influxdata/influxdb/secrets" - username = secrets.get(key: "POSTGRES_USERNAME") - password = secrets.get(key: "POSTGRES_PASSWORD") + username = secrets.get(key: "POSTGRES_USERNAME") + password = secrets.get(key: "POSTGRES_PASSWORD") - sql.from( - driverName: "postgres", - dataSourceName: "postgresql://${username}:${password}@localhost:5432", - query: "SELECT * FROM example_table", - ) - ``` + sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost:5432", + query: "SELECT * FROM example_table", + ) + ``` To define secret values in your `/api/v2/templates/apply` request, - pass the `secrets` parameter with key-value pairs--for example: - ```json - { - ... - "secrets": { - "POSTGRES_USERNAME": "pguser", - "POSTGRES_PASSWORD": "foo" - } - ... + ```json + { + ... + "secrets": { + "POSTGRES_USERNAME": "pguser", + "POSTGRES_PASSWORD": "foo" } - ``` - - InfluxDB stores the key-value pairs as secrets that you can access - with `secrets.get()`. + ... + } + ``` + InfluxDB stores the key-value pairs as secrets that you can access with `secrets.get()`. Once stored, you can't view secret values in InfluxDB. - #### Related guides - - - [How to pass secrets when installing a - template](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template) type: object stackID: - description: > + description: | ID of the stack to update. - - To apply templates to an existing stack in the organization, use the - `stackID` parameter. - + To apply templates to an existing stack in the organization, use the `stackID` parameter. If you apply templates without providing a stack ID, - InfluxDB initializes a new stack with all new resources. - - To find a stack ID, use the InfluxDB [`/api/v2/stacks` API - endpoint](#operation/ListStacks) to list stacks. - + To find a stack ID, use the InfluxDB [`/api/v2/stacks` API endpoint](#operation/ListStacks) to list stacks. #### Related guides - - - - [Stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) - - - [View - stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/view/) + - [Stacks](/influxdb/cloud/influxdb-templates/stacks/) + - [View stacks](/influxdb/cloud/influxdb-templates/stacks/view/) type: string template: - description: > + description: | A template object to apply. - A template object has a `contents` property - with an array of InfluxDB resource configurations. - Pass `template` to apply only one template object. - If you use `template`, you can't use the `templates` parameter. - - If you want to apply multiple template objects, use `templates` - instead. + If you want to apply multiple template objects, use `templates` instead. properties: contentType: type: string @@ -5544,9 +5246,7 @@ components: items: properties: defaultValue: - description: >- - Default value that will be provided for the reference when no - value is provided + description: Default value that will be provided for the reference when no value is provided nullable: true oneOf: - type: string @@ -5554,9 +5254,7 @@ components: - type: number - type: boolean envRefKey: - description: >- - Key identified as environment reference and is the key identified - in the template + description: Key identified as environment reference and is the key identified in the template type: string resourceField: description: Field the environment reference corresponds too @@ -5602,10 +5300,7 @@ components: kind: $ref: '#/components/schemas/TemplateKind' name: - description: >- - if defined with id, name is used for resource exported by id. - if defined independently, resources strictly matching name are - exported + description: if defined with id, name is used for resource exported by id. if defined independently, resources strictly matching name are exported type: string required: - id @@ -6416,7 +6111,7 @@ components: properties: id: description: | - The ID of the user. + The user ID. readOnly: true type: string links: @@ -6430,13 +6125,13 @@ components: type: object name: description: | - The name of the user. + The user name. type: string status: default: active - description: > - The status of a user. An inactive user won't have access to - resources. + description: | + The status of a user. + An inactive user can't read or write resources. enum: - active - inactive @@ -6720,76 +6415,57 @@ components: type: object securitySchemes: BasicAuthentication: - description: > + description: | ### Basic authentication scheme + Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it: - Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API - operations that support it: - - **username**: InfluxDB Cloud username - - **password**: InfluxDB Cloud API token + - **username**: InfluxDB Cloud username + - **password**: InfluxDB Cloud API token #### Example - - `curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query" - --user "exampleuser@influxdata.com":"INFLUX_API_TOKEN"` + ```sh + curl --get "https://europe-west1-1.gcp.cloud2.influxdata.com/query" + --user "exampleuser@influxdata.com":"INFLUX_API_TOKEN" + ``` Replace the following: - - *`exampleuser@influxdata.com`*: the email address that you signed up - with - - - *`INFLUX_API_TOKEN`*: your [InfluxDB API - token](/influxdb/cloud/reference/glossary/#token) + - *`exampleuser@influxdata.com`*: the email address that you signed up with + - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) scheme: basic type: http TokenAuthentication: - description: > - Use the [Token - authentication](#section/Authentication/TokenAuthentication) - + description: | + Use the [Token authentication](#section/Authentication/TokenAuthentication) scheme to authenticate to the InfluxDB API. - - In your API requests, send an `Authorization` header. - - For the header value, provide the word `Token` followed by a space and - an InfluxDB API token. - + For the header value, provide the word `Token` followed by a space and an InfluxDB API token. The word `Token` is case-sensitive. - - ### Syntax - - `Authorization: Token YOUR_INFLUX_API_TOKEN` - - + `Authorization: Token INFLUX_API_TOKEN` For more information and examples, see the following: - - [`/authorizations`](#tag/Authorizations) endpoint. - - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication). - - [Manage API tokens](/influxdb/cloud/security/tokens/). + + - [`/authorizations`(#tag/Authorizations) endpoints] + - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication) + - [Manage API tokens](/influxdb/cloud/security/tokens/) in: header name: Authorization type: apiKey info: title: InfluxDB Cloud API Service version: Cloud 2.x - description: > - The InfluxDB v2 API provides a programmatic interface for all interactions - with InfluxDB. - + description: | + The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. - This documentation is generated from the - - [InfluxDB OpenAPI - specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml). + [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml). openapi: 3.0.0 paths: /api/v2: @@ -6810,69 +6486,63 @@ paths: - System information endpoints /api/v2/authorizations: get: - description: > + description: | Retrieves a list of authorizations. - - To limit which authorizations are returned, pass query parameters in - your request. - - If no query parameters are passed, InfluxDB returns all authorizations - for the organization. - + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations for the organization. #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API - token](/influxdb/cloud/reference/glossary/#token) + - InfluxDB Cloud doesn't expose [API token](/influxdb/cloud/reference/glossary/#token) values in `GET /api/v2/authorizations` responses; returns `token: redacted` for all authorizations. #### Required permissions for InfluxDB Cloud - - `read-authorizations` - #### Related guides - - - [View tokens](/influxdb/cloud/security/tokens/view-tokens/). + - [View tokens](/influxdb/cloud/security/tokens/view-tokens/) operationId: GetAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to this user. + Only returns authorizations scoped to the specified + [user](/influxdb/cloud/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to this user. + Only returns authorizations scoped to the specified + [user](/influxdb/cloud/reference/glossary/#user). in: query name: user schema: type: string - description: | An organization ID. - Only returns authorizations that belong to this organization. + Only returns authorizations that belong to the specified + [organization](/influxdb/cloud/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns authorizations that belong to this organization. + Only returns authorizations that belong to the specified + [organization](/influxdb/cloud/reference/glossary/#organization). in: query name: org schema: type: string - description: | - A token value. - Only returns the authorization that has this token. + An API [token](/influxdb/cloud/reference/glossary/#token) value. + Returns the authorization for the specified token. in: query name: token schema: @@ -6898,62 +6568,36 @@ paths: tags: - Authorizations post: - description: > - Creates an authorization. - - - Use this endpoint to create an authorization, which generates an API - token - - with permissions to `read` or `write` to a specific resource or `type` - of resource. - - The response contains the new authorization with the generated API - token. + description: | + Creates an authorization and returns the authorization with the + generated API [token](/influxdb/cloud/reference/glossary/#token). + Use this endpoint to create an authorization, which generates an API token + with permissions to `read` or `write` to a specific resource or `type` of resource. Keep the following in mind when creating and updating authorizations: - - - To apply a permission to a specific resource, specify the resource - `id` field. - - - To apply a permission to all resources with the type, omit the - resource `id`. - - - To scope an authorization to a specific user, provide the `userID` - property. - + - To apply a permission to a specific resource, specify the resource `id` field. + - To apply a permission to all resources with the type, omit the resource `id`. + - To scope an authorization to a specific user, provide the `userID` property. #### Limitations - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud enforces access restrictions on API tokens. - - - InfluxDB Cloud only allows access to the API token value immediately - after the authorization is created. - - - You can’t change access (read/write) permissions for an API token - after it’s created. - + - InfluxDB Cloud only allows access to the API token value immediately after the authorization is created. + - You can’t change access (read/write) permissions for an API token after it’s created. - Tokens stop working when the user who created the token is deleted. - We recommend the following for managing your tokens: - - Create a generic user to create and manage tokens for writing data. - - Store your tokens in a secure password vault for future access. - #### Related guides - - - [Create a token](/influxdb/cloud/security/tokens/create-token/). + - [Create a token](/influxdb/cloud/security/tokens/create-token/) operationId: PostAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -6970,7 +6614,8 @@ paths: application/json: schema: $ref: '#/components/schemas/Authorization' - description: Authorization created + description: | + Success. The authorization is created. The response body contains the authorization. '400': $ref: '#/components/responses/GeneralServerError' description: Invalid request @@ -7094,33 +6739,23 @@ paths: - Authorizations /api/v2/buckets: get: - description: > - Retrieves a list of - [buckets](/influxdb/cloud/reference/glossary/#bucket). - - - To limit which buckets are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all buckets up to - the + description: | + Retrieves a list of [buckets](/influxdb/cloud/reference/glossary/#bucket). + To limit which buckets are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all buckets up to the default `limit`. - #### Limitations - - - Paging with an `offset` greater than the number of records will result - in - + - Paging with an `offset` greater than the number of records will result in an empty list of buckets--for example: The following request is paging to the 50th record, but the user only has 10 buckets. ```sh - $ curl --request GET "INFLUX_URL/api/v2/scripts?limit=1&offset=50" + $ curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" $ { "links": { @@ -7133,7 +6768,6 @@ paths: #### Related Guides - - [Manage buckets](/influxdb/cloud/organizations/buckets/) operationId: GetBuckets parameters: @@ -7217,8 +6851,7 @@ paths: type: system updatedAt: '2022-03-15T17:22:33.726179487Z' links: - self: >- - /api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID + self: /api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID schema: $ref: '#/components/schemas/Buckets' description: | @@ -7240,56 +6873,36 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "http://localhost:8086/api/v2/buckets?name=_monitoring" \ + source: | + curl --request GET "http://localhost:8086/api/v2/buckets?name=_monitoring" \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" post: - description: > + description: | Creates a [bucket](/influxdb/cloud/reference/glossary/#bucket) - and returns the created bucket along with metadata. The default data - [retention period](/influxdb/cloud/reference/glossary/#retention-period) - is 30 days. - #### InfluxDB OSS - - A single InfluxDB OSS instance supports active writes or queries for - - approximately 20 buckets across all organizations at a given time. - Reading - + approximately 20 buckets across all organizations at a given time. Reading or writing to more than 20 buckets at a time can adversely affect - performance. - #### Limitations - - InfluxDB Cloud Free Plan allows users to create up to two buckets. - Exceeding the bucket quota will result in an HTTP `403` status code. - For additional information regarding InfluxDB Cloud offerings, see - - [InfluxDB Cloud - Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). - + [InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). #### Related Guides - - [Create bucket](/influxdb/cloud/organizations/buckets/create-bucket/) - - - [Create bucket CLI - reference](/influxdb/cloud/reference/cli/influx/bucket/create) + - [Create bucket CLI reference](/influxdb/cloud/reference/cli/influx/bucket/create) operationId: PostBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7401,13 +7014,11 @@ paths: }' /api/v2/buckets/{bucketID}: delete: - description: > + description: | Deletes a bucket and all associated records. - #### InfluxDB Cloud - - Does the following when you send a delete request: 1. Validates the request and queues the delete. @@ -7416,23 +7027,16 @@ paths: #### InfluxDB OSS - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - #### Limitations - - Only one bucket can be deleted per request. - #### Related Guides - - - [Delete a - bucket](/influxdb/cloud/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](/influxdb/cloud/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) operationId: DeleteBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7499,9 +7103,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request DELETE - "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ + source: | + curl --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ --header "Authorization: Token INFLUX_TOKEN" \ --header 'Accept: application/json' get: @@ -7579,36 +7182,24 @@ paths: tags: - Buckets patch: - description: > + description: | Updates a bucket. - Use this endpoint to update properties - (`name`, `description`, and `retentionRules`) of a bucket. - #### InfluxDB Cloud - - - Requires the `retentionRules` property in the request body. If you - don't - - provide `retentionRules`, InfluxDB responds with an HTTP `403` status - code. - + - Requires the `retentionRules` property in the request body. If you don't + provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. #### InfluxDB OSS - - Doesn't require `retentionRules`. - #### Related Guides - - - [Update a - bucket](/influxdb/cloud/organizations/buckets/update-bucket/) + - [Update a bucket](/influxdb/cloud/organizations/buckets/update-bucket/) operationId: PatchBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7659,17 +7250,13 @@ paths: application/json: examples: invalidJSONStringValue: - description: > - If the request body contains invalid JSON, InfluxDB returns - `invalid` - + description: | + If the request body contains invalid JSON, InfluxDB returns `invalid` with detail about the problem. summary: Invalid JSON value: code: invalid - message: >- - invalid json: invalid character '\'' looking for beginning - of value + message: 'invalid json: invalid character ''\'''' looking for beginning of value' schema: $ref: '#/components/schemas/Error' description: | @@ -7681,10 +7268,8 @@ paths: application/json: examples: invalidRetention: - summary: > - The retention policy provided exceeds the max retention for - the - + summary: | + The retention policy provided exceeds the max retention for the organization. value: code: forbidden @@ -7722,9 +7307,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID - \ + source: | + curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -7740,34 +7324,20 @@ paths: }' /api/v2/buckets/{bucketID}/labels: get: - description: > + description: | Retrieves a list of all labels for a bucket. - - Labels are objects that contain `labelID`, `name`, `description`, and - `color` - + Labels are objects that contain `labelID`, `name`, `description`, and `color` key-value pairs. They may be used for grouping and filtering InfluxDB - resources. - - Labels are also capable of grouping across different resources--for - example, - - you can apply a label named `air_sensor` to a bucket and a task to - quickly - + Labels are also capable of grouping across different resources--for example, + you can apply a label named `air_sensor` to a bucket and a task to quickly organize resources. - #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to - retrieve and manage labels. - - - [Manage labels in the InfluxDB - UI](/influxdb/cloud/visualize-data/labels/) + - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - [Manage labels in the InfluxDB UI](/influxdb/cloud/visualize-data/labels/) operationId: GetBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7814,36 +7384,24 @@ paths: tags: - Buckets post: - description: > + description: | Adds a label to a bucket and returns the new label information. - - Labels are objects that contain `labelID`, `name`, `description`, and - `color` - - key-value pairs. They may be used for grouping and filtering across one - or - + Labels are objects that contain `labelID`, `name`, `description`, and `color` + key-value pairs. They may be used for grouping and filtering across one or more kinds of **resources**--for example, you can apply a label named - `air_sensor` to a bucket and a task to quickly organize resources. - #### Limitations - - Before adding a label to a bucket, you must create the label if you haven't already. To create a label with the InfluxDB API, send a `POST` request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to - retrieve and manage labels. - - - [Manage labels in the InfluxDB - UI](/influxdb/cloud/visualize-data/labels/) + - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - [Manage labels in the InfluxDB UI](/influxdb/cloud/visualize-data/labels/) operationId: PostBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7921,9 +7479,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -8091,7 +7648,7 @@ paths: $ref: '#/components/responses/BadRequestError' examples: invalidRequest: - summary: The `userID` is missing from the request body. + summary: The user `id` is missing from the request body. value: code: invalid message: user id missing or invalid @@ -8113,10 +7670,9 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ - --header "Authorization: Token INFLUX_TOKEN" \ + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ + --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ @@ -8124,21 +7680,15 @@ paths: } /api/v2/buckets/{bucketID}/members/{userID}: delete: - description: > + description: | Removes a member from a bucket. - - Use this endpoint to remove a user's member privileges from a bucket. - This - + Use this endpoint to remove a user's member privileges from a bucket. This removes the user's `read` and `write` permissions for the bucket. - #### Related guides - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) operationId: DeleteBucketsIDMembersID parameters: @@ -8179,10 +7729,42 @@ paths: - Buckets /api/v2/buckets/{bucketID}/owners: get: + description: | + Retrieves a list of all [owners](/influxdb/cloud/reference/glossary/#owner) + for a bucket. + + Bucket owners have permission to delete buckets and remove user and member + permissions from the bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `read-orgs INFLUX_ORG_ID` + + `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve a + list of owners for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) operationId: GetBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. + - description: | + The ID of the bucket to retrieve owners for. in: path name: bucketID required: true @@ -8192,9 +7774,31 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/buckets/BUCKET_ID/owners + users: + - id: d88d182d91b0950f + links: + self: /api/v2/users/d88d182d91b0950f + name: example-owner + role: owner + status: active schema: $ref: '#/components/schemas/ResourceOwners' - description: A list of bucket owners + description: | + Success. + The response body contains a list of all owners for the bucket. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -8205,10 +7809,41 @@ paths: tags: - Buckets post: + description: | + Adds an owner to a bucket and returns the [owners](/influxdb/cloud/reference/glossary/#owner) + with role and user detail. + + Use this endpoint to create a _resource owner_ for the bucket. + Bucket owners have permission to delete buckets and remove user and member + permissions from the bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + `INFLUX_ORG_ID` is the ID of the organization that you want add an owner for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) operationId: PostBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. + - description: | + The ID of the bucket to add an owner for. in: path name: bucketID required: true @@ -8217,9 +7852,18 @@ paths: requestBody: content: application/json: + examples: + successResponse: + value: + id: d88d182d91b0950f + links: + self: /api/v2/users/d88d182d91b0950f + name: example-user + role: owner + status: active schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner + description: A user to add as an owner for the bucket. required: true responses: '201': @@ -8227,7 +7871,25 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceOwner' - description: Success. The user is an owner of the bucket + description: | + Created. + The bucket `owner` role is assigned to the user. + The response body contains the resource owner with + role and user detail. + '400': + $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The user `id` is missing from the request body. + value: + code: invalid + message: user id missing or invalid + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -8237,18 +7899,59 @@ paths: summary: Add an owner to a bucket tags: - Buckets + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/owners \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + } /api/v2/buckets/{bucketID}/owners/{userID}: delete: + description: | + Removes an owner from a bucket. + + Use this endpoint to remove a user's `owner` role for a bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + `INFLUX_ORG_ID` is the ID of the organization that you want to remove an owner + from. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) operationId: DeleteBucketsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. + - description: | + The ID of the owner to remove. in: path name: userID required: true schema: type: string - - description: The bucket ID. + - description: | + The ID of the bucket to remove an owner from. in: path name: bucketID required: true @@ -8256,7 +7959,15 @@ paths: type: string responses: '204': - description: Owner removed + description: | + Success. + The user is no longer an owner of the bucket. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -8350,42 +8061,31 @@ paths: application/json: examples: badNameExample: - description: >- - The error returned when the name is invalid, such as too few - or too many characters or the name contains non-printable - ASCII or is not valid UTF-8. + description: The error returned when the name is invalid, such as too few or too many characters or the name contains non-printable ASCII or is not valid UTF-8. summary: Invalid name value: code: invalid message: name is invalid duplicateColumnNamesExample: - description: >- - The error returned when the request body contains duplicate - column names. + description: The error returned when the request body contains duplicate column names. summary: Duplicate column names value: code: invalid message: Duplicate column names missingColumnsExample: - description: >- - The error returned when the request body is missing the - columns property. + description: The error returned when the request body is missing the columns property. summary: Missing columns value: code: invalid message: columns is required missingFieldExample: - description: >- - The error returned when the request body is missing at least - one field type column. + description: The error returned when the request body is missing at least one field type column. summary: Missing field value: code: invalid message: At least one field column is required missingTimestampExample: - description: >- - The error returned when the request body is missing a - timestamp type column. + description: The error returned when the request body is missing a timestamp type column. summary: Missing timestamp value: code: invalid @@ -8480,9 +8180,7 @@ paths: application/json: examples: missingColumnsExample: - description: >- - The error returned when the request body does not contain - all the columns from the source. + description: The error returned when the request body does not contain all the columns from the source. summary: Deleted columns value: code: invalid @@ -8830,9 +8528,7 @@ paths: maximum: 100 minimum: -1 type: integer - - description: >- - A user identifier. Returns only dashboards where this user has the - `owner` role. + - description: A user identifier. Returns only dashboards where this user has the `owner` role. in: query name: owner schema: @@ -8846,9 +8542,7 @@ paths: - CreatedAt - UpdatedAt type: string - - description: >- - A list of dashboard identifiers. Returns only the listed dashboards. - If both `id` and `owner` are specified, only `id` is used. + - description: A list of dashboard identifiers. Returns only the listed dashboards. If both `id` and `owner` are specified, only `id` is used. in: query name: id schema: @@ -8998,9 +8692,7 @@ paths: properties: cells: $ref: '#/components/schemas/CellWithViewProperties' - description: >- - optional, when provided will replace all existing cells with - the cells provided + description: optional, when provided will replace all existing cells with the cells provided description: description: optional, when provided will replace the description type: string @@ -9075,9 +8767,7 @@ paths: - Cells - Dashboards put: - description: >- - Replaces all cells in a dashboard. This is used primarily to update the - positional information of all cells. + description: Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells. operationId: PutDashboardsIDCells parameters: - $ref: '#/components/parameters/TraceSpan' @@ -9153,9 +8843,7 @@ paths: - Cells - Dashboards patch: - description: >- - Updates the non positional information related to a cell. Updates to a - single cell's positional data could cause grid conflicts. + description: Updates the non positional information related to a cell. Updates to a single cell's positional data could cause grid conflicts. operationId: PatchDashboardsIDCellsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -9793,17 +9481,13 @@ paths: - DBRPs /api/v2/delete: post: - description: > + description: | Deletes data from a bucket. - - Use this endpoint to delete points from a bucket in a specified time - range. - + Use this endpoint to delete points from a bucket in a specified time range. #### InfluxDB Cloud - - Does the following when you send a delete request: 1. Validates the request and queues the delete. @@ -9812,103 +9496,74 @@ paths: #### InfluxDB OSS - - Validates the request, handles the delete synchronously, and then responds with success or failure. #### Required permissions - - `write-buckets` or `write-bucket BUCKET_ID`. `BUCKET_ID` is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) - `write` rate limits apply. - - For more information, see [limits and adjustable - quotas](/influxdb/cloud/account-management/limits/). - + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - - [Delete data](/influxdb/cloud/write-data/delete-data/). - - - Learn how to use [delete predicate - syntax](/influxdb/cloud/reference/syntax/delete-predicate/). - - - Learn how InfluxDB handles [deleted - tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) + - [Delete data](/influxdb/cloud/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). + - Learn how InfluxDB handles [deleted tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). operationId: PostDelete parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > + - description: | The organization to delete data from. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Deletes data from the bucket in the organization associated with - the authorization (API token). - + - Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: org schema: description: The organization name or ID. type: string - - description: > + - description: | The name or ID of the bucket to delete data from. - - If you pass both `bucket` and `bucketID`, `bucketID` takes - precedence. + If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. in: query name: bucket schema: description: The bucket name or ID. type: string - - description: > + - description: | The ID of the organization to delete data from. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Deletes data from the bucket in the organization associated with - the authorization (API token). - + - Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: orgID schema: description: The organization ID. type: string - - description: > + - description: | The ID of the bucket to delete data from. - - If you pass both `bucket` and `bucketID`, `bucketID` takes - precedence. + If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. in: query name: bucketID schema: @@ -9919,61 +9574,38 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletePredicateRequest' - description: > + description: | Time range parameters and an optional **delete predicate expression**. - To select points to delete within the specified time range, pass a - - **delete predicate expression** in the `predicate` property of the - request body. - - If you don't pass a `predicate`, InfluxDB deletes all data with - timestamps - + **delete predicate expression** in the `predicate` property of the request body. + If you don't pass a `predicate`, InfluxDB deletes all data with timestamps in the specified time range. - #### Related guides - - - [Delete data](/influxdb/cloud/write-data/delete-data/). - - - Learn how to use [delete predicate - syntax](/influxdb/cloud/reference/syntax/delete-predicate/). + - [Delete data](/influxdb/cloud/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). required: true responses: '204': - description: > + description: | Success. - #### InfluxDB Cloud - - Validated and queued the request. + - Handles the delete asynchronously - the deletion might not have completed yet. - - Handles the delete asynchronously - the deletion might not have - completed yet. - - - An HTTP `2xx` status code acknowledges that the write or delete is - queued. - - To ensure that InfluxDB Cloud handles writes and deletes in the - order you request them, - + An HTTP `2xx` status code acknowledges that the write or delete is queued. + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request. - Because writes are asynchronous, data might not yet be written - when you receive the response. - #### InfluxDB OSS - - Deleted the data. '400': content: @@ -9986,17 +9618,13 @@ paths: 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` doesn't match an - organization. + - Returns this error if `org` or `orgID` doesn't match an organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -10012,9 +9640,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ + source: | + curl --request POST INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ @@ -10202,9 +9829,7 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: >- - Success. The response body contains the currently authenticated - user. + description: Success. The response body contains the currently authenticated user. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -10217,13 +9842,50 @@ paths: /api/v2/me/password: put: description: | + Updates the password for the signed-in [user](/influxdb/cloud/reference/glossary/#user). + + This endpoint represents the third step in the following three-step process to let a + user with a user session update their password: + 1. Pass the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) to the `POST /api/v2/signin` + endpoint to create a user session and generate a session cookie. + 2. From the response in the first step, extract the session cookie (`Set-Cookie`) header. + 3. Pass the following in a request to the `PUT /api/v2/me/password` endpoint: + - The `Set-Cookie` header from the second step + - The `Authorization Basic` header with the user's _Basic authentication_ credentials + - `{"password": "NEW_PASSWORD"}` in the request body + #### InfluxDB Cloud - InfluxDB Cloud doesn't support changing user passwords through the API. - Use the InfluxDB Cloud user interface to update your password. + - Doesn't allow you to manage passwords through the API. + Use the InfluxDB Cloud user interface (UI) to update your password. + + #### Related endpoints + + - [Signin](#tag/Signin) + - [Signout](#tag/Signout) + - [Users](#tag/Users) + + #### Related guides + + - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) operationId: PutMePassword parameters: - $ref: '#/components/parameters/TraceSpan' + - description: | + The user session cookie for the + [user](/influxdb/cloud/reference/glossary/#user) + signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + example: influxdb-oss-session=19aaaZZZGOvP2GGryXVT2qYftlFKu3bIopurM6AGFow1yF1abhtOlbHfsc-d8gozZFC_6WxmlQIAwLMW5xs523w== + in: cookie + name: influxdb-oss-session + required: true + schema: + type: string requestBody: content: application/json: @@ -10233,13 +9895,20 @@ paths: required: true responses: '204': - description: Success. The password was updated. + description: Success. The password is updated. '400': - description: > + description: | Bad request. - InfluxDB Cloud doesn't support changing passwords through the API - and always responds with this status. + #### InfluxDB Cloud + + - Doesn't allow you to manage through the API; always responds with this status. + + #### InfluxDB OSS + + - Doesn't understand a value passed in the request. + '401': + $ref: '#/components/responses/AuthorizationError' default: content: application/json: @@ -10258,9 +9927,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - - description: >- - Only show notification endpoints that belong to specific - organization ID. + - description: Only show notification endpoints that belong to specific organization ID. in: query name: orgID required: true @@ -10542,9 +10209,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - - description: >- - Only show notification rules that belong to a specific organization - ID. + - description: Only show notification rules that belong to a specific organization ID. in: query name: orgID required: true @@ -10555,9 +10220,7 @@ paths: name: checkID schema: type: string - - description: >- - Only return notification rules that "would match" statuses which - contain the tag key value pairs provided. + - description: Only return notification rules that "would match" statuses which contain the tag key value pairs provided. in: query name: tag schema: @@ -10874,29 +10537,19 @@ paths: - Rules /api/v2/orgs: get: - description: > - Retrieves a list of - [organizations](/influxdb/cloud/reference/glossary/#organization/). - - - To limit which organizations are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all organizations up - to the default `limit`. + description: | + Retrieves a list of [organizations](/influxdb/cloud/reference/glossary/#organization/). + To limit which organizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. #### InfluxDB Cloud - - - Only returns the organization that owns the token passed in the - request. - + - Only returns the organization that owns the token passed in the request. #### Related guides - - - [View organizations](/influxdb/cloud/organizations/view-orgs/). + - [View organizations](/influxdb/cloud/organizations/view-orgs/) operationId: GetOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10967,22 +10620,16 @@ paths: - Organizations - Security and access endpoints post: - description: > - Creates an - [organization](/influxdb/cloud/reference/glossary/#organization) - + description: | + Creates an [organization](/influxdb/cloud/reference/glossary/#organization) and returns the newly created organization. - #### InfluxDB Cloud - - Doesn't allow you to use this endpoint to create organizations. - #### Related guides - - [Manage organizations](/influxdb/cloud/organizations) operationId: PostOrgs parameters: @@ -11081,7 +10728,7 @@ paths: #### Related guides - - [Delete organization](/influxdb/cloud/organizations/delete-orgs/) + - [Delete organizations](/influxdb/cloud/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11140,7 +10787,7 @@ paths: #### Related guides - - [View organization](/influxdb/cloud/organizations/view-orgs/) + - [View organizations](/influxdb/cloud/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11190,40 +10837,26 @@ paths: - Organizations - Security and access endpoints patch: - description: > + description: | Updates an organization. - Use this endpoint to update properties - (`name`, `description`) of an organization. - Updating an organization’s name affects all resources that reference the - organization by name, including the following: - - Queries - - Dashboards - - Tasks - - Telegraf configurations - - Templates - - If you change an organization name, be sure to update the organization - name - + If you change an organization name, be sure to update the organization name in these resources as well. - #### Related Guides - - [Update an organization](/influxdb/cloud/organizations/update-org/) operationId: PatchOrgsID parameters: @@ -11297,51 +10930,35 @@ paths: - Limits /api/v2/orgs/{orgID}/members: get: - description: > + description: | Retrieves a list of all users that belong to an organization. - InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have - permission to access InfluxDB. - [Members](/influxdb/cloud/reference/glossary/#member) are users - within the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `read-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you retrieve a list - of - + `INFLUX_ORG_ID` is the ID of the organization that you retrieve a list of members from. - #### Related guides - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) operationId: GetOrgsIDMembers parameters: @@ -11377,11 +10994,9 @@ paths: status: active schema: $ref: '#/components/schemas/ResourceMembers' - description: > + description: | Success. - - The response body contains a list of all users within the - organization. + The response body contains a list of all users within the organization. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -11414,48 +11029,33 @@ paths: - Organizations - Security and access endpoints post: - description: > - Adds a user to an organization. - + description: | + Add a user to an organization. InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have - permission to access InfluxDB. - [Members](/influxdb/cloud/reference/glossary/#member) are users - within the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `write-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want add a member - to. - + `INFLUX_ORG_ID` is the ID of the organization that you want add a member to. #### Related guides - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) operationId: PostOrgsIDMembers parameters: @@ -11492,7 +11092,7 @@ paths: $ref: '#/components/schemas/ResourceMember' description: | Success. - The response body contains the user. + The response body contains the user information. '400': $ref: '#/components/responses/BadRequestError' examples: @@ -11519,9 +11119,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ + source: | + curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -11530,41 +11129,31 @@ paths: }' /api/v2/orgs/{orgID}/members/{userID}: delete: - description: > + description: | Removes a member from an organization. - - Use this endpoint to remove a user's `read` and `write` permissions for the organization. - + Use this endpoint to remove a user's member privileges from a bucket. This + removes the user's `read` and `write` permissions from the organization. #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `write-orgs INFLUX_ORG_ID` - `INFLUX_ORG_ID` is the ID of the organization that you want to remove an - owner from. - #### Related guides - - [Manage members](/influxdb/cloud/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: @@ -11604,25 +11193,19 @@ paths: - Security and access endpoints /api/v2/orgs/{orgID}/owners: get: - description: > + description: | Retrieves a list of all owners of an organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions - - `read-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve - a - + `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve a list of owners from. operationId: GetOrgsIDOwners parameters: @@ -11670,32 +11253,24 @@ paths: - Organizations - Security and access endpoints post: - description: > + description: | Adds an owner to an organization. - Use this endpoint to assign the organization `owner` role to a user. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions - - `write-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want add an owner - for. - + `INFLUX_ORG_ID` is the ID of the organization that you want add an owner for. #### Related endpoints - - [Authorizations](#tag/Authorizations) operationId: PostOrgsIDOwners parameters: @@ -11751,9 +11326,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ + source: | + curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -11762,45 +11336,30 @@ paths: }' /api/v2/orgs/{orgID}/owners/{userID}: delete: - description: > + description: | Removes an [owner](/influxdb/cloud/reference/glossary/#owner) from - the organization. - - Organization owners have permission to delete organizations and remove - user and member - + Organization owners have permission to delete organizations and remove user and member permissions from the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `write-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want remove an - owner - + `INFLUX_ORG_ID` is the ID of the organization that you want remove an owner from. - #### Related endpoints - - [Authorizations](#tag/Authorizations) operationId: DeleteOrgsIDOwnersID parameters: @@ -11965,22 +11524,18 @@ paths: required: true schema: type: string - - description: > + - description: | Earliest time to include in results. - - For more information about timestamps, see [Manipulate timestamps - with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). + For more information about timestamps, see [Manipulate timestamps with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). in: query name: start required: true schema: format: unix timestamp type: integer - - description: > + - description: | Latest time to include in results. - - For more information about timestamps, see [Manipulate timestamps - with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). + For more information about timestamps, see [Manipulate timestamps with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). in: query name: stop required: false @@ -11999,25 +11554,16 @@ paths: content: text/csv: schema: - example: > - #group,false,false,true,true,false,false,true,true,true,true - #datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string - #default,_result,,,,,,,,, - ,result,table,_start,_stop,_time,_value,_field,_measurement,bucket_id,org_id - ,,0,2021-05-10T14:25:10.865702397Z,2021-05-10T15:25:10.865702397Z,2021-05-10T15:00:00Z,5434066,gauge,storage_usage_bucket_bytes,2f6ba0cf9a2fdcbb,cec6fc1d2176dc11 - ,,1,2021-05-10T14:25:10.865702397Z,2021-05-10T15:25:10.865702397Z,2021-05-10T15:00:00Z,9924053.966666665,gauge,storage_usage_bucket_bytes,8af67bcaf69d9daf,cec6fc1d2176dc11 + example: | + #group,false,false,true,true,false,false,true,true,true,true #datatype,string,long,dateTime:RFC3339,dateTime:RFC3339,dateTime:RFC3339,double,string,string,string,string #default,_result,,,,,,,,, ,result,table,_start,_stop,_time,_value,_field,_measurement,bucket_id,org_id ,,0,2021-05-10T14:25:10.865702397Z,2021-05-10T15:25:10.865702397Z,2021-05-10T15:00:00Z,5434066,gauge,storage_usage_bucket_bytes,2f6ba0cf9a2fdcbb,cec6fc1d2176dc11 ,,1,2021-05-10T14:25:10.865702397Z,2021-05-10T15:25:10.865702397Z,2021-05-10T15:00:00Z,9924053.966666665,gauge,storage_usage_bucket_bytes,8af67bcaf69d9daf,cec6fc1d2176dc11 type: string description: Usage data headers: Content-Encoding: - description: >- - Lists any encodings (usually compression algorithms) that have - been applied to the response payload. + description: Lists any encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity - description: >- - The content coding. `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -12074,44 +11620,29 @@ paths: - Ping /api/v2/query: post: - description: > + description: | Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a - bucket. - + Use this endpoint to send a Flux query request and retrieve data from a bucket. #### Rate limits (with InfluxDB Cloud) - `read` rate limits apply. - - For more information, see [limits and adjustable - quotas](/influxdb/cloud/account-management/limits/). - + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - - [Query with the InfluxDB - API](/influxdb/cloud/query-data/execute-queries/influx-api/). - - - [Get started with - Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + - [Query with the InfluxDB API](/influxdb/cloud/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: - $ref: '#/components/parameters/TraceSpan' - - description: >- - The content encoding (usually a compression algorithm) that the - client can understand. + - description: The content encoding (usually a compression algorithm) that the client can understand. in: header name: Accept-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -12123,43 +11654,31 @@ paths: - application/json - application/vnd.flux type: string - - description: > + - description: | The name or ID of the organization executing the query. - #### InfluxDB Cloud - - Doesn't use `org` or `orgID`. - - - Queries the bucket in the organization associated with the - authorization (API token). - + - Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: org schema: type: string - - description: > + - description: | The ID of the organization executing the query. - #### InfluxDB Cloud - - Doesn't use `org` or `orgID`. - - - Queries the bucket in the organization associated with the - authorization (API token). - + - Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: orgID @@ -12182,27 +11701,21 @@ paths: '200': content: application/csv: - example: > + 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: type: string description: Success. The response body contains query results. headers: Content-Encoding: - description: >- - Lists encodings (usually compression algorithms) that have been - applied to the response payload. + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity - description: > - The content coding: `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -12223,17 +11736,13 @@ paths: 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` doesn't match an - organization. + - Returns this error if `org` or `orgID` doesn't match an organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -12251,9 +11760,7 @@ paths: - doesn't return this error. headers: Retry-After: - description: >- - Non-negative decimal integer indicating seconds to wait before - retrying the request. + description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: format: int32 type: integer @@ -12278,13 +11785,10 @@ 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 - + description: | + Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax errors and returns the list of errors. - In the following sample query, `from()` is missing the property key. ```json @@ -12296,14 +11800,10 @@ paths: ``` If you pass this in a request to the `/api/v2/analyze` endpoint, - - InfluxDB returns an `errors` list that contains an error object for the - missing key. - + InfluxDB returns an `errors` list that contains an error object for the missing key. #### Limitations - - The endpoint doesn't validate values in the query--for example: - The following sample query has correct syntax, but contains an incorrect `from()` property key: @@ -12339,22 +11839,17 @@ paths: application/json: examples: missingQueryPropertyKey: - description: > - Returns an error object if the Flux query is missing a - property key. + description: | + Returns an error object if the Flux query is missing a property key. + The following sample query is missing the _`bucket`_ property key: - The following sample query is missing the _`bucket`_ - property key: - - ```json - { - "query": "from(: \"iot_center\")\ - - ... - - } - ``` + ```json + { + "query": "from(: \"iot_center\")\ + ... + } + ``` summary: Missing property key error value: errors: @@ -12364,27 +11859,20 @@ paths: message: missing property key schema: $ref: '#/components/schemas/AnalyzeQueryResponse' - description: > + description: | Success. - The response body contains the list of `errors`. - - If the query syntax is valid, the endpoint returns an empty `errors` - list. + 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. + 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 + message: 'invalid json: invalid character ''\'''' looking for beginning of value' schema: $ref: '#/components/schemas/Error' description: | @@ -12403,9 +11891,8 @@ paths: application/json: examples: emptyJSONObject: - description: > - If the request body contains an empty JSON object, returns - `internal error`. + description: | + If the request body contains an empty JSON object, returns `internal error`. summary: Empty JSON object in request body value: code: internal error @@ -12448,34 +11935,20 @@ paths: EOF /api/v2/query/ast: post: - description: > - Analyzes a Flux query and returns a complete package source [Abstract - Syntax - - Tree - (AST)](/influxdb/cloud/reference/glossary/#abstract-syntax-tree-ast) - + description: | + Analyzes a Flux query and returns a complete package source [Abstract Syntax + Tree (AST)](/influxdb/cloud/reference/glossary/#abstract-syntax-tree-ast) for the query. - - Use this endpoint for deep query analysis such as debugging unexpected - 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 - + A Flux query AST provides a semantic, tree-like representation with contextual + information about the query. The AST illustrates how the query is distributed into different components for execution. - #### Limitations - - The endpoint doesn't validate values in the query--for example: The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: @@ -12495,6 +11968,7 @@ paths: ``` The following code sample shows how to pass the query as JSON in the request body: + ```json { "query": "from(foo: \"iot_center\")\ |> range(start: -90d)\ @@ -12674,9 +12148,7 @@ paths: end: column: 47 line: 1 - source: >- - from(bucket: "example-bucket") |> - range(start: -5m) + source: 'from(bucket: "example-bucket") |> range(start: -5m)' start: column: 1 line: 1 @@ -12687,9 +12159,7 @@ paths: end: column: 108 line: 1 - source: >- - fn: (r) => r._measurement == - "example-measurement" + source: 'fn: (r) => r._measurement == "example-measurement"' start: column: 58 line: 1 @@ -12709,9 +12179,7 @@ paths: end: column: 108 line: 1 - source: >- - fn: (r) => r._measurement == - "example-measurement" + source: 'fn: (r) => r._measurement == "example-measurement"' start: column: 58 line: 1 @@ -12775,9 +12243,7 @@ paths: end: column: 108 line: 1 - source: >- - (r) => r._measurement == - "example-measurement" + source: (r) => r._measurement == "example-measurement" start: column: 62 line: 1 @@ -12820,9 +12286,7 @@ paths: end: column: 109 line: 1 - source: >- - filter(fn: (r) => r._measurement == - "example-measurement") + source: 'filter(fn: (r) => r._measurement == "example-measurement")' start: column: 51 line: 1 @@ -12831,10 +12295,7 @@ paths: end: column: 109 line: 1 - source: >- - from(bucket: "example-bucket") |> - range(start: -5m) |> filter(fn: (r) => - r._measurement == "example-measurement") + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' start: column: 1 line: 1 @@ -12843,10 +12304,7 @@ paths: end: column: 109 line: 1 - source: >- - from(bucket: "example-bucket") |> range(start: - -5m) |> filter(fn: (r) => r._measurement == - "example-measurement") + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' start: column: 1 line: 1 @@ -12856,10 +12314,7 @@ paths: end: column: 109 line: 1 - source: >- - from(bucket: "example-bucket") |> range(start: - -5m) |> filter(fn: (r) => r._measurement == - "example-measurement") + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' start: column: 1 line: 1 @@ -12870,20 +12325,16 @@ paths: type: Package schema: $ref: '#/components/schemas/ASTResponse' - description: > + description: | Success. - - The response body contains an Abstract Syntax Tree (AST) of the Flux - query. + 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()`, - + description: | + If the request body contains a missing property key in `from()`, returns `invalid` and problem detail. summary: Invalid AST value: @@ -12928,48 +12379,31 @@ paths: EOL /api/v2/query/suggestions: get: - description: > + description: | Retrieves a list of Flux query suggestions. Each suggestion contains a - - [Flux - function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - + [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name and parameters. - - Use this endpoint to retrieve a list of Flux query suggestions used in - the - - InfluxDB Flux Query Builder. Helper function names have an underscore - (`_`) - + Use this endpoint to retrieve a list of Flux query suggestions used in the + InfluxDB Flux Query Builder. Helper function names have an underscore (`_`) prefix and aren't meant to be used directly in queries--for example: - - **Recommended**: Use `top(n, columns=["_value"], tables=<-)` to sort on a column and keep the top n records instead of `_sortLimit_`. `top` uses the `_sortLimit` helper function. #### Limitations - - Using `/api/v2/query/suggestions/` (note the trailing slash) with cURL - will result in a HTTP `301 Moved Permanently` status code. Please use - `/api/v2/query/suggestions` without a trailing slash. - - When writing a query, avoid using `_functionName()` helper functions - exposed by this endpoint. - #### Related Guides - - - [List of all Flux - functions](/influxdb/cloud/flux/v0.x/stdlib/all-functions/). + - [List of all Flux functions](/influxdb/cloud/flux/v0.x/stdlib/all-functions/) operationId: GetQuerySuggestions parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13563,26 +12997,20 @@ paths: tables: stream schema: $ref: '#/components/schemas/FluxSuggestions' - description: > + description: | Success. - - The response body contains a list of Flux query - suggestions--function - + The response body contains a list of Flux query suggestions--function names used in the Flux Query Builder autocomplete suggestions. '301': content: text/html: examples: movedPermanently: - description: > - The URL has been permanently moved. Use - `/api/v2/query/suggestions`. + description: | + The URL has been permanently moved. Use `/api/v2/query/suggestions`. summary: Invalid URL - value: > - Moved - Permanently + value: | + Moved Permanently schema: properties: body: @@ -13605,45 +13033,30 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "https://cloud2.influxdata.com/api/v2/query/suggestions" \ + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/query/suggestions" \ --header "Accept: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" /api/v2/query/suggestions/{name}: get: - description: > - Retrieves a query suggestion that contains the name and parameters of - the - + description: | + Retrieves a query suggestion that contains the name and parameters of the requested function. - - Use this endpoint to pass a branching suggestion (a Flux function name) - and - + Use this endpoint to pass a branching suggestion (a Flux function name) and retrieve the parameters of the requested function. - #### Limitations - - Use `/api/v2/query/suggestions/{name}` (without a trailing slash). - - `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in - a - + `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a HTTP `301 Moved Permanently` status. - - The function `name` must exist and must be spelled correctly. - #### Related Guides - - - [List of all Flux - functions](/influxdb/cloud/flux/v0.x/stdlib/all-functions/). + - [List of all Flux functions](/influxdb/cloud/flux/v0.x/stdlib/all-functions/) operationId: GetQuerySuggestionsName parameters: - $ref: '#/components/parameters/TraceSpan' @@ -13693,9 +13106,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "https://cloud2.influxdata.com/api/v2/query/suggestions/sum/" \ + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/query/suggestions/sum/" \ --header "Accept: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" /api/v2/resources: @@ -13724,37 +13136,30 @@ paths: - System information endpoints /api/v2/scripts: get: - description: > - Retrieves a list of - [scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). - + description: | + Retrieves a list of [scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). #### Limitations - - - Paging with an `offset` greater than the number of records will result - in - + - Paging with an `offset` greater than the number of records will result in an empty response--for example: - The following request is paging to the 50th record, but the user has only + The following sample request pages to the 50th record, but the user has only created two scripts. - ```sh - $ curl --request GET "INFLUX_URL/api/v2/scripts?limit=1&offset=50" + ```sh + $ curl --request GET "INFLUX_URL/api/v2/scripts?limit=1&offset=50" - $ {"scripts":[]} - ``` + $ {"scripts":[]} + ``` - #### Related Guides + #### Related guides - - - [Invoke custom - scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) operationId: GetScripts parameters: - description: | - Limits the number of scripts returned. Default is `100`. + The maximum number of scripts to return. Default is `100`. in: query name: limit required: false @@ -13765,7 +13170,7 @@ paths: type: integer - description: | The offset for pagination. - The number of records to skip. + Skips the specified number of records in the result. in: query name: offset required: false @@ -13773,19 +13178,17 @@ paths: default: 0 minimum: 0 type: integer - - description: The name of the script. + - description: The script name. Lists scripts with the specified name. in: query name: name required: false schema: type: string - - description: > + - description: | A list of label names. - - Only returns scripts that have all these labels. - - To retrieve a script, each name you pass in `labelNames` must - exactly match the label for a script. + Only returns scripts that have all the specified labels. + To retrieve a script, each name you pass in `labelNames` must exactly + match the label for a script. in: query name: labelNames required: false @@ -13795,7 +13198,7 @@ paths: type: array - description: | A part of the label name. - Returns scripts that have a label that contains this phrase. + Returns scripts that have a label that contains the specified phrase. in: query name: labelContains required: false @@ -13815,9 +13218,7 @@ paths: language: flux name: getLastPointFromSampleBucket orgID: bea7ea952287f70d - script: >- - from(bucket: SampleBucket) |> range(start: -7d) |> - limit(n:1) + script: 'from(bucket: SampleBucket) |> range(start: -7d) |> limit(n:1)' updatedAt: '2022-07-17T23:49:45.731237Z' - createdAt: '2022-07-17T23:43:26.660308Z' description: getLastPoint finds the last point in a bucket @@ -13825,9 +13226,7 @@ paths: language: flux name: getLastPoint orgID: bea7ea952287f70d - script: >- - from(bucket: params.mybucket) |> range(start: -7d) |> - limit(n:1) + script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' updatedAt: '2022-07-17T23:43:26.660308Z' schema: $ref: '#/components/schemas/Scripts' @@ -13843,13 +13242,13 @@ paths: value: code: 3 details: [] - message: >- - parsing field "limit": strconv.ParseUint: parsing "-1": - invalid syntax + message: 'parsing field "limit": strconv.ParseUint: parsing "-1": invalid syntax' schema: $ref: '#/components/schemas/Error' description: | Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the error. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -13867,27 +13266,20 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "https://cloud2.influxdata.com/api/v2/scripts?limit=100&offset=0" \ + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/scripts?limit=100&offset=0" \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" post: - description: > - Creates an [invokable - script](https://docs.influxdata.com/resources/videos/api-invokable-scripts/) + description: | + Creates an [invokable script](https://docs.influxdata.com/resources/videos/api-invokable-scripts/) + and returns the script. - and returns the created script. + #### Related guides - - #### Related Guides - - - - [Invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). - - - [Creating custom InfluxDB - endpoints](https://docs.influxdata.com/resources/videos/api-invokable-scripts/). + - [Invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + - [Creating custom InfluxDB endpoints](https://docs.influxdata.com/resources/videos/api-invokable-scripts/) operationId: PostScripts requestBody: content: @@ -13909,9 +13301,7 @@ paths: language: flux name: getLastPoint orgID: bea7ea952287f70d - script: >- - from(bucket: params.mybucket) |> range(start: -7d) |> - limit(n:1) + script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' updatedAt: '2022-07-17T23:43:26.660308Z' schema: $ref: '#/components/schemas/Script' @@ -13919,32 +13309,7 @@ paths: Success. The response body contains the script and its metadata. '400': - content: - application/json: - examples: - invalidCharacterValue: - description: | - If the request body contains an invalid character, returns - `invalid` with detail about the problem. - summary: Invalid character - value: - code: invalid - details: [] - message: invalid character ',' looking for beginning of value - invalidJSONStringValue: - description: | - If the request body contains invalid JSON, returns `invalid` - with detail about the problem. - summary: Invalid JSON - value: - code: invalid - message: >- - invalid json: invalid character '\'' looking for beginning - of value - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. + $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '422': @@ -13989,10 +13354,12 @@ paths: }' /api/v2/scripts/{scriptID}: delete: - description: Deletes a script and all associated records. + description: Deletes a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records. operationId: DeleteScriptsID parameters: - - description: The ID of the script to delete. + - description: | + A script ID. + Deletes the specified script. in: path name: scriptID required: true @@ -14000,7 +13367,11 @@ paths: type: string responses: '204': - description: The script is deleted. + description: Success. The script is deleted. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/ServerError' description: Unexpected error @@ -14008,10 +13379,13 @@ paths: tags: - Invokable Scripts get: - description: Uses script ID to retrieve details of an invokable script. + description: | + Retrieves a [script](/influxdb/cloud/api-guide/api-invokable-scripts/). operationId: GetScriptsID parameters: - - description: The script ID. + - description: | + A script ID. + Retrieves the specified script. in: path name: scriptID required: true @@ -14023,21 +13397,28 @@ paths: application/json: schema: $ref: '#/components/schemas/Script' - description: The requested script object. + description: Success. The response body contains the script. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/ServerError' - description: Unexpected error + description: Unexpected error. summary: Retrieve a script tags: - Data I/O endpoints - Invokable Scripts patch: - description: > - Updates properties (`name`, `description`, and `script`) of an invokable - script. + description: | + Updates a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and returns the script. + + Use this endpoint to update the properties (`name`, `description`, and `script`) of an invokable script. operationId: PatchScriptsID parameters: - - description: The script ID. + - description: | + A script ID. + Updates the specified script. in: path name: scriptID required: true @@ -14048,7 +13429,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ScriptUpdateRequest' - description: Script update to apply + description: The script update to apply. required: true responses: '200': @@ -14056,7 +13437,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Script' - description: The updated script. + description: Success. The response body contains the updated script. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/ServerError' description: Unexpected error @@ -14065,49 +13452,38 @@ paths: - Invokable Scripts /api/v2/scripts/{scriptID}/invoke: post: - description: > - Invokes a script and substitutes `params` keys referenced in the script - with - - `params` key-values sent in the request body--for example: - - - The following script contains the parameter _`mybucket`_: + description: | + Runs a script and returns the result. + When the script runs, InfluxDB replaces `params` keys referenced in the script with + `params` key-values passed in the request body--for example: + The following sample script contains a _`mybucket`_ parameter : ```json - "script": "from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)" ``` - The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request - body - - passes a value for _`mybucket`_: - + The following example `POST /api/v2/scripts/SCRIPT_ID/invoke` request body + passes a value for the _`mybucket`_ parameter: ```json - { "params": { "mybucket": "air_sensor" } } - ``` + #### Related guides - #### Related Guides - - - [Invoke custom - scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) operationId: PostScriptsIDInvoke parameters: - description: | - Script ID. - Only returns scripts with this ID. + A script ID. + Runs the specified script. in: path name: scriptID required: true @@ -14124,9 +13500,8 @@ paths: text/csv: examples: successResponse: - value: > + value: | ,result,table,_start,_stop,_time,_value,_field,_measurement,host - ,_result,0,2019-10-30T01:28:02.52716421Z,2022-07-26T01:28:02.52716421Z,2020-01-01T00:00:00Z,72.01,used_percent,mem,host2 schema: $ref: '#/components/schemas/ScriptHTTPResponseData' @@ -14146,6 +13521,8 @@ paths: $ref: '#/components/schemas/Error' description: | Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the error. headers: X-Platform-Error-Code: description: | @@ -14160,16 +13537,16 @@ paths: application/json: examples: bucketNotFound: + description: InfluxDB can't find the requested bucket. summary: | - The requested bucket was not found. + Bucket not found value: code: not found - message: >- - failed to initialize execute state: could not find bucket - "test-bucket" + message: 'failed to initialize execute state: could not find bucket "test-bucket"' scriptNotFound: + description: InfluxDB can't find the requested script. summary: | - The requested script was not found. + Script not found value: code: not found message: script "09afa3b220fe400" not found @@ -14199,9 +13576,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/invoke" \ + source: | + curl --request POST "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/invoke" \ --header "Authorization: Token INFLUX_TOKEN" \ --header 'Accept: application/csv' \ --header 'Content-Type: application/json' \ @@ -14212,10 +13588,14 @@ paths: }' /api/v2/scripts/{scriptID}/labels/add: patch: - description: Adds labels to a script and returns the updated script. + description: | + Adds labels to a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) + and returns the script. operationId: PatchScriptsIDAddLabels parameters: - - description: The script ID. + - description: | + The script ID. + Adds labels to the specified script. in: path name: scriptID required: true @@ -14236,7 +13616,7 @@ paths: type: string type: array type: object - description: The names of labels to add to the script. + description: The labels to add to the script. required: true responses: '200': @@ -14248,8 +13628,7 @@ paths: Success. The response body contains the updated script. '400': - $ref: '#/components/responses/ServerError' - description: Bad request. + $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -14260,16 +13639,17 @@ paths: default: $ref: '#/components/responses/ServerError' description: Unexpected error. - summary: Adds labels to a script + summary: Add labels to a script tags: - - Data I/O endpoints - Invokable Scripts /api/v2/scripts/{scriptID}/labels/remove: patch: - description: Removes labels from a script and returns the updated script. + description: Removes labels from a script and returns the script. operationId: PatchScriptsIDRemoveLabels parameters: - - description: The script ID. + - description: | + A script ID. + Removes labels from the specified script. in: path name: scriptID required: true @@ -14290,7 +13670,7 @@ paths: type: string type: array type: object - description: The names of labels to remove from the script. + description: The labels to remove from the script. required: true responses: '200': @@ -14302,8 +13682,7 @@ paths: Success. The response body contains the updated script. '400': - $ref: '#/components/responses/ServerError' - description: Bad request. + $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -14314,15 +13693,12 @@ paths: default: $ref: '#/components/responses/ServerError' description: Unexpected error. - summary: Removes labels from a script + summary: Remove labels from a script tags: - - Data I/O endpoints - Invokable Scripts /api/v2/setup: get: - description: >- - Check if setup is allowed. Returns `true` if no default user, - organization, or bucket have been created. + description: Check if setup is allowed. Returns `true` if no default user, organization, or bucket have been created. operationId: GetSetup parameters: - $ref: '#/components/parameters/TraceSpan' @@ -14337,9 +13713,7 @@ paths: tags: - Setup post: - description: >- - Post an onboarding request to create an initial user, organization, and - bucket. + description: Post an onboarding request to create an initial user, organization, and bucket. operationId: PostSetup parameters: - $ref: '#/components/parameters/TraceSpan' @@ -14365,9 +13739,7 @@ paths: - Setup /api/v2/setup/user: post: - description: >- - Post an onboarding request to create a new user, organization, and - bucket. + description: Post an onboarding request to create a new user, organization, and bucket. operationId: PostSetupUser requestBody: content: @@ -14391,27 +13763,67 @@ paths: - Setup /api/v2/signin: post: - description: >- - Authenticates ***Basic Auth*** credentials for a user. If successful, - creates a new UI session for the user. + description: | + Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) + for a [user](/influxdb/cloud/reference/glossary/#user), + and then, if successful, generates a user session. + + To authenticate a user, pass the HTTP `Authorization` header with the + `Basic` scheme and the base64-encoded username and password--for example: + + ```sh + Authorization: Basic USERNAME:PASSWORD + ``` + + In InfluxDB Cloud, the username is the email address the user signed up with. + + _Note that many HTTP clients provide a Basic authentication option that + accepts the `USERNAME:PASSWORD` syntax and encodes the credentials before + sending the request. + To learn more about HTTP authentication, see + [Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._ + + If authentication is successful, InfluxDB creates a new session for the user + and then returns the session cookie in the `Set-Cookie` response header. + User sessions exist only in memory. + They expire within ten minutes and during restarts of the InfluxDB instance. + + #### User sessions with authorizations + + - In InfluxDB Cloud, a user session inherits all the user's permissions for + the organization. + - In InfluxDB OSS, a user session inherits all the user's permissions for all + the organizations that the user belongs to. + + #### Related endpoints + + - [Signout](#tag/Signout) operationId: PostSignin parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': - description: Success. User authenticated. + description: | + Success. + The user is authenticated. + The `Set-Cookie` response header contains the session cookie. '401': content: application/json: schema: $ref: '#/components/schemas/Error' - description: Unauthorized access. + description: | + Unauthorized. + This error may be caused by one of the following problems: + - The user doesn't have access. + - The user passed incorrect credentials in the request. + - The credentials are formatted incorrectly in the request. '403': content: application/json: schema: $ref: '#/components/schemas/Error' - description: User account is disabled. + description: Forbidden. The user account is disabled. default: content: application/json: @@ -14423,6 +13835,12 @@ paths: summary: Create a user session. tags: - Signin + x-codeSamples: + - label: 'cURL: signin with --user option encoding' + lang: Shell + source: | + curl --request POST http://localhost:8086/api/v2/signin \ + --user "USERNAME:PASSWORD" /api/v2/signout: post: description: Expires the current UI session for the user. @@ -14470,21 +13888,15 @@ paths: required: true schema: type: string - - description: > + - description: | The stack name. - Finds stack `events` with this name and returns the stacks. - Repeatable. - To filter for more than one stack name, - repeat this parameter with each name--for example: - - - - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` + - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` examples: findStackByName: summary: Find stacks with the event name @@ -14493,21 +13905,15 @@ paths: name: name schema: type: string - - description: > + - description: | The stack ID. - Only returns stacks with this ID. - Repeatable. - To filter for more than one stack ID, - repeat this parameter with each ID--for example: - - - - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` + - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` examples: findStackByID: summary: Find a stack with the ID @@ -14536,29 +13942,21 @@ paths: summary: The orgID query parameter is missing value: code: invalid - message: >- - organization id[""] is invalid: id must have a length of - 16 bytes + message: 'organization id[""] is invalid: id must have a length of 16 bytes' orgProvidedNotFound: - summary: >- - The org or orgID passed doesn't own the token passed in the - header + 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 an incorrect value is passed for `org` or - `orgID`. + - Returns this error if an incorrect value is passed for `org` or `orgID`. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -14573,13 +13971,10 @@ paths: tags: - Templates post: - description: > + description: | Creates or initializes a stack. - - Use this endpoint to _manually_ initialize a new stack with the - following - + Use this endpoint to _manually_ initialize a new stack with the following optional information: - Stack name @@ -14587,23 +13982,16 @@ paths: - URLs for template manifest files To automatically create a stack when applying templates, - use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). - #### Required permissions - - `write` permission for the organization - #### Related guides - - [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/) - - - [Use InfluxDB - templates](/influxdb/cloud/influxdb-templates/use/#apply-templates-to-an-influxdb-instance) + - [Use InfluxDB templates](/influxdb/cloud/influxdb-templates/use/#apply-templates-to-an-influxdb-instance) operationId: CreateStack requestBody: content: @@ -14638,16 +14026,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -14800,73 +14184,67 @@ paths: - Templates /api/v2/tasks: get: - description: > - Retrieves a list of [tasks](/influxdb/cloud/process-data/). + description: | + Retrieves a list of [tasks](/influxdb/cloud/reference/glossary/#task). - - To limit which tasks are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all tasks up to the - default `limit`. + 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: | - Task name. - Only returns tasks with this name. + A [task](/influxdb/cloud/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. in: query name: name schema: type: string - description: | - Task ID. - Only returns tasks created after this task. + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Only returns tasks created after the specified task. in: query name: after schema: type: string - description: | - User ID. - Only returns tasks owned by this user. + A [user](/influxdb/cloud/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. in: query name: user schema: type: string - description: | - Organization name. - Only returns tasks owned by this organization. + An [organization](/influxdb/cloud/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. in: query name: org schema: type: string - description: | - Organization ID. - Only returns tasks owned by this organization. + An [organization](/influxdb/cloud/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. in: query name: orgID schema: type: string - - in: query + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). + in: query name: status schema: - description: | - Task status (`active` or `inactive`). - Only returns tasks with this status. enum: - active - inactive type: string - - description: > - Limits the number of tasks returned. Default is `100`. + - description: | + The maximum number of [tasks](/influxdb/cloud/reference/glossary/#task) to return. + Default is `100`. + The minimum is `1` and the maximum is `500`. - - To reduce the payload size, combine _`type=basic`_ and _`limit`_ - (see _Request samples_) - - For more information about the `basic` response, see the _`type`_ - parameter. + 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. @@ -14890,8 +14268,8 @@ paths: minimum: 0 type: integer - description: | - The field used for sorting records in the list. - Only `name` is supported. + The sort field. Only `name` is supported. + Specifies the field used to sort records in the list. in: query name: sortBy required: false @@ -14899,15 +14277,12 @@ paths: enum: - name type: string - - 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. + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) type (`basic` or `system`). + Default is `system`. + Specifies the level of detail for tasks in the response. + The default (`system`) response contains all the metadata properties for tasks. + To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). in: query name: type required: false @@ -14918,8 +14293,8 @@ paths: - system type: string - description: | - Script ID. - Only returns tasks that use this script. + A [script](#tag/Invokable-Scripts) ID. + Only returns tasks that use the specified invokable script. in: query name: scriptID schema: @@ -14928,6 +14303,71 @@ paths: '200': content: application/json: + examples: + basicTypeTaskOutput: + description: | + A sample response body for the `?type=basic` parameter. + `type=basic` omits some task fields (`createdAt` and `updatedAt`) + and field values (`org`, `flux`) in the response. + 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: | + A sample response body for the `?type=system` parameter. + `type=system` returns all task fields. + 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: | @@ -14946,78 +14386,67 @@ paths: x-codeSamples: - label: 'cURL: all tasks, basic output' lang: Shell - source: > - curl https://cloud2.influxdata.com/api/v2/tasks/?limit=-1&type=basic - \ + 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. - + description: | + Creates a [task](/influxdb/cloud/reference/glossary/#task) and returns the task. Use this endpoint to create a scheduled task that runs a Flux script. - #### InfluxDB Cloud - - You can use either `flux` or `scriptID` to provide the task script. - `flux`: a string of "raw" Flux that contains task options and the script--for example: - ```json - { - "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ - from(bucket: \"telegraf\") - |> range(start: -1h) - |> filter(fn: (r) => (r._measurement == \"cpu\")) - |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) - |> filter(fn: (r) => (r.cpu == \"cpu-total\")) - |> aggregateWindow(every: 1h, fn: max) - |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", - "status": "active", - "description": "This task downsamples CPU data every hour" - } - ``` + ```json + { + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + from(bucket: \"telegraf\") + |> range(start: -1h) + |> filter(fn: (r) => (r._measurement == \"cpu\")) + |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + |> aggregateWindow(every: 1h, fn: max) + |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + "status": "active", + "description": "This task downsamples CPU data every hour" + } + ``` - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body--for example: - ```json - { - "name": "CPU Total 1 Hour New", - "description": "This task downsamples CPU data every hour", - "every": "1h", - "scriptID": "SCRIPT_ID", - "scriptParameters": - { - "rangeStart": "-1h", - "bucket": "telegraf", - "filterField": "cpu-total" - } + ```json + { + "name": "CPU Total 1 Hour New", + "description": "This task downsamples CPU data every hour", + "every": "1h", + "scriptID": "SCRIPT_ID", + "scriptParameters": + { + "rangeStart": "-1h", + "bucket": "telegraf", + "filterField": "cpu-total" } - ``` + } + ``` #### Limitations: - - You can't use `flux` and `scriptID` for the same task. + - You can't use `flux` and `scriptID` for the same task. #### Related guides - - [Get started with tasks](/influxdb/cloud/process-data/get-started/) - - - [Create a - task](/influxdb/cloud/process-data/manage-tasks/create-task/) - + - [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/) + - [Task configuration options](/influxdb/cloud/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15034,9 +14463,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: >- - Success. The response body contains a `tasks` list with the new - task. + description: Success. The response body contains a `tasks` list with the new task. '400': content: application/json: @@ -15045,13 +14472,9 @@ paths: 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 + message: 'failed to decode request: can not provide both scriptID and flux' missingFluxError: - summary: >- - The request body requires either a flux parameter or - scriptID parameter + summary: The request body requires either a flux parameter or scriptID parameter value: code: invalid message: 'failed to decode request: flux required' @@ -15063,8 +14486,8 @@ paths: #### 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`_. + - 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': @@ -15119,23 +14542,17 @@ paths: EOF /api/v2/tasks/{taskID}: delete: - description: > - Deletes a task and associated records. + description: | + Deletes a [task](/influxdb/cloud/reference/glossary/#task) and associated records. + Use this endpoint to delete a task and all associated records (task runs, logs, and labels). + Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - 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). + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). operationId: DeleteTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to delete. + - description: A [task](/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to delete. in: path name: taskID required: true @@ -15143,7 +14560,7 @@ paths: type: string responses: '204': - description: Success. The task and runs are deleted. Scheduled runs are canceled. + description: Success. The task and task runs are deleted. Scheduled runs are canceled. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -15163,7 +14580,9 @@ paths: operationId: GetTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retrieve. + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to retrieve. in: path name: taskID required: true @@ -15191,76 +14610,67 @@ paths: - Data I/O endpoints - Tasks patch: - description: > - Updates a task and then cancels all scheduled runs of the task. + description: | + Updates a [task](/influxdb/cloud/reference/glossary/#task), + and then cancels all scheduled runs of the task. + Use this endpoint to set, modify, or clear task properties--for example: `cron`, `name`, `flux`, `status`. + Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - Use this endpoint to set, modify, and clear task properties (for - example: `cron`, `name`, `flux`, `status`). - - Once InfluxDB applies the update, it cancels all previously scheduled - runs of the task. - - - To update a task, pass an object that contains the updated key-value - pairs. - + 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. - + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. #### InfluxDB Cloud - - - You can use either `flux` or `scriptID` to provide the task script. + - Use either `flux` or `scriptID` to provide the task script. - `flux`: a string of "raw" Flux that contains task options and the script--for example: - ```json - { - "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ - from(bucket: \"telegraf\") - |> range(start: -1h) - |> filter(fn: (r) => (r._measurement == \"cpu\")) - |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) - |> filter(fn: (r) => (r.cpu == \"cpu-total\")) - |> aggregateWindow(every: 1h, fn: max) - |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", - "status": "active", - "description": "This task downsamples CPU data every hour" - } - ``` + ```json + { + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + from(bucket: \"telegraf\") + |> range(start: -1h) + |> filter(fn: (r) => (r._measurement == \"cpu\")) + |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + |> aggregateWindow(every: 1h, fn: max) + |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + "status": "active", + "description": "This task downsamples CPU data every hour" + } + ``` - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) for the task to run. To pass task options when using `scriptID`, pass the options as properties in the request body--for example: - ```json - { - "name": "CPU Total 1 Hour New", - "description": "This task downsamples CPU data every hour", - "every": "1h", - "scriptID": "SCRIPT_ID", - "scriptParameters": - { - "rangeStart": "-1h", - "bucket": "telegraf", - "filterField": "cpu-total" - } + ```json + { + "name": "CPU Total 1 Hour New", + "description": "This task downsamples CPU data every hour", + "every": "1h", + "scriptID": "SCRIPT_ID", + "scriptParameters": + { + "rangeStart": "-1h", + "bucket": "telegraf", + "filterField": "cpu-total" } - ``` + } + ``` #### Limitations: - - You can't use `flux` and `scriptID` for the same task. operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to update. + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to update. in: path name: taskID required: true @@ -15271,7 +14681,7 @@ paths: application/json: schema: $ref: '#/components/schemas/TaskUpdateRequest' - description: An object that contains updated task properties to apply. + description: An task update to apply. required: true responses: '200': @@ -15314,9 +14724,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelsResponse' - description: >- - Success. The response body contains a list of all labels for the - task. + description: Success. The response body contains a list of all labels for the task. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -15331,12 +14739,10 @@ paths: tags: - Tasks post: - description: > + 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. + 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' @@ -15359,9 +14765,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: >- - Success. The response body contains a list of all labels for the - task. + description: Success. The response body contains a list of all labels for the task. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -15412,20 +14816,13 @@ paths: - 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. + 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: @@ -15445,32 +14842,20 @@ paths: summary: Events for a failed task run. value: events: - - message: >- - Started task from script: "option task = {name: \"test - task\", every: 3d, offset: 0s}" + - 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 + - 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 a successful task run. 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)" + - 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) @@ -15478,14 +14863,10 @@ paths: time: '2022-07-18T14:46:07.242859Z' schema: $ref: '#/components/schemas/Logs' - description: > - Success. The response body contains an `events` list with logs for - the 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. + If a task run fails, InfluxDB logs an event with the reason for the failure. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -15502,11 +14883,9 @@ paths: /api/v2/tasks/{taskID}/members: get: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15536,17 +14915,11 @@ paths: - Tasks post: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. - - - Adds a user to members of a task and returns the newly created member - with - - role and user detail. + Adds a user to members of a task and returns the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15582,11 +14955,9 @@ paths: /api/v2/tasks/{taskID}/members/{userID}: delete: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15617,12 +14988,9 @@ paths: /api/v2/tasks/{taskID}/owners: get: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. - + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. Retrieves all users that have owner permission for a task. operationId: GetTasksIDOwners @@ -15640,15 +15008,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceOwners' - description: > + description: | Success. + The response contains a list of `users` that have the `owner` role for the task. - The response contains a list of `users` that have the `owner` role - for the task. - - - If the task has no owners, the response contains an empty `users` - array. + If the task has no owners, the response contains an empty `users` array. '401': $ref: '#/components/responses/AuthorizationError' '422': @@ -15656,16 +15020,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -15680,18 +15040,13 @@ paths: - Tasks post: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. - + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. Assigns a task `owner` role to a user. - Use this endpoint to create a _resource owner_ for the task. - A _resource owner_ is a user with `role: owner` for a specific resource. operationId: PostTasksIDOwners parameters: @@ -15737,16 +15092,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -15762,11 +15113,9 @@ paths: /api/v2/tasks/{taskID}/owners/{userID}: delete: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15796,15 +15145,11 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs: get: - description: > + description: | Retrieves a list of runs for a [task](/influxdb/cloud/process-data/). - - To limit which task runs are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all task runs up to - the default `limit`. + To limit which task runs are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. operationId: GetTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15830,20 +15175,16 @@ paths: maximum: 500 minimum: 1 type: integer - - description: > - A timestamp ([RFC3339 date/time - format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - + - description: | + A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after this time. in: query name: afterTime schema: format: date-time type: string - - description: > - A timestamp ([RFC3339 date/time - format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - + - description: | + A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before this time. in: query name: beforeTime @@ -15867,22 +15208,15 @@ paths: tags: - Tasks post: - description: > + description: | Schedules a task run to start immediately, ignoring scheduled runs. - Use this endpoint to manually start a task run. - Scheduled runs will continue to run as scheduled. - This may result in concurrently running tasks. - To _retry_ a previous run (and avoid creating a new run), - - use the [`POST - /api/v2/tasks/{taskID}/runs/{runID}/retry`](#operation/PostTasksIDRunsIDRetry) - endpoint. + use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). operationId: PostTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15976,10 +15310,8 @@ paths: tags: - Tasks get: - description: > - Retrieves a specific run for a - [task](/influxdb/cloud/reference/glossary/#task). - + 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 @@ -16008,19 +15340,12 @@ paths: 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 + 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)" + - 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) @@ -16049,15 +15374,11 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/logs: get: - description: > + description: | Retrieves all logs for a task run. + A log is a list of run events with `runID`, `time`, and `message` properties. - A log is a list of run events with `runID`, `time`, and `message` - properties. - - - Use this endpoint to help analyze task performance and troubleshoot - failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16082,32 +15403,20 @@ paths: summary: Events for a failed task. value: events: - - message: >- - Started task from script: "option task = {name: \"test - task\", every: 3d, offset: 0s}" + - 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 + - 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 a successful task run. 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)" + - 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) @@ -16115,14 +15424,10 @@ paths: time: '2022-07-18T14:46:07.242859Z' schema: $ref: '#/components/schemas/Logs' - description: > - Success. The response body contains an `events` list with logs for - the task run. - + description: | + Success. The response body contains an `events` list with logs for the task run. Each log event `message` contains detail about the event. - - If a run fails, InfluxDB logs an event with the reason for the - failure. + If a run fails, InfluxDB logs an event with the reason for the failure. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -16138,28 +15443,34 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/retry: post: - description: > - Queues a task run to retry and returns the newly scheduled run. - - - To manually start a _new_ task run, use the [`POST - /api/v2/tasks/{taskID}/runs`](#operation/PostTasksIDRuns) endpoint. + description: | + Queues a [task](/influxdb/cloud/reference/glossary/#task) run to + retry and returns the scheduled run. + To manually start a _new_ task run, use the + [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). operationId: PostTasksIDRunsIDRetry parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retry. + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to retry. in: path name: taskID required: true schema: type: string - - description: The ID of the task run to retry. + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) run ID. + Specifies the task run to retry. + + To find a task run ID, use the + [`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns) + to list task runs. in: path name: runID required: true @@ -16180,10 +15491,8 @@ paths: value: id: 09d60ffe08738000 links: - logs: >- - /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs - retry: >- - /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry + logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs + retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 task: /api/v2/tasks/09a776832f381000 requestedAt: '2022-08-16T20:05:11.84145Z' @@ -16639,9 +15948,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceOwner' - description: >- - Telegraf configuration owner was added. Returns a ResourceOwner that - references the User. + description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. default: content: application/json: @@ -16682,44 +15989,26 @@ paths: - Telegrafs /api/v2/templates/apply: post: - description: > + description: | Applies a template to - - create or update a [stack](/influxdb/cloud/influxdb-templates/stacks/) - of InfluxDB - + create or update a [stack](/influxdb/cloud/influxdb-templates/stacks/) of InfluxDB [resources](/influxdb/cloud/reference/cli/influx/export/all/#resources). - The response contains the diff of changes and the stack ID. - Use this endpoint to install an InfluxDB template to an organization. - Provide template URLs or template objects in your request. - To customize which template resources are installed, use the `actions` - parameter. - By default, when you apply a template, InfluxDB installs the template to - - create and update stack resources and then generates a diff of the - changes. - + create and update stack resources and then generates a diff of the changes. If you pass `dryRun: true` in the request body, InfluxDB validates the - template and generates the resource diff, but doesn’t make any - changes to your instance. - #### Custom values for templates - - - Some templates may contain [environment - references](/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names) - for custom metadata. + - Some templates may contain [environment references](/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. To provide custom values for environment references, pass the _`envRefs`_ property in the request body. For more information and examples, see how to @@ -16734,21 +16023,16 @@ paths: #### Required permissions - - `write` permissions for resource types in the template. - #### Rate limits (with InfluxDB Cloud) - - Adjustable service quotas apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - [Use templates](/influxdb/cloud/influxdb-templates/use/) - - [Stacks](/influxdb/cloud/influxdb-templates/stacks/) operationId: ApplyTemplate requestBody: @@ -16848,16 +16132,11 @@ paths: application/json: schema: $ref: '#/components/schemas/TemplateSummary' - description: > + description: | Success. - The template applied successfully. - The response body contains the stack ID, a diff, and a summary. - - The diff compares the initial state to the state after the template - installation. - + The diff compares the initial state to the state after the template installation. The summary contains newly created resources. '422': content: @@ -17027,9 +16306,7 @@ paths: application/x-yaml: schema: $ref: '#/components/schemas/Template' - description: >- - The template was created successfully. Returns the newly created - template. + description: The template was created successfully. Returns the newly created template. default: content: application/json: @@ -17042,17 +16319,82 @@ paths: /api/v2/users: get: description: | - Retrieves a list of users. + Retrieves a list of [users](/influxdb/cloud/reference/glossary/#user). + + To limit which users are returned, pass query parameters in your request. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't allow listing all users through the API. + Use the InfluxDB Cloud user interface (UI) to manage account information. + + #### Required permissions for InfluxDB Cloud + + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | List all users | Operator token | InfluxData internal use only | + | List a specific user | `read-users` or `read-user USER_ID` | + + Replace the following: + + - `USER_ID`: ID of the user that you want to retrieve. + + #### Related guides + + - [Manage users](/influxdb/cloud/organizations/users/) operationId: GetUsers parameters: - $ref: '#/components/parameters/TraceSpan' + - description: | + A user name. + Only lists the specified [user](/influxdb/cloud/reference/glossary/#user). + in: query + name: name + schema: + type: string + - description: | + A user id. + Only lists the specified [user](/influxdb/cloud/reference/glossary/#user). + in: query + name: id + schema: + type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/Users' - description: Success. The response contains a list of `users`. + description: | + Success. The response contains a list of `users`. + + #### InfluxDB Cloud + + - Returns an empty `users` list if you don't pass _`id`_ or _`name`_ parameters and don't use an + _operator token_. + Only InfluxData can access InfluxDB Cloud operator tokens. + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Unauthorized. + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Unprocessable entity. + + The error may indicate one of the following problems: + + - The request body isn't valid--the request is well-formed, + but InfluxDB can't process it due to semantic errors. + - You passed a parameter combination that InfluxDB doesn't support. + '500': + $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -17062,7 +16404,25 @@ paths: - Users post: description: | - Creates a user and returns the newly created user. + (InfluxData internal use only) + + Creates and returns a [user](/influxdb/cloud/reference/glossary/#user) + that can access InfluxDB. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't allow managing users through the API. + Use the InfluxDB Cloud user interface (UI) to manage account information. + + #### Required permissions for InfluxDB Cloud + + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | Create user | Operator token | InfluxData internal use only | + + #### Related guides + + - [Manage users](/influxdb/cloud/organizations/users/) operationId: PostUsers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17081,7 +16441,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: | Success. - The response contains the newly created user. + The response body contains the user. '401': content: application/json: @@ -17089,21 +16449,23 @@ paths: $ref: '#/components/schemas/Error' description: | Unauthorized. + + #### InfluxDB Cloud + + - Returns this error if the request doesn't use an _operator token_. + Only InfluxData can access InfluxDB Cloud operator tokens. '422': content: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, + but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -17115,10 +16477,34 @@ paths: - Users /api/v2/users/{userID}: delete: + description: | + (InfluxData internal use only) + + Deletes a [user](/influxdb/cloud/reference/glossary/#user). + + For security purposes, once an InfluxDB user account is deleted from an + organization, the user (and their token) cannot be reactivated. + + #### InfluxDB Cloud + + - Doesn't allow managing users through the API. + Use the InfluxDB Cloud user interface (UI) to manage account information. + + #### Required permissions + + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | Delete user | Operator token | InfluxData internal use only | + + #### Related guides + + - [Manage users](/influxdb/cloud/organizations/users/) operationId: DeleteUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to delete. + - description: | + A user ID. + Deletes the specified [user](/influxdb/cloud/reference/glossary/#user). in: path name: userID required: true @@ -17126,7 +16512,7 @@ paths: type: string responses: '204': - description: User deleted + description: Success. The user is deleted. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -17134,10 +16520,18 @@ paths: tags: - Users get: + description: | + Retrieves a [user](/influxdb/cloud/reference/glossary/#user). + + #### Related guides + + - [Manage users](/influxdb/cloud/organizations/users/) operationId: GetUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The user ID. + - description: | + A user ID. + Retrieves the specified [user](/influxdb/cloud/reference/glossary/#user). in: path name: userID required: true @@ -17149,7 +16543,7 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: User details + description: Success. The response body contains the user. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -17157,10 +16551,31 @@ paths: tags: - Users patch: + description: | + (InfluxData internal use only) + + Updates a [user](/influxdb/cloud/reference/glossary/#user) and returns the user. + + #### InfluxDB Cloud + + - Doesn't allow managing users through the API. + Use the InfluxDB Cloud user interface (UI) to manage account information. + + #### Required permissions for InfluxDB Cloud + + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | Update user | Operator token | InfluxData internal use only | + + #### Related guides + + - [Manage users](/influxdb/cloud/organizations/users/) operationId: PatchUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to update. + - description: | + A user ID. + Updates the specified [user](/influxdb/cloud/reference/glossary/#user). in: path name: userID required: true @@ -17171,7 +16586,7 @@ paths: application/json: schema: $ref: '#/components/schemas/User' - description: User update to apply + description: The user update to apply. required: true responses: '200': @@ -17179,7 +16594,7 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: User updated + description: Success. The response body contains the updated user. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -17189,14 +16604,25 @@ paths: /api/v2/users/{userID}/password: post: description: | + Updates a user password. + + Use this endpoint to let a user authenticate with + [Basic authentication credentials](#section/Authentication/BasicAuthentication) + and set a new password. + #### InfluxDB Cloud - InfluxDB Cloud doesn't support changing user passwords through the API. - Use the InfluxDB Cloud user interface to update your password. + - Doesn't allow you to manage user passwords through the API. + Use the InfluxDB Cloud user interface (UI) to update a password. + + #### Related guides + + - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) operationId: PostUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The user ID. + - description: The ID of the user to set the password for. in: path name: userID required: true @@ -17207,29 +16633,52 @@ paths: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' - description: New password + description: The new password to set for the user. required: true responses: '204': - description: Password successfully updated + description: Success. The password is 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: + examples: + updatePasswordNotAllowed: + summary: Cloud API can't update passwords + value: + code: invalid + message: passwords cannot be changed through the InfluxDB Cloud API schema: $ref: '#/components/schemas/Error' - description: Unsuccessful authentication + description: | + Bad request. + + #### InfluxDB Cloud + + - Doesn't allow you to manage passwords through the API; always responds with this status. + + #### InfluxDB OSS + + - Doesn't understand a value passed in the request. + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error security: - BasicAuthentication: [] summary: Update a password tags: - Security and access endpoints - Users + x-codeSamples: + - label: 'cURL: use Basic auth to update the user password' + lang: Shell + source: | + curl --request POST \ + "http://localhost:8086/api/v2/users/USER_ID/password" \ + --header 'Content-type: application/json' \ + --user "USERNAME:PASSWORD" \ + --data-binary @- << EOF + {"password": ""} + EOF /api/v2/variables: get: operationId: GetVariables @@ -17488,18 +16937,13 @@ paths: - Variables /api/v2/write: post: - description: > + description: | Writes data to a bucket. - - Use this endpoint to send data in [line - protocol](/influxdb/cloud/reference/syntax/line-protocol/) format to - InfluxDB. - + Use this endpoint to send data in [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud - - Takes the following steps when you send a write request: 1. Validates the request and queues the write. @@ -17515,40 +16959,27 @@ paths: #### InfluxDB OSS - - Validates the request, handles the write synchronously, and then responds with success or failure. - - If all points were written successfully, responds with HTTP `204` - status code; + - If all points were written successfully, responds with HTTP `204` status code; otherwise, returns the first line that failed. #### Required permissions - - `write-buckets` or `write-bucket BUCKET_ID`. `BUCKET_ID` is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) - `write` rate limits apply. - - For more information, see [limits and adjustable - quotas](/influxdb/cloud/account-management/limits/). - + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - - [Write data with the InfluxDB - API](/influxdb/cloud/write-data/developer-tools/api). - - - [Optimize writes to - InfluxDB](/influxdb/cloud/write-data/best-practices/optimize-writes/). - - - [Troubleshoot issues writing - data](/influxdb/cloud/write-data/troubleshoot/) + - [Write data with the InfluxDB API](/influxdb/cloud/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](/influxdb/cloud/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](/influxdb/cloud/write-data/troubleshoot/) operationId: PostWrite parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17559,27 +16990,22 @@ paths: name: Content-Encoding schema: default: identity - description: > + description: | Content coding. - - Use `gzip` for compressed data or `identity` for unmodified, - uncompressed data. + Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity type: string - - description: > + - description: | The format of the data in the request body. - - To send a line protocol payload, pass `Content-Type: text/plain; - charset=utf-8`. + To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`. in: header name: Content-Type schema: default: text/plain; charset=utf-8 - description: > - `text/plain` is the content type for line protocol. `UTF-8` is the - default character set. + description: | + `text/plain` is the content type for line protocol. `UTF-8` is the default character set. enum: - text/plain - text/plain; charset=utf-8 @@ -17608,7 +17034,8 @@ paths: - Returns only `application/json` for format and limit errors. #### Related guides - - [Troubleshoot issues writing data](/influxdb/cloud/write-data/troubleshoot/). + + - [Troubleshoot issues writing data](/influxdb/cloud/write-data/troubleshoot/) in: header name: Accept schema: @@ -17617,28 +17044,19 @@ paths: enum: - application/json type: string - - description: > + - description: | The destination organization for writes. - InfluxDB writes all points in the batch to this organization. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Writes to the bucket in the organization associated with the - authorization (API token). - + - Writes to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. - - InfluxDB writes all points in the batch to this organization. in: query name: org @@ -17646,27 +17064,19 @@ paths: schema: description: The organization name or ID. type: string - - description: > + - description: | The ID of the destination organization for writes. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Writes to the bucket in the organization associated with the - authorization (API token). - + - Writes to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. - - InfluxDB writes all points in the batch to this organization. in: query name: orgID @@ -17691,21 +17101,15 @@ paths: text/plain: examples: plain-utf8: - value: > - airSensors,sensor_id=TLM0201 - temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 - 1630424257000000000 - - airSensors,sensor_id=TLM0202 - temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 - 1630424257000000000 + value: | + airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 + airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000 schema: format: byte type: string - description: > + description: | Data in line protocol format. - To send compressed data, do the following: 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. @@ -17714,52 +17118,34 @@ paths: #### Related guides - - - [Best practices for optimizing - writes](/influxdb/cloud/write-data/best-practices/optimize-writes/). + - [Best practices for optimizing writes](/influxdb/cloud/write-data/best-practices/optimize-writes/) required: true responses: '204': - description: > + description: | Success. - #### InfluxDB Cloud - - Validated and queued the request. - - - Handles the write asynchronously - the write might not have - completed yet. - + - Handles the write asynchronously - the write might not have completed yet. #### InfluxDB OSS - - Successfully wrote all points in the batch. - #### Related guides - - - [How to check for write - errors](/influxdb/cloud/write-data/troubleshoot/). + - [How to check for write errors](/influxdb/cloud/write-data/troubleshoot/) '400': content: application/json: examples: measurementSchemaFieldTypeConflict: - summary: >- - (Cloud) field type conflict thrown by an explicit bucket - schema + summary: (Cloud) field type conflict thrown by an explicit bucket schema value: code: invalid - message: >- - partial write error (2 written): unable to parse - 'air_sensor,service=S1,sensor=L1 - temperature="90.5",humidity=70.0 1632850122': schema: - field type for field "temperature" not permitted by - schema; got String but expected Float + message: 'partial write error (2 written): unable to parse ''air_sensor,service=S1,sensor=L1 temperature="90.5",humidity=70.0 1632850122'': schema: field type for field "temperature" not permitted by schema; got String but expected Float' orgNotFound: summary: (OSS) organization not found value: @@ -17767,34 +17153,21 @@ paths: message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/LineProtocolError' - description: > + description: | Bad request. The response body contains detail about the error. - - InfluxDB returns this error if the line protocol data in the request - is malformed. - - The response body contains the first malformed line in the data, and - indicates what was expected. - - For partial writes, the number of points written and the number of - points rejected are also included. - - For more information, check the `rejected_points` measurement in - your `_monitoring` bucket. - + InfluxDB returns this error if the line protocol data in the request is malformed. + The response body contains the first malformed line in the data, and indicates what was expected. + For partial writes, the number of points written and the number of points rejected are also included. + For more information, check the `rejected_points` measurement in your `_monitoring` bucket. #### InfluxDB Cloud - - Returns this error for bucket schema conflicts. - #### InfluxDB OSS - - - Returns this error if `org` or `orgID` doesn't match an - organization. + - Returns this error if `org` or `orgID` doesn't match an organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -17805,9 +17178,8 @@ paths: examples: dataExceedsSizeLimitOSS: summary: InfluxDB OSS response - value: > - {"code":"request too large","message":"unable to read data: - points batch is too large"} + value: | + {"code":"request too large","message":"unable to read data: points batch is too large"} schema: $ref: '#/components/schemas/LineProtocolLengthError' text/html: @@ -17857,28 +17229,22 @@ paths: - Doesn't return this error. headers: Retry-After: - description: >- - Non-negative decimal integer indicating seconds to wait before - retrying the request. + description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: format: int32 type: integer '500': $ref: '#/components/responses/InternalServerError' '503': - description: > + description: | Service unavailable. - - Returns this error if the server is temporarily unavailable to accept writes. - - Returns a `Retry-After` header that describes when to try the - write again. + - Returns a `Retry-After` header that describes when to try the write again. headers: Retry-After: - description: >- - Non-negative decimal integer indicating seconds to wait before - retrying the request. + description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: format: int32 type: integer @@ -17895,42 +17261,42 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns legacy authorizations scoped to this user. + Only returns legacy authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns legacy authorizations scoped to this user. + Only returns legacy authorizations scoped to the specified [user](/influxdb/cloud/reference/glossary/#user). in: query name: user schema: type: string - description: | An organization ID. - Only returns legacy authorizations that belong to this organization. + Only returns legacy authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns legacy authorizations that belong to this organization. + Only returns legacy authorizations that belong to the specified [organization](/influxdb/cloud/reference/glossary/#organization). in: query name: org schema: type: string - description: | An authorization name token. - Only returns legacy authorizations with this token (name). + Only returns legacy authorizations with the specified name. in: query name: token schema: type: string - description: | An authorization ID. - Only returns the legacy authorization with this ID. + Returns the specified legacy authorization. in: query name: authID schema: @@ -17949,9 +17315,7 @@ paths: $ref: '#/components/schemas/Links' readOnly: true type: object - description: >- - Success. The response body contains a list of legacy - `authorizations`. + description: Success. The response body contains a list of legacy `authorizations`. default: $ref: '#/components/responses/ServerError' description: Unexpected error @@ -17959,20 +17323,14 @@ paths: tags: - Legacy Authorizations post: - description: > - Creates a legacy authorization and returns the newly created - authorization. - + description: | + Creates a legacy authorization and returns the legacy authorization. #### Required permissions + - `write-users USER_ID` if you pass the `userID` property in the request body. - - `write-users USER_ID` if you pass the `userID` property in the request - body. - - - `USER_ID` is the ID of the user that you want to scope the authorization - to. + `USER_ID` is the ID of the user that you want to scope the authorization to. operationId: PostLegacyAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18007,17 +17365,14 @@ paths: schema: properties: code: - description: > - The HTTP status code description. Default is - `unauthorized`. + description: | + The HTTP status code description. Default is `unauthorized`. enum: - unauthorized readOnly: true type: string message: - description: >- - A human-readable message that may contain detail about the - error. + description: A human-readable message that may contain detail about the error. readOnly: true type: string description: | @@ -18150,30 +17505,22 @@ paths: name: Accept schema: default: application/json - description: > + description: | Media type that the client can understand. - - **Note**: With `application/csv`, query results include [**unix - timestamps**](/influxdb/cloud/reference/glossary/#unix-timestamp) - instead of [RFC3339 - timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp). + **Note**: With `application/csv`, query results include [**unix timestamps**](/influxdb/cloud/reference/glossary/#unix-timestamp) instead of [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp). enum: - application/json - application/csv - text/csv - application/x-msgpack type: string - - description: >- - The content encoding (usually a compression algorithm) that the - client can understand. + - description: The content encoding (usually a compression algorithm) that the client can understand. in: header name: Accept-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -18194,49 +17541,33 @@ paths: name: p schema: type: string - - description: > + - description: | The database to query data from. - - This is mapped to an InfluxDB - [bucket](/influxdb/cloud/reference/glossary/#bucket). - - For more information, see [Database and retention policy - mapping](/influxdb/cloud/api/influxdb-1x/dbrp/). + This is mapped to an InfluxDB [bucket](/influxdb/cloud/reference/glossary/#bucket). + For more information, see [Database and retention policy mapping](/influxdb/cloud/api/influxdb-1x/dbrp/). in: query name: db required: true schema: type: string - - description: > + - description: | The retention policy to query data from. - - This is mapped to an InfluxDB - [bucket](/influxdb/cloud/reference/glossary/#bucket). - - For more information, see [Database and retention policy - mapping](/influxdb/cloud/api/influxdb-1x/dbrp/). + This is mapped to an InfluxDB [bucket](/influxdb/cloud/reference/glossary/#bucket). + For more information, see [Database and retention policy mapping](/influxdb/cloud/api/influxdb-1x/dbrp/). in: query name: rp schema: type: string - - description: >- - The InfluxQL query to execute. To execute multiple queries, delimit - queries with a semicolon (`;`). + - description: The InfluxQL query to execute. To execute multiple queries, delimit queries with a semicolon (`;`). in: query name: q required: true schema: type: string - - description: > + - description: | A unix timestamp precision. - - Formats timestamps as [unix (epoch) - timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) the - specified precision - - instead of [RFC3339 - timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) - with nanosecond precision. + Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud/reference/glossary/#unix-timestamp) the specified precision + instead of [RFC3339 timestamps](/influxdb/cloud/reference/glossary/#rfc3339-timestamp) with nanosecond precision. in: query name: epoch schema: @@ -18268,9 +17599,7 @@ paths: description: Query results headers: Content-Encoding: - description: >- - Lists encodings (usually compression algorithms) that have been - applied to the response payload. + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity description: | @@ -18299,9 +17628,7 @@ paths: - doesn't return this error. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: format: int32 type: integer @@ -18329,9 +17656,7 @@ paths: name: p schema: type: string - - description: >- - Bucket to write to. If none exists, InfluxDB creates a bucket with a - default 3-day retention policy. + - description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy. in: query name: db required: true @@ -18347,16 +17672,12 @@ paths: name: precision schema: type: string - - description: >- - When present, its value indicates to the database that compression - is applied to the line protocol body. + - description: When present, its value indicates to the database that compression is applied to the line protocol body. in: header name: Content-Encoding schema: default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. enum: - gzip - identity @@ -18370,26 +17691,19 @@ paths: required: true responses: '204': - description: >- - Write data is correctly formatted and accepted for writing to the - bucket. + description: Write data is correctly formatted and accepted for writing to the bucket. '400': content: application/json: schema: $ref: '#/components/schemas/LineProtocolError' - description: >- - Line protocol poorly formed and no points were written. Response - can be used to determine the first malformed line in the body - line-protocol. All data in body was rejected and not written. + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. '401': content: application/json: schema: $ref: '#/components/schemas/Error' - description: >- - Token doesn't have sufficient permissions to write to this - organization and bucket or the organization and bucket do not exist. + description: Token doesn't have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. '403': content: application/json: @@ -18401,31 +17715,20 @@ paths: application/json: schema: $ref: '#/components/schemas/LineProtocolLengthError' - description: >- - Write has been rejected because the payload is too large. Error - message returns max size supported. All data in body was rejected - and not written. + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the write again. + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: format: int32 type: integer '503': - description: >- - Server is temporarily unavailable to accept writes. The Retry-After - header describes when to try the write again. + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: format: int32 type: integer @@ -18443,144 +17746,84 @@ security: servers: - url: / tags: - - description: > + - description: | Use one of the following schemes to authenticate to the InfluxDB API: - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - - - [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - + - [Querystring authentication](#section/Authentication/QuerystringAuthentication) name: Authentication x-traitTag: true - - description: > + - description: | Create and manage authorizations (API tokens). - An _authorization_ contains a list of `read` and `write` - - permissions for organization resources and provides an API token for - authentication. - - An authorization belongs to an organization and only contains permissions - for that organization. - + permissions for organization resources and provides an API token for authentication. + An authorization belongs to an organization and only contains permissions for that organization. In InfluxDB Cloud, an authorization with `read-authorizations` permission - can be used to view other authorizations. - - Optionally, when creating an authorization, you can scope it to a specific - user. - + Optionally, when creating an authorization, you can scope it to a specific user. #### Limitations - To follow best practices for secure API token generation and retrieval, - InfluxDB Cloud enforces access restrictions on API tokens. - - - InfluxDB Cloud only allows access to the API token value immediately - after the authorization is created. - - - You can’t change access (read/write) permissions for an API token after - it’s created. - + - InfluxDB Cloud only allows access to the API token value immediately after the authorization is created. + - You can’t change access (read/write) permissions for an API token after it’s created. - Tokens stop working when the user who created the token is deleted. - We recommend the following for managing your tokens: - - Create a generic user to create and manage tokens for writing data. - - Store your tokens in a secure password vault for future access. - #### User sessions with authorizations - If a user signs in with username and password, creating a _user session_, - - the session carries the permissions granted by all the user's - authorizations. - - To create a user session, use the [`POST - /api/v2/signin`](#operation/PostSignin) endpoint. - + the session carries the permissions granted by all the user's authorizations. + To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints - - [Signin](#tag/Signin) - - [Signout](#tag/Signout) - ### Related guides - - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication). - - [Manage API tokens](/influxdb/cloud/security/tokens/). - - [Assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/). + - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication) + - [Manage API tokens](/influxdb/cloud/security/tokens/) + - [Assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/) name: Authorizations - name: Bucket Schemas - - description: > - Store your data in InfluxDB - [buckets](/influxdb/cloud/reference/glossary/#bucket). - + - description: | + Store your data in InfluxDB [buckets](/influxdb/cloud/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - - have a [retention - period](/influxdb/cloud/reference/glossary/#retention-period), - + have a [retention period](/influxdb/cloud/reference/glossary/#retention-period), a duration of time that each data point persists. InfluxDB drops all - points with timestamps older than the bucket’s retention period. - A bucket belongs to an organization. - ### Related guides - - [Manage buckets](/influxdb/cloud/organizations/buckets/) + - [Manage buckets](/influxdb/cloud/organizations/buckets/) name: Buckets - name: Cells - name: Checks - - description: > - Many InfluxDB API endpoints require parameters to specify resources--for - example, - + - description: | + Many InfluxDB API endpoints require parameters to specify resources--for example, writing to a **bucket** in an **organization**. - ### Common query parameters - - | Query parameter | Value type | - Description | - - |:------------------------ |:--------------------- - |:-------------------------------------------| - - | `bucket` | string | The bucket name or ID - ([find your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). - | - - | `bucketID` | string | The bucket ID ([find - your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). | - - | `org` | string | The organization name - or ID ([find your organization](/influxdb/cloud/organizations/view-orgs/). - | - - | `orgID` | 16-byte string | The organization ID - ([find your organization](/influxdb/cloud/organizations/view-orgs/). | + | Query parameter | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](/influxdb/cloud/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](/influxdb/cloud/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/cloud/organizations/view-orgs/). | name: Common parameters x-traitTag: true - name: Dashboards @@ -18589,66 +17832,43 @@ tags: - description: | Delete data from an InfluxDB bucket. name: Delete - - description: > + - description: | InfluxDB API endpoints use standard HTTP request and response headers. - **Note**: Not all operations support all headers. - ### Request headers - - | Header | Value type | - Description | - - |:------------------------ |:--------------------- - |:-------------------------------------------| - - | `Accept` | string | The content type that - the client can understand. | - - | `Authorization` | string | The authorization - scheme and credential. | - - | `Content-Encoding` | string | The compression - applied to the line protocol in the request payload. | - - | `Content-Length` | integer | The size of the - entity-body, in bytes, sent to the database. | - - | `Content-Type` | string | The format of the - data in the request body. | + | Header | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `Accept` | string | The content type that the client can understand. | + | `Authorization` | string | The authorization scheme and credential. | + | `Content-Encoding` | string | The compression applied to the line protocol in the request payload. | + | `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. | + | `Content-Type` | string | The format of the data in the request body. | name: Headers x-traitTag: true - - description: > - Manage and execute scripts as API endpoints in InfluxDB. + - description: | + Store, manage, and execute scripts in InfluxDB. + A script stores your custom Flux script and provides an invokable + endpoint that accepts runtime parameters. + In a script, you can specify custom runtime parameters + (`params`)--for example, `params.myparameter`. + Once you create a script, InfluxDB generates an + [`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke) + for your organization. + You can run the script from API requests and tasks, defining parameter + values for each run. + When the script runs, InfluxDB replaces `params` references in the + script with the runtime parameter values you define. + Use the `/api/v2/scripts` endpoints to create and manage scripts. + See related guides to learn how to define parameters and execute scripts. - An API Invokable Script assigns your custom Flux script to a new + #### Related guides - InfluxDB API endpoint for your organization. - - Invokable scripts let you execute your script as an HTTP request to the - endpoint. - - - Invokable scripts accept parameters. - - Add parameter references in your script as `params.myparameter`. - - When you `invoke` your script, you send parameters as key-value pairs in - the `params` object. - - Then, InfluxDB executes your script with the key-value pairs as arguments, - and returns the result. - - - ### Related guides - - - - [Invoke custom - scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) from API requests. + - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) name: Invokable Scripts - name: Labels - name: Legacy Authorizations @@ -18657,92 +17877,44 @@ tags: - name: Limits - name: NotificationEndpoints - name: NotificationRules - - description: > - Manage your - [organization](/influxdb/cloud/reference/glossary/#organization). - + - description: | + Manage your [organization](/influxdb/cloud/reference/glossary/#organization). An organization is a workspace for a group of users. Organizations can be - used to separate different environments, projects, teams or users within - InfluxDB. - Use the `/api/v2/orgs` endpoints to view and manage organizations. name: Organizations - name: Ping - description: | Retrieve data, analyze queries, and get query suggestions. name: Query - - description: > - See the [**API Quick Start**](/influxdb/cloud/api-guide/api_intro/) to get - up and running authenticating with tokens, writing to buckets, and - querying data. + - description: | + See the [**API Quick Start**](/influxdb/cloud/api-guide/api_intro/) to get up and running authenticating with tokens, writing to buckets, and querying data. - - [**InfluxDB API client - libraries**](/influxdb/cloud/api-guide/client-libraries/) are available - for popular languages and ready to import into your application. + [**InfluxDB API client libraries**](/influxdb/cloud/api-guide/client-libraries/) are available for popular languages and ready to import into your application. name: Quick start x-traitTag: true - name: Resources - - description: > - The InfluxDB API uses standard HTTP status codes for success and failure - responses. - - The response body may include additional details. For details about a - specific operation's response, see **Responses** and **Response Samples** - for that operation. - + - description: | + The InfluxDB API uses standard HTTP status codes for success and failure responses. + The response body may include additional details. For details about a specific operation's response, see **Responses** and **Response Samples** for that operation. API operations may return the following HTTP status codes: - |  Code  | Status | Description | - |:-----------:|:------------------------ |:--------------------- | - | `200` | Success | | - - | `204` | No content | For a `POST` request, `204` - indicates that InfluxDB accepted the request and request data is valid. - Asynchronous operations, such as `write`, might not have completed yet. | - - | `400` | Bad request | May indicate one of the - following:
  • Line protocol is malformed. The response body contains - the first malformed line in the data and indicates what was expected. For - partial writes, the number of points written and the number of points - rejected are also included. For more information, check the - `rejected_points` measurement in your `_monitoring` - bucket.
  • `Authorization` header is missing or malformed or the API - token doesn't have permission for the operation.
| - - | `401` | Unauthorized | May indicate one of the - following:
  • `Authorization: Token` header is missing or - malformed
  • API token value is missing from the header
  • API - token doesn't have permission. For more information about token types and - permissions, see [Manage API - tokens](/influxdb/cloud/security/tokens/)
| - - | `404` | Not found | Requested resource was not - found. `message` in the response body provides details about the requested - resource. | - - | `413` | Request entity too large | Request payload exceeds the - size limit. | - - | `422` | Unprocessable entity | Request data is invalid. `code` - and `message` in the response body provide details about the problem. | - - | `429` | Too many requests | API token is temporarily over - the request quota. The `Retry-After` header describes when to try the - request again. | - + | `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. | + | `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems:
  • Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your [_monitoring bucket](/influxdb/cloud/reference/internals/system-buckets/#_monitoring-system-bucket).
  • `Authorization` header is missing or malformed or the API token doesn't have permission for the operation.
| + | `401` | Unauthorized | May indicate one of the following:
  • `Authorization: Token` header is missing or malformed
  • API token value is missing from the header
  • API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/cloud/security/tokens/)
| + | `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. | + | `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. | + | `413` | Request entity too large | Request payload exceeds the size limit. | + | `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. | + | `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. | | `500` | Internal server error | | - - | `503` | Service unavailable | Server is temporarily - unavailable to process the request. The `Retry-After` header describes - when to try the request again. | + | `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. | name: Response codes x-traitTag: true - name: Routes @@ -18753,113 +17925,66 @@ tags: - name: Signin - name: Signout - 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. - - In InfluxDB Cloud, you can create tasks that run [invokable - scripts](#tag/Invokable-Scripts) - + - description: | + Process and analyze your data with [tasks](/influxdb/cloud/reference/glossary/#task) 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. - + Use the `/api/v2/tasks` endpoints to create and manage tasks, retry task runs, and retrieve run logs. #### Related guides - - - [Get started with tasks](/influxdb/cloud/process-data/get-started/). - - - [Common data processing - tasks](/influxdb/cloud/process-data/common-tasks/) - - - [Create a - script](/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script). + - [Get started with tasks](/influxdb/cloud/process-data/get-started/) + - [Common data processing tasks](/influxdb/cloud/process-data/common-tasks/) + - [Create a script](/influxdb/cloud/api-guide/api-invokable-scripts/#create-an-invokable-script) name: Tasks - name: Telegraf Plugins - name: Telegrafs - - description: > + - description: | Export and apply InfluxDB **templates**. - Manage **stacks** of templated InfluxDB resources. - InfluxDB templates are prepackaged configurations for - everything from dashboards and Telegraf to notifications and alerts. - Use InfluxDB templates to quickly configure a fresh instance of InfluxDB, - back up your dashboard configuration, or share your configuration with the - InfluxData community. - - Use the `/api/v2/templates` endpoints to export templates and apply - templates. - + Use the `/api/v2/templates` endpoints to export templates and apply templates. **InfluxDB stacks** are stateful InfluxDB templates that let you - - add, update, and remove installed template resources over time, avoid - duplicating - + add, update, and remove installed template resources over time, avoid duplicating resources when applying the same or similar templates more than once, and - apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. - Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides - - [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/) - - [InfluxDB templates](/influxdb/cloud/influxdb-templates/) name: Templates - name: Usage - - description: > + - description: | Retrieve specific users. - - InfluxDB Cloud lets you invite and collaborate with multiple users in your - organization. - - To invite and remove users from your organization, use the InfluxDB Cloud - user interface (UI); - + InfluxDB Cloud lets you invite and collaborate with multiple users in your organization. + To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI); you can't use the InfluxDB API to manage users in InfluxDB Cloud. - Once a user is added to your organization, you can use the - `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to - view specific members. - #### User sessions with authorizations - Optionally, you can scope an authorization (and its API token) to a user. - If a user signs in with username and password, creating a _user session_, - - the session carries the permissions granted by all the user's - authorizations. - - To create a user session, use the [`POST - /api/v2/signin`](#operation/PostSignin) endpoint. - + the session carries the permissions granted by all the user's authorizations. + To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). #### Related guides - - [Manage users](/influxdb/cloud/organizations/users/) name: Users - name: Variables diff --git a/api-docs/cloud/swaggerV1Compat.yml b/api-docs/cloud/swaggerV1Compat.yml index c96be9f27..02860b1ce 100644 --- a/api-docs/cloud/swaggerV1Compat.yml +++ b/api-docs/cloud/swaggerV1Compat.yml @@ -2,20 +2,13 @@ openapi: 3.0.0 info: title: InfluxDB Cloud v1 compatibility API documentation version: 0.1.0 - description: > - The InfluxDB 1.x compatibility /write and /query endpoints work with - InfluxDB 1.x client libraries and third-party integrations like Grafana and - others. - - - If you want to use the latest InfluxDB /api/v2 API instead, see the - [InfluxDB v2 API documentation](/influxdb/cloud/api/). + description: | + The InfluxDB 1.x compatibility /write and /query endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. + If you want to use the latest InfluxDB /api/v2 API instead, see the [InfluxDB v2 API documentation](/influxdb/cloud/api/). This documentation is generated from the - - [InfluxDB OpenAPI - specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml). + [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml). servers: - url: / paths: @@ -41,9 +34,7 @@ paths: schema: type: string required: true - description: >- - Bucket to write to. If none exists, InfluxDB creates a bucket with a - default 3-day retention policy. + description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy. - in: query name: rp schema: @@ -56,36 +47,25 @@ paths: description: Write precision. - in: header name: Content-Encoding - description: >- - When present, its value indicates to the database that compression - is applied to the line protocol body. + description: When present, its value indicates to the database that compression is applied to the line protocol body. schema: type: string - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity responses: '204': - description: >- - Write data is correctly formatted and accepted for writing to the - bucket. + description: Write data is correctly formatted and accepted for writing to the bucket. '400': - description: >- - Line protocol poorly formed and no points were written. Response - can be used to determine the first malformed line in the body - line-protocol. All data in body was rejected and not written. + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. content: application/json: schema: $ref: '#/components/schemas/LineProtocolError' '401': - description: >- - Token does not have sufficient permissions to write to this - organization and bucket or the organization and bucket do not exist. + description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. content: application/json: schema: @@ -97,35 +77,24 @@ paths: schema: $ref: '#/components/schemas/Error' '413': - description: >- - Write has been rejected because the payload is too large. Error - message returns max size supported. All data in body was rejected - and not written. + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. content: application/json: schema: $ref: '#/components/schemas/LineProtocolLengthError' '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the write again. + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 '503': - description: >- - Server is temporarily unavailable to accept writes. The Retry-After - header describes when to try the write again. + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 @@ -155,10 +124,7 @@ paths: name: Accept schema: type: string - description: >- - Specifies how query results should be encoded in the response. - **Note:** With `application/csv`, query results include epoch - timestamps instead of RFC3339 timestamps. + description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps. default: application/json enum: - application/json @@ -167,15 +133,10 @@ paths: - application/x-msgpack - in: header name: Accept-Encoding - description: >- - The Accept-Encoding request HTTP header advertises which content - encoding, usually a compression algorithm, the client is able to - understand. + description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. schema: type: string - description: >- - Specifies that the query response in the body should be encoded - with gzip or not encoded with identity. + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. default: identity enum: - gzip @@ -207,23 +168,16 @@ paths: description: Query results headers: Content-Encoding: - description: >- - The Content-Encoding entity header is used to compress the - media-type. When present, its value indicates which encodings - were applied to the entity-body + description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body schema: type: string - description: >- - Specifies that the response in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the response in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity Trace-Id: - description: >- - The Trace-Id header reports the request's trace ID, if one was - generated. + description: The Trace-Id header reports the request's trace ID, if one was generated. schema: type: string description: Specifies the request's trace ID. @@ -242,14 +196,10 @@ paths: type: string format: binary '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the read again. + description: Token is temporarily over quota. The Retry-After header describes when to try the read again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 @@ -330,11 +280,8 @@ components: items: {} InfluxQLCSVResponse: type: string - example: > - name,tags,time,test_field,test_tag - test_measurement,,1603740794286107366,1,tag_value - test_measurement,,1603740870053205649,2,tag_value - test_measurement,,1603741221085428881,3,tag_value + example: | + name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value Error: properties: code: @@ -379,15 +326,11 @@ components: type: string op: readOnly: true - description: >- - Op describes the logical code operation during error. Useful for - debugging. + description: Op describes the logical code operation during error. Useful for debugging. type: string err: readOnly: true - description: >- - Err is a stack of errors that occurred during processing of the - request. Useful for debugging. + description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. type: string line: readOnly: true @@ -425,30 +368,21 @@ components: type: apiKey name: Authorization in: header - description: > - Use the [Token - authentication](#section/Authentication/TokenAuthentication) - + description: | + Use the [Token authentication](#section/Authentication/TokenAuthentication) scheme to authenticate to the InfluxDB API. - In your API requests, send an `Authorization` header. - - For the header value, provide the word `Token` followed by a space and - an InfluxDB API token. - + For the header value, provide the word `Token` followed by a space and an InfluxDB API token. The word `Token` is case-sensitive. - ### Syntax - `Authorization: Token YOUR_INFLUX_TOKEN` - For examples and more information, see the following: - [`/authorizations`](#tag/Authorizations) endpoint. - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication). @@ -456,54 +390,37 @@ components: BasicAuthentication: type: http scheme: basic - description: > - Use the HTTP [Basic - authentication](#section/Authentication/BasicAuthentication) - - scheme with clients that support the InfluxDB 1.x convention of username - and password (that don't support the `Authorization: Token` scheme): + description: | + Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication) + scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme): - - For examples and more information, see how to [authenticate with a - username and password](/influxdb/cloud/reference/api/influxdb-1x/). + For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/). QuerystringAuthentication: type: apiKey in: query name: u=&p= - description: > - Use the [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - - scheme with InfluxDB 1.x API parameters to provide credentials through - the query string. + description: | + Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication) + scheme with InfluxDB 1.x API parameters to provide credentials through the query string. - - For examples and more information, see how to [authenticate with a - username and password](/influxdb/cloud/reference/api/influxdb-1x/). + For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/). security: - TokenAuthentication: [] - BasicAuthentication: [] - QuerystringAuthentication: [] tags: - name: Authentication - description: > + description: | The InfluxDB 1.x API requires authentication for all requests. - InfluxDB Cloud uses InfluxDB API tokens to authenticate requests. - For more information, see the following: - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - - - [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - + - [Querystring authentication](#section/Authentication/QuerystringAuthentication) x-traitTag: true diff --git a/api-docs/v2.4/ref.yml b/api-docs/v2.4/ref.yml index 64f6e1620..8ac4652de 100644 --- a/api-docs/v2.4/ref.yml +++ b/api-docs/v2.4/ref.yml @@ -1,9 +1,8 @@ components: parameters: After: - description: > - Resource ID to seek from. Results are not inclusive of this ID. Use - `after` instead of `offset`. + description: | + Resource ID to seek from. Results are not inclusive of this ID. Use `after` instead of `offset`. in: query name: after required: false @@ -75,9 +74,7 @@ components: readOnly: true type: string message: - description: >- - A human-readable message that may contain detail about the - error. + description: A human-readable message that may contain detail about the error. readOnly: true type: string description: | @@ -91,25 +88,19 @@ components: application/json: examples: orgProvidedNotFound: - summary: >- - The org or orgID passed doesn't own the token passed in the - header + summary: The org or orgID passed doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/Error' - description: > + description: | Bad request. - The response body contains detail about the error. - #### InfluxDB OSS - - - Returns this error if an incorrect value is passed for `org` or - `orgID`. + - Returns this error if an incorrect value is passed for `org` or `orgID`. GeneralServerError: content: application/json: @@ -145,21 +136,14 @@ components: message: organization not found schema: $ref: '#/components/schemas/Error' - description: > + description: | Not found. - A requested resource was not found. - - The response body contains the requested resource type and the name - value - + The response body contains the requested resource type and the name value (if you passed it)--for example: - - `"organization name \"my-org\" not found"` - - - `"organization not found"`: indicates you passed an ID that did not - match + - `"organization not found"`: indicates you passed an ID that did not match an organization. ServerError: content: @@ -223,6 +207,7 @@ components: readOnly: true type: string id: + description: The authorization ID. readOnly: true type: string links: @@ -239,15 +224,19 @@ components: readOnly: true type: object org: - description: The name of the organization that owns the token. + description: | + The organization name. + Specifies the [organization](/influxdb/v2.4/reference/glossary/#organization) that the token is scoped to. readOnly: true type: string orgID: - description: The ID of the organization. + description: | + The organization ID. + Specifies the [organization](/influxdb/v2.4/reference/glossary/#organization) that the authorization is scoped to. type: string permissions: description: | - A list of permissions for an authorization. + The list of permissions. An authorization must have at least one permission. items: $ref: '#/components/schemas/Permission' @@ -255,7 +244,11 @@ components: type: array token: description: | - The API token for authenticating InfluxDB API and CLI requests. + The API token. + [Tokens](/influxdb/v2.4/reference/glossary/#token) are + used to authenticate InfluxDB API requests and `influx` CLI commands. + If authenticated, the token is allowed the permissions of the _authorization_. + The token value is unique to the authorization. readOnly: true type: string updatedAt: @@ -263,11 +256,15 @@ components: readOnly: true type: string user: - description: The name of the user that the token is scoped to. + description: | + The user name. + Specifies the [user](/influxdb/v2.4/reference/glossary/#user) that owns the authorization. + If the authorization is _scoped_ to a user, the user; + otherwise, the creator of the authorization. readOnly: true type: string userID: - description: The ID of the user that the token is scoped to. + description: The user ID. Specifies the [user](/influxdb/v2.4/reference/glossary/#user) that owns the authorization. If _scoped_, the user that the authorization is scoped to; otherwise, the creator of the authorization. readOnly: true type: string type: object @@ -305,9 +302,7 @@ components: type: string status: default: active - description: >- - Status of the token. If `inactive`, requests using the token will be - rejected. + description: Status of the token. If `inactive`, requests using the token will be rejected. enum: - active - inactive @@ -344,9 +339,7 @@ components: - '10' type: string bounds: - description: >- - The extents of the axis in the form [lower, upper]. Clients - determine whether bounds are inclusive or exclusive of their limits. + description: The extents of the axis in the form [lower, upper]. Clients determine whether bounds are inclusive or exclusive of their limits. items: type: string maxItems: 2 @@ -371,9 +364,7 @@ components: - linear type: string BadStatement: - description: >- - A placeholder for statements for which no correct statement nodes can be - created + description: A placeholder for statements for which no correct statement nodes can be created properties: text: description: Raw source text @@ -779,10 +770,7 @@ components: readOnly: true type: string latestCompleted: - description: >- - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) - of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -919,10 +907,7 @@ components: ColorMapping: additionalProperties: type: string - description: >- - A color mapping is an object that maps time series data to a UI color - scheme to allow the UI to render graphs consistent colors across - reloads. + description: A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads. example: configcat_deployments-autopromotionblocker: '#663cd0' measurement_birdmigration_europe: '#663cd0' @@ -930,9 +915,7 @@ components: series_id_2: '#edf529' type: object ConditionalExpression: - description: >- - Selects one of two expressions, `Alternate` or `Consequent`, depending - on a third boolean expression, `Test` + description: Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test` properties: alternate: $ref: '#/components/schemas/Expression' @@ -1012,9 +995,7 @@ components: description: InfluxDB v1 database type: string default: - description: >- - Mapping represents the default retention policy for the database - specified. + description: Mapping represents the default retention policy for the database specified. type: boolean id: description: The ID of the DBRP mapping. @@ -1029,9 +1010,7 @@ components: description: InfluxDB v1 retention policy type: string virtual: - description: >- - Indicates an autogenerated, virtual mapping based on the bucket - name. Currently only available in OSS. + description: Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. type: boolean required: - id @@ -1050,9 +1029,7 @@ components: description: InfluxDB v1 database type: string default: - description: >- - Mapping represents the default retention policy for the database - specified. + description: Mapping represents the default retention policy for the database specified. type: boolean org: description: The name of the organization that owns this mapping. @@ -1232,10 +1209,7 @@ components: $ref: '#/components/schemas/Links' type: object DateTimeLiteral: - description: >- - Represents an instant in time with nanosecond precision in [RFC3339Nano - date/time - format](/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp). + description: Represents an instant in time with nanosecond precision in [RFC3339Nano date/time format](/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp). properties: type: $ref: '#/components/schemas/NodeType' @@ -1259,9 +1233,7 @@ components: description: If only zero values reported since time, trigger an alert type: boolean staleTime: - description: >- - String duration for time that a series is considered stale and - should not trigger deadman. + description: String duration for time that a series is considered stale and should not trigger deadman. type: string statusMessageTemplate: description: The template used to generate and write a status message. @@ -1287,9 +1259,7 @@ components: - type type: object DecimalPlaces: - description: >- - Indicates whether decimal places should be enforced, and how many digits - it should show. + description: Indicates whether decimal places should be enforced, and how many digits it should show. properties: digits: description: The number of digits after decimal to display @@ -1303,24 +1273,19 @@ components: description: The delete predicate request. properties: predicate: - description: > - An expression in [delete predicate - syntax](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/delete-predicate/). + description: | + An expression in [delete predicate syntax](/influxdb/v2.3/reference/syntax/delete-predicate/). example: tag1="value1" and (tag2="value2" and tag3!="value3") type: string start: - description: > - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - + description: | + A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). The earliest time to delete from. format: date-time type: string stop: - description: > - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - + description: | + A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). The latest time to delete from. format: date-time type: string @@ -1329,39 +1294,24 @@ components: - stop type: object Dialect: - description: > + description: | Options for tabular data output. - - Default output is [annotated - CSV](/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) - with headers. - + Default output is [annotated CSV](/influxdb/v2.3/reference/syntax/annotated-csv/#csv-response-format) with headers. For more information about tabular data **dialect**, - - see [W3 metadata vocabulary for tabular - data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-metadata-20151217/#dialect-descriptions). properties: annotations: - description: > + description: | Annotation rows to include in the results. - - An _annotation_ is metadata associated with an object (column) in - the data model. - + An _annotation_ is metadata associated with an object (column) in the data model. #### Related guides - - - See [Annotated CSV - annotations](https://docs.influxdata.com/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) - for examples and more information. - + - See [Annotated CSV annotations](/influxdb/v2.3/reference/syntax/annotated-csv/#annotations) for examples and more information. For more information about **annotations** in tabular data, - - see [W3 metadata vocabulary for tabular - data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). + see [W3 metadata vocabulary for tabular data](https://www.w3.org/TR/2015/REC-tabular-data-model-20151217/#columns). items: enum: - group @@ -1372,32 +1322,22 @@ components: uniqueItems: true commentPrefix: default: '#' - description: >- - The character prefixed to comment strings. Default is a number sign - (`#`). + description: The character prefixed to comment strings. Default is a number sign (`#`). maxLength: 1 minLength: 0 type: string dateTimeFormat: default: RFC3339 - description: > + description: | The format for timestamps in results. - - Default is [`RFC3339` date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). - + Default is [`RFC3339` date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp). To include nanoseconds in timestamps, use `RFC3339Nano`. - #### Example formatted date/time values - | Format | Value | - |:------------|:----------------------------| - | `RFC3339` | `"2006-01-02T15:04:05Z07:00"` | - | `RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` | enum: - RFC3339 @@ -1436,9 +1376,7 @@ components: $ref: '#/components/schemas/Expression' type: object Duration: - description: >- - A pair consisting of length of time and the unit of time measured. It is - the atomic unit from which all duration literals are composed. + description: A pair consisting of length of time and the unit of time measured. It is the atomic unit from which all duration literals are composed. properties: magnitude: type: integer @@ -1448,9 +1386,7 @@ components: type: string type: object DurationLiteral: - description: >- - Represents the elapsed time between two instants as an int64 nanosecond - count with syntax of golang's time.Duration + description: Represents the elapsed time between two instants as an int64 nanosecond count with syntax of golang's time.Duration properties: type: $ref: '#/components/schemas/NodeType' @@ -1482,9 +1418,7 @@ components: readOnly: true type: string err: - description: >- - Stack of errors that occurred during processing of the request. - Useful for debugging. + description: Stack of errors that occurred during processing of the request. Useful for debugging. readOnly: true type: string message: @@ -1492,9 +1426,7 @@ components: readOnly: true type: string op: - description: >- - Describes the logical code operation when the error occurred. Useful - for debugging. + description: Describes the logical code operation when the error occurred. Useful for debugging. readOnly: true type: string required: @@ -1543,9 +1475,7 @@ components: - $ref: '#/components/schemas/UnsignedIntegerLiteral' - $ref: '#/components/schemas/Identifier' ExpressionStatement: - description: >- - May consist of an expression that doesn't return a value and is executed - solely for its side-effects + description: May consist of an expression that doesn't return a value and is executed solely for its side-effects properties: expression: $ref: '#/components/schemas/Expression' @@ -1555,9 +1485,7 @@ components: Field: properties: alias: - description: >- - Alias overrides the field name in the returned response. Applies - only if type is `func` + description: Alias overrides the field name in the returned response. Applies only if type is `func` type: string args: description: Args are the arguments to the function @@ -1565,9 +1493,7 @@ components: $ref: '#/components/schemas/Field' type: array type: - description: >- - `type` describes the field type. `func` is a function. `field` is a - field reference. + description: '`type` describes the field type. `func` is a function. `field` is a field reference.' enum: - func - field @@ -1577,9 +1503,7 @@ components: - wildcard type: string value: - description: >- - value is the value of the field. Meaning of the value is implied by - the `type` key + description: value is the value of the field. Meaning of the value is implied by the `type` key type: string type: object File: @@ -1607,9 +1531,7 @@ components: additionalProperties: true type: object FloatLiteral: - description: >- - Represents floating point numbers according to the double - representations defined by the IEEE-754-1985 + description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 properties: type: $ref: '#/components/schemas/NodeType' @@ -1854,9 +1776,7 @@ components: type: array detectCoordinateFields: default: true - description: >- - If true, search results get automatically regroupped so that lon,lat - and value are treated as columns + description: If true, search results get automatically regroupped so that lon,lat and value are treated as columns type: boolean latLonColumns: $ref: '#/components/schemas/LatLonColumns' @@ -2204,11 +2124,8 @@ components: type: object InfluxqlCsvResponse: description: CSV Response to InfluxQL Query - example: > - name,tags,time,test_field,test_tag - test_measurement,,1603740794286107366,1,tag_value - test_measurement,,1603740870053205649,2,tag_value - test_measurement,,1603741221085428881,3,tag_value + example: | + name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value type: string InfluxqlJsonResponse: description: JSON Response to InfluxQL Query @@ -2274,11 +2191,9 @@ components: properties: additionalProperties: type: string - description: > + description: | Key-value pairs associated with this label. - - To remove a property, send an update with an empty value (`""`) for - the key. + To remove a property, send an update with an empty value (`""`) for the key. example: color: ffb3b3 description: this is a description @@ -2293,12 +2208,10 @@ components: properties: additionalProperties: type: string - description: > + description: | Key-value pairs associated with this label. - - To remove a property, send an update with an empty value (`""`) for - the key. + To remove a property, send an update with an empty value (`""`) for the key. example: color: ffb3b3 description: this is a description @@ -2328,12 +2241,10 @@ components: type: string properties: additionalProperties: - description: > + description: | Key-value pairs associated with this label. - - To remove a property, send an update with an empty value (`""`) - for the key. + To remove a property, send an update with an empty value (`""`) for the key. type: string example: color: ffb3b3 @@ -2393,10 +2304,8 @@ components: description: The ID of the organization that the authorization is scoped to. type: string permissions: - description: > - A list of permissions that provide `read` and `write` access to - organization resources. - + description: | + A list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission. items: $ref: '#/components/schemas/Permission' @@ -2543,9 +2452,7 @@ components: readOnly: true type: string err: - description: >- - Stack of errors that occurred during processing of the request. - Useful for debugging. + description: Stack of errors that occurred during processing of the request. Useful for debugging. readOnly: true type: string line: @@ -2558,9 +2465,7 @@ components: readOnly: true type: string op: - description: >- - Describes the logical code operation when the error occurred. Useful - for debugging. + description: Describes the logical code operation when the error occurred. Useful for debugging. readOnly: true type: string required: @@ -2610,19 +2515,14 @@ components: readOnly: true type: string time: - description: >- - The time ([RFC3339Nano date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) - that the event occurred. + description: The time ([RFC3339Nano date/time format](/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) that the event occurred. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true type: string type: object LogicalExpression: - description: >- - Represents the rule conditions that collectively evaluate to either true - or false + description: Represents the rule conditions that collectively evaluate to either true or false properties: left: $ref: '#/components/schemas/Expression' @@ -2954,22 +2854,15 @@ components: readOnly: true type: string latestCompleted: - description: >- - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) - of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string limit: - description: >- - Don't notify me more than times every seconds. - If set, limitEvery cannot be empty. + description: Don't notify me more than times every seconds. If set, limitEvery cannot be empty. type: integer limitEvery: - description: >- - Don't notify me more than times every seconds. - If set, limit cannot be empty. + description: Don't notify me more than times every seconds. If set, limit cannot be empty. type: integer links: example: @@ -3096,18 +2989,15 @@ components: type: string retentionPeriodHrs: deprecated: true - description: > - Retention period *in nanoseconds* for the new bucket. This key's - name has been misleading since OSS 2.0 GA, please transition to use - `retentionPeriodSeconds` + description: | + Retention period *in nanoseconds* for the new bucket. This key's name has been misleading since OSS 2.0 GA, please transition to use `retentionPeriodSeconds` type: integer retentionPeriodSeconds: format: int64 type: integer token: - description: > - Authentication token to set on the initial user. If not specified, - the server will generate a token. + description: | + Authentication token to set on the initial user. If not specified, the server will generate a token. type: string username: type: string @@ -3309,31 +3199,21 @@ components: minimum: 0 type: integer shardGroupDurationSeconds: - description: > - The [shard group - duration](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#shard). - + description: | + The [shard group duration](/influxdb/v2.3/reference/glossary/#shard). The number of seconds that each shard group covers. - #### InfluxDB Cloud - - Doesn't use `shardGroupDurationsSeconds`. - #### InfluxDB OSS - - - Default value depends on the [bucket retention - period](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/#shard-group-duration). - + - Default value depends on the [bucket retention period](/influxdb/v2.3/reference/internals/shards/#shard-group-duration). #### Related guides - - - InfluxDB [shards and shard - groups](https://docs.influxdata.com/influxdb/v2.3/reference/internals/shards/) + - InfluxDB [shards and shard groups](/influxdb/v2.3/reference/internals/shards/) format: int64 type: integer type: @@ -3360,11 +3240,9 @@ components: $ref: '#/components/schemas/Resource' properties: id: - description: > + description: | The ID of a specific resource. - - In a `permission`, applies the permission to only the resource - with this ID. + In a `permission`, applies the permission to only the resource with this ID. type: string name: description: | @@ -3376,18 +3254,14 @@ components: Optional: The name of the organization with `orgID`. type: string orgID: - description: > + description: | The ID of the organization that owns the resource. - - In a `permission`, applies the permission to all resources of - `type` owned by this organization. + In a `permission`, applies the permission to all resources of `type` owned by this organization. type: string type: - description: > + description: | The type of resource. - - In a `permission`, applies the permission to all resources of - this type. + In a `permission`, applies the permission to all resources of this type. enum: - authorizations - buckets @@ -3430,9 +3304,7 @@ components: $ref: '#/components/schemas/NodeType' type: object PipeLiteral: - description: >- - Represents a specialized literal value, indicating the left hand value - of a pipe expression + description: Represents a specialized literal value, indicating the left hand value of a pipe expression properties: type: $ref: '#/components/schemas/NodeType' @@ -3456,41 +3328,27 @@ components: $ref: '#/components/schemas/RetentionRules' rp: default: '0' - description: > - Retention policy is an InfluxDB 1.x concept that represents the - duration - - of time that each data point in the retention policy persists. Use - `rp` - + description: | + Retention policy is an InfluxDB 1.x concept that represents the duration + of time that each data point in the retention policy persists. Use `rp` for compatibility with InfluxDB 1.x. - The InfluxDB 2.x and Cloud equivalent is - - [retention - period](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#retention-period). + [retention period](/influxdb/v2.3/reference/glossary/#retention-period). type: string schemaType: $ref: '#/components/schemas/SchemaType' default: implicit - description: > + description: | Schema Type. - - Use `explicit` to enforce column names, tags, fields, and data types - for - + Use `explicit` to enforce column names, tags, fields, and data types for your data. - #### InfluxDB Cloud - - Default is `implicit`. - #### InfluxDB OSS - - Doesn't support `schemaType`. required: - orgID @@ -3546,22 +3404,18 @@ components: type: string params: additionalProperties: true - description: > + description: | Key-value pairs passed as parameters during query execution. - - To use parameters in your query, pass a _`query`_ with `params` - references (in dot notation)--for example: - + 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)" + 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", @@ -3569,14 +3423,10 @@ components: } ``` - - During query execution, InfluxDB passes _`params`_ to your script - and substitutes the values. - + 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: @@ -3645,9 +3495,7 @@ components: type: string type: object RegexpLiteral: - description: >- - Expressions begin and end with `/` and are regular expressions with - syntax accepted by RE2 + description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 properties: type: $ref: '#/components/schemas/NodeType' @@ -3853,11 +3701,9 @@ components: Resource: properties: id: - description: > + description: | The ID of a specific resource. - - In a `permission`, applies the permission to only the resource with - this ID. + In a `permission`, applies the permission to only the resource with this ID. type: string name: description: | @@ -3869,18 +3715,14 @@ components: Optional: The name of the organization with `orgID`. type: string orgID: - description: > + description: | The ID of the organization that owns the resource. - - In a `permission`, applies the permission to all resources of `type` - owned by this organization. + In a `permission`, applies the permission to all resources of `type` owned by this organization. type: string type: - description: > + description: | The type of resource. - - In a `permission`, applies the permission to all resources of this - type. + In a `permission`, applies the permission to all resources of this type. enum: - authorizations - buckets @@ -4001,37 +3843,27 @@ components: properties: everySeconds: default: 2592000 - description: > - The duration in seconds for how long data will be kept in the - database. - + description: | + The duration in seconds for how long data will be kept in the database. The default duration is 2592000 (30 days). - 0 represents infinite retention. example: 86400 format: int64 minimum: 0 type: integer shardGroupDurationSeconds: - description: > + description: | The shard group duration. - The duration or interval (in seconds) that each shard group covers. - #### InfluxDB Cloud - - Does not use `shardGroupDurationsSeconds`. - #### InfluxDB OSS - - Default value depends on the - - [bucket retention - period](https://docs.influxdata.com/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). + [bucket retention period](/influxdb/v2.3/v2.3/reference/internals/shards/#shard-group-duration). format: int64 type: integer type: @@ -4156,10 +3988,7 @@ components: Run: properties: finishedAt: - description: >- - The time ([RFC3339Nano date/time - format](https://go.dev/src/time/format.go)) the run finished - executing. + description: The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run finished executing. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true @@ -4195,26 +4024,17 @@ components: readOnly: true type: array requestedAt: - description: >- - The time ([RFC3339Nano date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) - the run was manually requested. + description: The time ([RFC3339Nano date/time format](/influxdb/v2.3/reference/glossary/#rfc3339nano-timestamp)) the run was manually requested. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true type: string scheduledFor: - description: >- - The time [RFC3339 date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) - used for the run's `now` option. + description: The time [RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. format: date-time type: string startedAt: - description: >- - The time ([RFC3339Nano date/time - format](https://go.dev/src/time/format.go)) the run started - executing. + description: The time ([RFC3339Nano date/time format](https://go.dev/src/time/format.go)) the run started executing. example: 2006-01-02T15:04:05.999999999Z07:00 format: date-time readOnly: true @@ -4234,12 +4054,9 @@ components: RunManually: properties: scheduledFor: - description: > - The time [RFC3339 date/time - format](https://docs.influxdata.com/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) - + description: | + The time [RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) used for the run's `now` option. - Default is the server _now_ time. format: date-time nullable: true @@ -4629,9 +4446,7 @@ components: description: Specifies the API token string. Specify either `URL` or `Token`. type: string url: - description: >- - Specifies the URL of the Slack endpoint. Specify either `URL` or - `Token`. + description: Specifies the URL of the Slack endpoint. Specify either `URL` or `Token`. type: string type: object type: object @@ -4862,9 +4677,7 @@ components: decimalPlaces: $ref: '#/components/schemas/DecimalPlaces' fieldOptions: - description: >- - fieldOptions represent the fields retrieved by the query with - customization options + description: fieldOptions represent the fields retrieved by the query with customization options items: $ref: '#/components/schemas/RenamableField' type: array @@ -4884,21 +4697,15 @@ components: tableOptions: properties: fixFirstColumn: - description: >- - fixFirstColumn indicates whether the first column of the table - should be locked + description: fixFirstColumn indicates whether the first column of the table should be locked type: boolean sortBy: $ref: '#/components/schemas/RenamableField' verticalTimeAxis: - description: >- - verticalTimeAxis describes the orientation of the table by - indicating whether the time axis will be displayed vertically + description: verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically type: boolean wrapping: - description: >- - Wrapping describes the text wrapping style to be used in table - views + description: Wrapping describes the text wrapping style to be used in table views enum: - truncate - wrap @@ -4906,9 +4713,7 @@ components: type: string type: object timeFormat: - description: >- - timeFormat describes the display format for time values according to - moment.js date formatting + description: timeFormat describes the display format for time values according to moment.js date formatting type: string type: enum: @@ -4943,33 +4748,31 @@ components: Task: properties: authorizationID: - description: >- - The ID of the authorization used when the task communicates with the - query engine. + description: | + An authorization ID. + Specifies the authorization used when the task communicates with the query engine. + + To find an authorization ID, use the + [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to + list authorizations. type: string createdAt: format: date-time readOnly: true 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. + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. type: string description: - description: The description of the task. + description: A description of the task. type: string every: - description: >- - An 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. + description: The interval ([duration literal](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. format: duration type: string flux: - description: The Flux script that the task runs. + description: The Flux script that the task executes. + format: flux type: string id: readOnly: true @@ -4987,10 +4790,7 @@ components: readOnly: true type: string latestCompleted: - description: >- - A timestamp ([RFC3339 date/time - format](https://docs.influxdata.com/flux/v0.x/data-types/basic/time/#time-syntax)) - of the latest scheduled and completed run. + description: A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)) of the latest scheduled and completed run. format: date-time readOnly: true type: string @@ -5021,21 +4821,27 @@ components: 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. + 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 the task. + description: | + An [organization](/influxdb/v2.3/reference/glossary/#organization) name. + Specifies the organization that owns the task. type: string orgID: - description: The ID of the organization that owns the task. + description: | + An [organization](/influxdb/v2.3/reference/glossary/#organization) ID. + Specifies the organization that owns the task. type: string ownerID: - description: The ID of the user who owns the Task. + description: | + A [user](/influxdb/v2.3/reference/glossary/#user) ID. + Specifies the owner of the task. + + To find a user ID, you can use the + [`GET /api/v2/users` endpoint](#operation/GetUsers) to + list users. type: string status: $ref: '#/components/schemas/TaskStatusType' @@ -5222,14 +5028,10 @@ components: - $ref: '#/components/schemas/NotificationEndpointBase' - properties: channel: - description: >- - The ID of the telegram channel; a chat_id in - https://core.telegram.org/bots/api#sendmessage . + description: The ID of the telegram channel; a chat_id in https://core.telegram.org/bots/api#sendmessage . type: string token: - description: >- - Specifies the Telegram bot token. See - https://core.telegram.org/bots#creating-a-new-bot . + description: Specifies the Telegram bot token. See https://core.telegram.org/bots#creating-a-new-bot . type: string required: - token @@ -5243,27 +5045,20 @@ components: TelegramNotificationRuleBase: properties: disableWebPagePreview: - description: >- - Disables preview of web links in the sent messages when "true". - Defaults to "false". + description: Disables preview of web links in the sent messages when "true". Defaults to "false". type: boolean messageTemplate: description: The message template as a flux interpolated string. type: string parseMode: - description: >- - Parse mode of the message text per - https://core.telegram.org/bots/api#formatting-options. Defaults to - "MarkdownV2". + description: Parse mode of the message text per https://core.telegram.org/bots/api#formatting-options. Defaults to "MarkdownV2". enum: - MarkdownV2 - HTML - Markdown type: string type: - description: >- - The discriminator between other types of notification rules is - "telegram". + description: The discriminator between other types of notification rules is "telegram". enum: - telegram type: string @@ -5284,72 +5079,58 @@ components: kind: $ref: '#/components/schemas/TemplateKind' metadata: - description: > - Metadata properties used for the resource when the template is - applied. + description: | + Metadata properties used for the resource when the template is applied. properties: name: type: string type: object spec: - description: > - Configuration properties used for the resource when the template - is applied. - + description: | + Configuration properties used for the resource when the template is applied. Key-value pairs map to the specification for the resource. - - The following code samples show `spec` configurations for template - resources: - + The following code samples show `spec` configurations for template resources: - A bucket: - ```json - { "spec": { - "name": "iot_center", - "retentionRules": [{ - "everySeconds": 2.592e+06, - "type": "expire" - }] - } + ```json + { "spec": { + "name": "iot_center", + "retentionRules": [{ + "everySeconds": 2.592e+06, + "type": "expire" + }] } - ``` + } + ``` - A variable: - ```json - { "spec": { - "language": "flux", - "name": "Node_Service", - "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", - tag: \"service\")", - "type": "query" - } + ```json + { "spec": { + "language": "flux", + "name": "Node_Service", + "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", + tag: \"service\")", + "type": "query" } - ``` + } + ``` type: object type: object type: array TemplateApply: properties: actions: - description: > + description: | A list of `action` objects. + Actions let you customize how InfluxDB applies templates in the request. - Actions let you customize how InfluxDB applies templates in the - request. + You can use the following actions to prevent creating or updating resources: - - You can use the following actions to prevent creating or updating - resources: - - - - A `skipKind` action skips template resources of a specified - `kind`. - - - A `skipResource` action skips template resources with a specified - `metadata.name` + - A `skipKind` action skips template resources of a specified `kind`. + - A `skipResource` action skips template resources with a specified `metadata.name` and `kind`. items: oneOf: @@ -5384,14 +5165,11 @@ components: type: object type: array dryRun: - description: > + description: | Only applies a dry run of the templates passed in the request. - - Validates the template and generates a resource diff and summary. - - - Doesn't install templates or make changes to the InfluxDB - instance. + - Doesn't install templates or make changes to the InfluxDB instance. type: boolean envRefs: additionalProperties: @@ -5400,30 +5178,17 @@ components: - type: integer - type: number - type: boolean - description: > - An object with key-value pairs that map to **environment - references** in templates. - - - Environment references in templates are `envRef` objects with an - `envRef.key` + description: | + An object with key-value pairs that map to **environment references** in templates. + Environment references in templates are `envRef` objects with an `envRef.key` property. - - To substitute a custom environment reference value when applying - templates, - + To substitute a custom environment reference value when applying templates, pass `envRefs` with the `envRef.key` and the value. - - When you apply a template, InfluxDB replaces `envRef` objects in the - template - + When you apply a template, InfluxDB replaces `envRef` objects in the template with the values that you provide in the `envRefs` parameter. - - For more examples, see how to [define environment - references](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#define-environment-references). - + For more examples, see how to [define environment references](/influxdb/v2.3/influxdb-templates/use/#define-environment-references). The following template fields may use environment references: @@ -5431,25 +5196,17 @@ components: - `spec.endpointName` - `spec.associations.name` - For more information about including environment references in - template fields, see how to - - [include user-definable resource - names](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). + For more information about including environment references in template fields, see how to + [include user-definable resource names](/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names). type: object orgID: - description: > + description: | Organization ID. - InfluxDB applies templates to this organization. - The organization owns all resources created by the template. - To find your organization, see how to - - [view - organizations](https://docs.influxdata.com/influxdb/v2.3/organizations/view-orgs/). + [view organizations](/influxdb/v2.3/organizations/view-orgs/). type: string remotes: description: | @@ -5470,99 +5227,72 @@ components: secrets: additionalProperties: type: string - description: > + description: | An object with key-value pairs that map to **secrets** in queries. - Queries may reference secrets stored in InfluxDB--for example, - - the following Flux script retrieves `POSTGRES_USERNAME` and - `POSTGRES_PASSWORD` - + the following Flux script retrieves `POSTGRES_USERNAME` and `POSTGRES_PASSWORD` secrets and then uses them to connect to a PostgreSQL database: - ```js - import "sql" - import "influxdata/influxdb/secrets" + ```js + import "sql" + import "influxdata/influxdb/secrets" - username = secrets.get(key: "POSTGRES_USERNAME") - password = secrets.get(key: "POSTGRES_PASSWORD") + username = secrets.get(key: "POSTGRES_USERNAME") + password = secrets.get(key: "POSTGRES_PASSWORD") - sql.from( - driverName: "postgres", - dataSourceName: "postgresql://${username}:${password}@localhost:5432", - query: "SELECT * FROM example_table", - ) - ``` + sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost:5432", + query: "SELECT * FROM example_table", + ) + ``` To define secret values in your `/api/v2/templates/apply` request, - pass the `secrets` parameter with key-value pairs--for example: - ```json - { - ... - "secrets": { - "POSTGRES_USERNAME": "pguser", - "POSTGRES_PASSWORD": "foo" - } - ... + ```json + { + ... + "secrets": { + "POSTGRES_USERNAME": "pguser", + "POSTGRES_PASSWORD": "foo" } - ``` - - InfluxDB stores the key-value pairs as secrets that you can access - with `secrets.get()`. + ... + } + ``` + InfluxDB stores the key-value pairs as secrets that you can access with `secrets.get()`. Once stored, you can't view secret values in InfluxDB. - #### Related guides - - - [How to pass secrets when installing a - template](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) + - [How to pass secrets when installing a template](/influxdb/v2.3/influxdb-templates/use/#pass-secrets-when-installing-a-template) type: object stackID: - description: > + description: | ID of the stack to update. - - To apply templates to an existing stack in the organization, use the - `stackID` parameter. - + To apply templates to an existing stack in the organization, use the `stackID` parameter. If you apply templates without providing a stack ID, - InfluxDB initializes a new stack with all new resources. - - To find a stack ID, use the InfluxDB [`/api/v2/stacks` API - endpoint](#operation/ListStacks) to list stacks. - + To find a stack ID, use the InfluxDB [`/api/v2/stacks` API endpoint](#operation/ListStacks) to list stacks. #### Related guides - - - - [Stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/) - - - [View - stacks](https://docs.influxdata.com/influxdb/v2.3/influxdb-templates/stacks/view/) + - [Stacks](/influxdb/v2.3/influxdb-templates/stacks/) + - [View stacks](/influxdb/v2.3/influxdb-templates/stacks/view/) type: string template: - description: > + description: | A template object to apply. - A template object has a `contents` property - with an array of InfluxDB resource configurations. - Pass `template` to apply only one template object. - If you use `template`, you can't use the `templates` parameter. - - If you want to apply multiple template objects, use `templates` - instead. + If you want to apply multiple template objects, use `templates` instead. properties: contentType: type: string @@ -5611,9 +5341,7 @@ components: items: properties: defaultValue: - description: >- - Default value that will be provided for the reference when no - value is provided + description: Default value that will be provided for the reference when no value is provided nullable: true oneOf: - type: string @@ -5621,9 +5349,7 @@ components: - type: number - type: boolean envRefKey: - description: >- - Key identified as environment reference and is the key identified - in the template + description: Key identified as environment reference and is the key identified in the template type: string resourceField: description: Field the environment reference corresponds too @@ -5669,10 +5395,7 @@ components: kind: $ref: '#/components/schemas/TemplateKind' name: - description: >- - if defined with id, name is used for resource exported by id. - if defined independently, resources strictly matching name are - exported + description: if defined with id, name is used for resource exported by id. if defined independently, resources strictly matching name are exported type: string required: - id @@ -6457,15 +6180,20 @@ components: User: properties: id: + description: The user ID. readOnly: true type: string name: + description: The user name. type: string oauthID: + description: The OAuth ID. type: string status: default: active - description: If inactive the user is inactive. + description: | + If `inactive`, the user is inactive. + Default is `active`. enum: - active - inactive @@ -6476,7 +6204,7 @@ components: properties: id: description: | - The ID of the user. + The user ID. readOnly: true type: string links: @@ -6490,13 +6218,13 @@ components: type: object name: description: | - The name of the user. + The user name. type: string status: default: active - description: > - The status of a user. An inactive user won't have access to - resources. + description: | + The status of a user. + An inactive user can't read or write resources. enum: - active - inactive @@ -6778,60 +6506,44 @@ components: type: object securitySchemes: BasicAuthentication: - description: > - Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API - operations that support it. - + description: | + Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it. Username and password schemes require the following credentials: - - **username** - - **password** + + - **username** + - **password** scheme: basic type: http TokenAuthentication: - description: > - Use the [Token - authentication](#section/Authentication/TokenAuthentication) - + description: | + Use the [Token authentication](#section/Authentication/TokenAuthentication) scheme to authenticate to the InfluxDB API. - - In your API requests, send an `Authorization` header. - - For the header value, provide the word `Token` followed by a space and - an InfluxDB API token. - + For the header value, provide the word `Token` followed by a space and an InfluxDB API token. The word `Token` is case-sensitive. - - ### Syntax - - `Authorization: Token YOUR_INFLUX_API_TOKEN` - - + `Authorization: Token INFLUX_API_TOKEN` For more information and examples, see the following: - - [`/authorizations`](#tag/Authorizations) endpoint. - - [Authorize API requests](/influxdb/v2.3/api-guide/api_intro/#authentication). - - [Manage API tokens](/influxdb/v2.3/security/tokens/). + + - [`/authorizations`(#tag/Authorizations) endpoints] + - [Authorize API requests](/influxdb/v2.3/api-guide/api_intro/#authentication) + - [Manage API tokens](/influxdb/v2.3/security/tokens/) in: header name: Authorization type: apiKey info: title: InfluxDB OSS API Service version: 2.4.0 - description: > - The InfluxDB v2 API provides a programmatic interface for all interactions - with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. - + description: | + The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint. This documentation is generated from the - - [InfluxDB OpenAPI - specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.4.0/contracts/ref/oss.yml). + [InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.4.0/contracts/ref/oss.yml). openapi: 3.0.0 paths: /api/v2: @@ -6852,63 +6564,51 @@ paths: - System information endpoints /api/v2/authorizations: get: - description: > + description: | Retrieves a list of authorizations. - - To limit which authorizations are returned, pass query parameters in - your request. - + To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations. - #### InfluxDB OSS - - Returns [API token](/influxdb/v2.3/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator - token](/influxdb/latest/security/tokens/#operator-token)_, + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, InfluxDB OSS returns authorizations for all organizations in the instance. #### Required permissions - - - InfluxDB OSS requires an _[operator - token](/influxdb/latest/security/tokens/#operator-token)_. - + - InfluxDB OSS requires an _[operator token](/influxdb/latest/security/tokens/#operator-token)_. #### Related guides - - - [View tokens](/influxdb/v2.3/security/tokens/view-tokens/). + - [View tokens](/influxdb/v2.3/security/tokens/view-tokens/) operationId: GetAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns authorizations scoped to this user. + Only returns authorizations scoped to the specified [user](/influxdb/v2.3/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns authorizations scoped to this user. + Only returns authorizations scoped to the specified [user](/influxdb/v2.3/reference/glossary/#user). in: query name: user schema: type: string - - description: >- - An organization ID. Only returns authorizations that belong to this - organization. + - description: An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/v2.3/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns authorizations that belong to this organization. + Only returns authorizations that belong to the specified [organization](/influxdb/v2.3/reference/glossary/#organization). in: query name: org schema: @@ -6935,52 +6635,32 @@ paths: - Authorizations - Security and access endpoints post: - description: > + description: | Creates an authorization. - - Use this endpoint to create an authorization, which generates an API - token - - with permissions to `read` or `write` to a specific resource or `type` - of resource. - - The response contains the new authorization with the generated API - token. - + Use this endpoint to create an authorization, which generates an API token + with permissions to `read` or `write` to a specific resource or `type` of resource. + The response contains the new authorization with the generated API token. Keep the following in mind when creating and updating authorizations: - - - To apply a permission to a specific resource, specify the resource - `id` field. - - - To apply a permission to all resources with the type, omit the - resource `id`. - - - To scope an authorization to a specific user, provide the `userID` - property. - + - To apply a permission to a specific resource, specify the resource `id` field. + - To apply a permission to all resources with the type, omit the resource `id`. + - To scope an authorization to a specific user, provide the `userID` property. #### Limitations - - - In InfluxDB OSS, API tokens are visible to the user who created the - authorization and to any + - In InfluxDB OSS, API tokens are visible to the user who created the authorization and to any user with an _[operator token](/influxdb/v2.3/security/tokens/#operator-token)_. - Even if an API token has `read-authorizations` permission, the token can't be used to view its authorization details. - Tokens stop working when the user who created the token is deleted. - - We recommend creating a generic user to create and manage tokens for - writing data. - + We recommend creating a generic user to create and manage tokens for writing data. #### Related guides - - - [Create a token](/influxdb/v2.3/security/tokens/create-token/). + - [Create a token](/influxdb/v2.3/security/tokens/create-token/) operationId: PostAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7122,13 +6802,9 @@ paths: /api/v2/backup/kv: get: deprecated: true - description: > - Retrieves a snapshot of metadata stored in the server's embedded KV - store. - - InfluxDB versions greater than 2.1.x don't include metadata stored in - embedded SQL; - + description: | + Retrieves a snapshot of metadata stored in the server's embedded KV store. + InfluxDB versions greater than 2.1.x don't include metadata stored in embedded SQL; avoid using this endpoint with versions greater than 2.1.x. operationId: GetBackupKV parameters: @@ -7144,9 +6820,7 @@ paths: default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: >- - Download snapshot of metadata stored in the server's embedded KV store. - Don't use with InfluxDB versions greater than InfluxDB 2.1.x. + summary: Download snapshot of metadata stored in the server's embedded KV store. Don't use with InfluxDB versions greater than InfluxDB 2.1.x. tags: - Backup /api/v2/backup/metadata: @@ -7154,16 +6828,12 @@ paths: operationId: GetBackupMetadata parameters: - $ref: '#/components/parameters/TraceSpan' - - description: >- - Indicates the content encoding (usually a compression algorithm) - that the client can understand. + - description: Indicates the content encoding (usually a compression algorithm) that the client can understand. in: header name: Accept-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -7177,14 +6847,11 @@ paths: description: Snapshot of metadata headers: Content-Encoding: - description: >- - Lists any encodings (usually compression algorithms) that have - been applied to the response payload. + description: Lists any encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity - description: > - The content coding: `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -7200,16 +6867,12 @@ paths: operationId: GetBackupShardId parameters: - $ref: '#/components/parameters/TraceSpan' - - description: >- - Indicates the content encoding (usually a compression algorithm) - that the client can understand. + - description: Indicates the content encoding (usually a compression algorithm) that the client can understand. in: header name: Accept-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -7221,10 +6884,7 @@ paths: schema: format: int64 type: integer - - description: >- - The earliest time [RFC3339 date/time - format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) to - include in the snapshot. + - description: The earliest time [RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp) to include in the snapshot. examples: RFC3339: summary: RFC3339 date/time format @@ -7244,14 +6904,11 @@ paths: description: TSM snapshot. headers: Content-Encoding: - description: >- - Lists any encodings (usually compression algorithms) that have - been applied to the response payload. + description: Lists any encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity - description: > - The content coding: `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -7270,33 +6927,23 @@ paths: - Backup /api/v2/buckets: get: - description: > - Retrieves a list of - [buckets](/influxdb/v2.3/reference/glossary/#bucket). - - - To limit which buckets are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all buckets up to - the + description: | + Retrieves a list of [buckets](/influxdb/v2.3/reference/glossary/#bucket). + To limit which buckets are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all buckets up to the default `limit`. - #### Limitations - - - Paging with an `offset` greater than the number of records will result - in - + - Paging with an `offset` greater than the number of records will result in an empty list of buckets--for example: The following request is paging to the 50th record, but the user only has 10 buckets. ```sh - $ curl --request GET "INFLUX_URL/api/v2/scripts?limit=1&offset=50" + $ curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" $ { "links": { @@ -7309,7 +6956,6 @@ paths: #### Related Guides - - [Manage buckets](/influxdb/v2.3/organizations/buckets/) operationId: GetBuckets parameters: @@ -7393,8 +7039,7 @@ paths: type: system updatedAt: '2022-03-15T17:22:33.726179487Z' links: - self: >- - /api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID + self: /api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID schema: $ref: '#/components/schemas/Buckets' description: | @@ -7416,56 +7061,36 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "http://localhost:8086/api/v2/buckets?name=_monitoring" \ + source: | + curl --request GET "http://localhost:8086/api/v2/buckets?name=_monitoring" \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" post: - description: > + description: | Creates a [bucket](/influxdb/v2.3/reference/glossary/#bucket) - and returns the created bucket along with metadata. The default data - [retention period](/influxdb/v2.3/reference/glossary/#retention-period) - is 30 days. - #### InfluxDB OSS - - A single InfluxDB OSS instance supports active writes or queries for - - approximately 20 buckets across all organizations at a given time. - Reading - + approximately 20 buckets across all organizations at a given time. Reading or writing to more than 20 buckets at a time can adversely affect - performance. - #### Limitations - - InfluxDB Cloud Free Plan allows users to create up to two buckets. - Exceeding the bucket quota will result in an HTTP `403` status code. - For additional information regarding InfluxDB Cloud offerings, see - - [InfluxDB Cloud - Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). - + [InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). #### Related Guides - - [Create bucket](/influxdb/v2.3/organizations/buckets/create-bucket/) - - - [Create bucket CLI - reference](/influxdb/v2.3/reference/cli/influx/bucket/create) + - [Create bucket CLI reference](/influxdb/v2.3/reference/cli/influx/bucket/create) operationId: PostBuckets parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7577,13 +7202,11 @@ paths: }' /api/v2/buckets/{bucketID}: delete: - description: > + description: | Deletes a bucket and all associated records. - #### InfluxDB Cloud - - Does the following when you send a delete request: 1. Validates the request and queues the delete. @@ -7592,23 +7215,16 @@ paths: #### InfluxDB OSS - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - #### Limitations - - Only one bucket can be deleted per request. - #### Related Guides - - - [Delete a - bucket](/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + - [Delete a bucket](/influxdb/v2.3/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) operationId: DeleteBucketsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7675,9 +7291,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request DELETE - "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ + source: | + curl --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ --header "Authorization: Token INFLUX_TOKEN" \ --header 'Accept: application/json' get: @@ -7755,34 +7370,23 @@ paths: tags: - Buckets patch: - description: > + description: | Updates a bucket. - Use this endpoint to update properties - (`name`, `description`, and `retentionRules`) of a bucket. - #### InfluxDB Cloud - - - Requires the `retentionRules` property in the request body. If you - don't - - provide `retentionRules`, InfluxDB responds with an HTTP `403` status - code. - + - Requires the `retentionRules` property in the request body. If you don't + provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. #### InfluxDB OSS - - Doesn't require `retentionRules`. - #### Related Guides - - [Update a bucket](/influxdb/v2.3/organizations/buckets/update-bucket/) operationId: PatchBucketsID parameters: @@ -7834,17 +7438,13 @@ paths: application/json: examples: invalidJSONStringValue: - description: > - If the request body contains invalid JSON, InfluxDB returns - `invalid` - + description: | + If the request body contains invalid JSON, InfluxDB returns `invalid` with detail about the problem. summary: Invalid JSON value: code: invalid - message: >- - invalid json: invalid character '\'' looking for beginning - of value + message: 'invalid json: invalid character ''\'''' looking for beginning of value' schema: $ref: '#/components/schemas/Error' description: | @@ -7856,10 +7456,8 @@ paths: application/json: examples: invalidRetention: - summary: > - The retention policy provided exceeds the max retention for - the - + summary: | + The retention policy provided exceeds the max retention for the organization. value: code: forbidden @@ -7897,9 +7495,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID - \ + source: | + curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -7915,34 +7512,20 @@ paths: }' /api/v2/buckets/{bucketID}/labels: get: - description: > + description: | Retrieves a list of all labels for a bucket. - - Labels are objects that contain `labelID`, `name`, `description`, and - `color` - + Labels are objects that contain `labelID`, `name`, `description`, and `color` key-value pairs. They may be used for grouping and filtering InfluxDB - resources. - - Labels are also capable of grouping across different resources--for - example, - - you can apply a label named `air_sensor` to a bucket and a task to - quickly - + Labels are also capable of grouping across different resources--for example, + you can apply a label named `air_sensor` to a bucket and a task to quickly organize resources. - #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to - retrieve and manage labels. - - - [Manage labels in the InfluxDB - UI](/influxdb/v2.3/visualize-data/labels/) + - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - [Manage labels in the InfluxDB UI](/influxdb/v2.3/visualize-data/labels/) operationId: GetBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -7989,36 +7572,24 @@ paths: tags: - Buckets post: - description: > + description: | Adds a label to a bucket and returns the new label information. - - Labels are objects that contain `labelID`, `name`, `description`, and - `color` - - key-value pairs. They may be used for grouping and filtering across one - or - + Labels are objects that contain `labelID`, `name`, `description`, and `color` + key-value pairs. They may be used for grouping and filtering across one or more kinds of **resources**--for example, you can apply a label named - `air_sensor` to a bucket and a task to quickly organize resources. - #### Limitations - - Before adding a label to a bucket, you must create the label if you haven't already. To create a label with the InfluxDB API, send a `POST` request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to - retrieve and manage labels. - - - [Manage labels in the InfluxDB - UI](/influxdb/v2.3/visualize-data/labels/) + - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - [Manage labels in the InfluxDB UI](/influxdb/v2.3/visualize-data/labels/) operationId: PostBucketsIDLabels parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8096,9 +7667,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ --header "Authorization: Token INFLUX_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -8266,7 +7836,7 @@ paths: $ref: '#/components/responses/BadRequestError' examples: invalidRequest: - summary: The `userID` is missing from the request body. + summary: The user `id` is missing from the request body. value: code: invalid message: user id missing or invalid @@ -8288,10 +7858,9 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ - --header "Authorization: Token INFLUX_TOKEN" \ + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ + --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{ @@ -8299,21 +7868,15 @@ paths: } /api/v2/buckets/{bucketID}/members/{userID}: delete: - description: > + description: | Removes a member from a bucket. - - Use this endpoint to remove a user's member privileges from a bucket. - This - + Use this endpoint to remove a user's member privileges from a bucket. This removes the user's `read` and `write` permissions for the bucket. - #### Related guides - - [Manage users](/influxdb/v2.3/users/) - - [Manage members](/influxdb/v2.3/organizations/members/) operationId: DeleteBucketsIDMembersID parameters: @@ -8354,10 +7917,42 @@ paths: - Buckets /api/v2/buckets/{bucketID}/owners: get: + description: | + Retrieves a list of all [owners](/influxdb/v2.3/reference/glossary/#owner) + for a bucket. + + Bucket owners have permission to delete buckets and remove user and member + permissions from the bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `read-orgs INFLUX_ORG_ID` + + `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve a + list of owners for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) + + #### Related guides + + - [Manage users](/influxdb/v2.3/users/) operationId: GetBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. + - description: | + The ID of the bucket to retrieve owners for. in: path name: bucketID required: true @@ -8367,9 +7962,31 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/buckets/BUCKET_ID/owners + users: + - id: d88d182d91b0950f + links: + self: /api/v2/users/d88d182d91b0950f + name: example-owner + role: owner + status: active schema: $ref: '#/components/schemas/ResourceOwners' - description: A list of bucket owners + description: | + Success. + The response body contains a list of all owners for the bucket. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -8380,10 +7997,41 @@ paths: tags: - Buckets post: + description: | + Adds an owner to a bucket and returns the [owners](/influxdb/v2.3/reference/glossary/#owner) + with role and user detail. + + Use this endpoint to create a _resource owner_ for the bucket. + Bucket owners have permission to delete buckets and remove user and member + permissions from the bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + `INFLUX_ORG_ID` is the ID of the organization that you want add an owner for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) + + #### Related guides + + - [Manage users](/influxdb/v2.3/users/) operationId: PostBucketsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. + - description: | + The ID of the bucket to add an owner for. in: path name: bucketID required: true @@ -8392,9 +8040,18 @@ paths: requestBody: content: application/json: + examples: + successResponse: + value: + id: d88d182d91b0950f + links: + self: /api/v2/users/d88d182d91b0950f + name: example-user + role: owner + status: active schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner + description: A user to add as an owner for the bucket. required: true responses: '201': @@ -8402,7 +8059,25 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceOwner' - description: Success. The user is an owner of the bucket + description: | + Created. + The bucket `owner` role is assigned to the user. + The response body contains the resource owner with + role and user detail. + '400': + $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The user `id` is missing from the request body. + value: + code: invalid + message: user id missing or invalid + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -8412,18 +8087,59 @@ paths: summary: Add an owner to a bucket tags: - Buckets + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/owners \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + } /api/v2/buckets/{bucketID}/owners/{userID}: delete: + description: | + Removes an owner from a bucket. + + Use this endpoint to remove a user's `owner` role for a bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + `INFLUX_ORG_ID` is the ID of the organization that you want to remove an owner + from. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) + + #### Related guides + + - [Manage users](/influxdb/v2.3/users/) operationId: DeleteBucketsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. + - description: | + The ID of the owner to remove. in: path name: userID required: true schema: type: string - - description: The bucket ID. + - description: | + The ID of the bucket to remove an owner from. in: path name: bucketID required: true @@ -8431,7 +8147,15 @@ paths: type: string responses: '204': - description: Owner removed + description: | + Success. + The user is no longer an owner of the bucket. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -8764,21 +8488,15 @@ paths: - Checks /api/v2/config: get: - description: > + description: | Returns the active runtime configuration of the InfluxDB instance. - - In InfluxDB v2.2+, use this endpoint to view your active runtime - configuration, - + In InfluxDB v2.2+, use this endpoint to view your active runtime configuration, including flags and environment variables. - #### Related guides - - - [View your runtime server - configuration](/influxdb/v2.3/reference/config-options/#view-your-runtime-server-configuration) + - [View your runtime server configuration](/influxdb/v2.3/reference/config-options/#view-your-runtime-server-configuration) operationId: GetConfig parameters: - $ref: '#/components/parameters/TraceSpan' @@ -8788,11 +8506,9 @@ paths: application/json: schema: $ref: '#/components/schemas/Config' - description: > + description: | Success. - - The response body contains the active runtime configuration of the - InfluxDB instance. + The response body contains the active runtime configuration of the InfluxDB instance. '401': $ref: '#/components/responses/GeneralServerError' default: @@ -8809,9 +8525,7 @@ paths: - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Descending' - - description: >- - A user identifier. Returns only dashboards where this user has the - `owner` role. + - description: A user identifier. Returns only dashboards where this user has the `owner` role. in: query name: owner schema: @@ -8825,9 +8539,7 @@ paths: - CreatedAt - UpdatedAt type: string - - description: >- - A list of dashboard identifiers. Returns only the listed dashboards. - If both `id` and `owner` are specified, only `id` is used. + - description: A list of dashboard identifiers. Returns only the listed dashboards. If both `id` and `owner` are specified, only `id` is used. in: query name: id schema: @@ -8977,9 +8689,7 @@ paths: properties: cells: $ref: '#/components/schemas/CellWithViewProperties' - description: >- - optional, when provided will replace all existing cells with - the cells provided + description: optional, when provided will replace all existing cells with the cells provided description: description: optional, when provided will replace the description type: string @@ -9054,9 +8764,7 @@ paths: - Cells - Dashboards put: - description: >- - Replaces all cells in a dashboard. This is used primarily to update the - positional information of all cells. + description: Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells. operationId: PutDashboardsIDCells parameters: - $ref: '#/components/parameters/TraceSpan' @@ -9132,9 +8840,7 @@ paths: - Cells - Dashboards patch: - description: >- - Updates the non positional information related to a cell. Updates to a - single cell's positional data could cause grid conflicts. + description: Updates the non positional information related to a cell. Updates to a single cell's positional data could cause grid conflicts. operationId: PatchDashboardsIDCellsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -9772,40 +9478,29 @@ paths: - DBRPs /debug/pprof/all: get: - description: > - Collects samples and returns reports for the following [Go runtime - profiles](https://pkg.go.dev/runtime/pprof): - + description: | + Collects samples and returns reports for the following [Go runtime profiles](https://pkg.go.dev/runtime/pprof): - **allocs**: All past memory allocations - - - **block**: Stack traces that led to blocking on synchronization - primitives - + - **block**: Stack traces that led to blocking on synchronization primitives - **cpu**: (Optional) Program counters sampled from the executing stack. Include by passing the `cpu` query parameter with a [duration](/influxdb/v2.3/reference/glossary/#duration) value. Equivalent to the report from [`GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS`](#operation/GetDebugPprofProfile). - **goroutine**: All current goroutines - - **heap**: Memory allocations for live objects - - **mutex**: Holders of contended mutexes - - - **threadcreate**: Stack traces that led to the creation of new OS - threads + - **threadcreate**: Stack traces that led to the creation of new OS threads operationId: GetDebugPprofAllProfiles parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - Collects and returns CPU profiling data for the specified - [duration](/influxdb/v2.3/reference/glossary/#duration). + - description: | + Collects and returns CPU profiling data for the specified [duration](/influxdb/v2.3/reference/glossary/#duration). in: query name: cpu schema: externalDocs: description: InfluxDB duration - url: >- - https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration + url: https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration format: duration type: string responses: @@ -9813,11 +9508,9 @@ paths: content: application/octet-stream: schema: - description: > + description: | GZIP compressed TAR file (`.tar.gz`) that contains - - [Go runtime profile](https://pkg.go.dev/runtime/pprof) - reports. + [Go runtime profile](https://pkg.go.dev/runtime/pprof) reports. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -9836,32 +9529,21 @@ paths: x-codeSamples: - label: 'Shell: Get all profiles' lang: Shell - source: > - # Download and extract a `tar.gz` of all profiles after 10 seconds - of CPU sampling. - + source: | + # Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling. curl "http://localhost:8086/debug/pprof/all?cpu=10s" | tar -xz - # x profiles/cpu.pb.gz - # x profiles/goroutine.pb.gz - # x profiles/block.pb.gz - # x profiles/mutex.pb.gz - # x profiles/heap.pb.gz - # x profiles/allocs.pb.gz - # x profiles/threadcreate.pb.gz - # Analyze a profile. - go tool pprof profiles/heap.pb.gz - label: 'Shell: Get all profiles except CPU' lang: Shell @@ -9882,29 +9564,19 @@ paths: go tool pprof profiles/heap.pb.gz /debug/pprof/allocs: get: - description: > - Returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - of - + description: | + Returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of all past memory allocations. - **allocs** is the same as the **heap** profile, - but changes the default [pprof](https://pkg.go.dev/runtime/pprof) - display to __-alloc_space__, - - the total number of bytes allocated since the program began (including - garbage-collected bytes). + the total number of bytes allocated since the program began (including garbage-collected bytes). operationId: GetDebugPprofAllocs parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - - `0`: (Default) Return the report as a gzip-compressed protocol - buffer. - - - `1`: Return a response body with the report formatted as - human-readable text. + - description: | + - `0`: (Default) Return the report as a gzip-compressed protocol buffer. + - `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. @@ -9930,9 +9602,8 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -9949,15 +9620,10 @@ paths: url: https://pkg.go.dev/net/http/pprof format: Go runtime profile type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. - - If debug is enabled (`?debug=1`), response body contains a - human-readable profile. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. + If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -9969,42 +9635,29 @@ paths: x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell - source: > + source: | # Analyze the profile in interactive mode. - go tool pprof http://localhost:8086/debug/pprof/allocs - # `pprof` returns the following prompt: - - # Entering interactive mode (type "help" for commands, "o" for - options) - + # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) - # At the prompt, get the top N memory allocations. - (pprof) top10 /debug/pprof/block: get: - description: > - Collects samples and returns a [Go runtime - profile](https://pkg.go.dev/runtime/pprof) - - report of stack traces that led to blocking on synchronization - primitives. + description: | + Collects samples and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) + report of stack traces that led to blocking on synchronization primitives. operationId: GetDebugPprofBlock parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - - `0`: (Default) Return the report as a gzip-compressed protocol - buffer. - - - `1`: Return a response body with the report formatted as - human-readable text. + - description: | + - `0`: (Default) Return the report as a gzip-compressed protocol buffer. + - `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. @@ -10030,9 +9683,8 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -10049,15 +9701,10 @@ paths: url: https://pkg.go.dev/net/http/pprof format: Go runtime profile type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. - - If debug is enabled (`?debug=1`), response body contains a - human-readable profile. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. + If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -10069,24 +9716,17 @@ paths: x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell - source: > + source: | # Analyze the profile in interactive mode. - go tool pprof http://localhost:8086/debug/pprof/block - # `pprof` returns the following prompt: - - # Entering interactive mode (type "help" for commands, "o" for - options) - + # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) - # At the prompt, get the top N entries. - (pprof) top10 /debug/pprof/cmdline: get: @@ -10113,18 +9753,14 @@ paths: - System information endpoints /debug/pprof/goroutine: get: - description: > - Collects statistics and returns a [Go runtime - profile](https://pkg.go.dev/runtime/pprof) - + description: | + Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of all current goroutines. operationId: GetDebugPprofGoroutine parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - - `0`: (Default) Return the report as a gzip-compressed protocol - buffer. - + - description: | + - `0`: (Default) Return the report as a gzip-compressed protocol buffer. - `1`: Return a response body with the report formatted as human-readable text with comments that translate addresses to function names and line numbers for debugging. @@ -10152,9 +9788,8 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -10171,15 +9806,10 @@ paths: url: https://pkg.go.dev/net/http/pprof format: Go runtime profile type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. - - If debug is enabled (`?debug=1`), response body contains a - human-readable profile. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. + If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -10191,46 +9821,32 @@ paths: x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell - source: > + source: | # Analyze the profile in interactive mode. - go tool pprof http://localhost:8086/debug/pprof/goroutine - # `pprof` returns the following prompt: - - # Entering interactive mode (type "help" for commands, "o" for - options) - + # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) - # At the prompt, get the top N entries. - (pprof) top10 /debug/pprof/heap: get: - description: > - Collects statistics and returns a [Go runtime - profile](https://pkg.go.dev/runtime/pprof) - + description: | + Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of memory allocations for live objects. - To run **garbage collection** before sampling, - pass the `gc` query parameter with a value of `1`. operationId: GetDebugPprofHeap parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - - `0`: (Default) Return the report as a gzip-compressed protocol - buffer. - - - `1`: Return a response body with the report formatted as - human-readable text. + - description: | + - `0`: (Default) Return the report as a gzip-compressed protocol buffer. + - `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. @@ -10267,9 +9883,8 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -10290,15 +9905,10 @@ paths: url: https://pkg.go.dev/net/http/pprof format: Go runtime profile type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. - - If debug is enabled (`?debug=1`), response body contains a - human-readable profile. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. + If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -10310,53 +9920,35 @@ paths: x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell - source: > + source: | # Analyze the profile in interactive mode. - go tool pprof http://localhost:8086/debug/pprof/heap - # `pprof` returns the following prompt: - - # Entering interactive mode (type "help" for commands, "o" for - options) - + # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) - # At the prompt, get the top N memory-intensive nodes. - (pprof) top10 - # pprof displays the list: - # Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total - # Dropped 895 nodes (cum <= 0.83MB) - # Showing top 10 nodes out of 143 /debug/pprof/mutex: get: - description: > - Collects statistics and returns a [Go runtime - profile](https://pkg.go.dev/runtime/pprof) report of - + description: | + Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of lock contentions. - - The profile contains stack traces of holders of contended mutual - exclusions (mutexes). + The profile contains stack traces of holders of contended mutual exclusions (mutexes). operationId: GetDebugPprofMutex parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - - `0`: (Default) Return the report as a gzip-compressed protocol - buffer. - - - `1`: Return a response body with the report formatted as - human-readable text. + - description: | + - `0`: (Default) Return the report as a gzip-compressed protocol buffer. + - `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. @@ -10382,9 +9974,8 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -10401,15 +9992,10 @@ paths: url: https://pkg.go.dev/net/http/pprof format: Go runtime profile type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. - - If debug is enabled (`?debug=1`), response body contains a - human-readable profile. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. + If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -10421,31 +10007,22 @@ paths: x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell - source: > + source: | # Analyze the profile in interactive mode. - go tool pprof http://localhost:8086/debug/pprof/mutex - # `pprof` returns the following prompt: - - # Entering interactive mode (type "help" for commands, "o" for - options) - + # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) - # At the prompt, get the top N entries. - (pprof) top10 /debug/pprof/profile: get: - description: > - Collects statistics and returns a [Go runtime - profile](https://pkg.go.dev/runtime/pprof) - + description: | + Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of program counters on the executing stack. operationId: GetDebugPprofProfile parameters: @@ -10461,20 +10038,16 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof format: binary type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -10501,20 +10074,15 @@ paths: (pprof) top10 /debug/pprof/threadcreate: get: - description: > - Collects statistics and returns a [Go runtime - profile](https://pkg.go.dev/runtime/pprof) - + description: | + Collects statistics and returns a [Go runtime profile](https://pkg.go.dev/runtime/pprof) report of stack traces that led to the creation of new OS threads. operationId: GetDebugPprofThreadCreate parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - - `0`: (Default) Return the report as a gzip-compressed protocol - buffer. - - - `1`: Return a response body with the report formatted as - human-readable text. + - description: | + - `0`: (Default) Return the report as a gzip-compressed protocol buffer. + - `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter. @@ -10540,9 +10108,8 @@ paths: content: application/octet-stream: schema: - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - in protocol buffer format. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report in protocol buffer format. externalDocs: description: Golang pprof package url: https://pkg.go.dev/net/http/pprof @@ -10563,15 +10130,10 @@ paths: url: https://pkg.go.dev/net/http/pprof format: Go runtime profile type: string - description: > - [Go runtime profile](https://pkg.go.dev/runtime/pprof) report - compatible - - with [pprof](https://github.com/google/pprof) analysis and - visualization tools. - - If debug is enabled (`?debug=1`), response body contains a - human-readable profile. + description: | + [Go runtime profile](https://pkg.go.dev/runtime/pprof) report compatible + with [pprof](https://github.com/google/pprof) analysis and visualization tools. + If debug is enabled (`?debug=1`), response body contains a human-readable profile. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -10583,30 +10145,22 @@ paths: x-codeSamples: - label: 'Shell: go tool pprof' lang: Shell - source: > + source: | # Analyze the profile in interactive mode. - go tool pprof http://localhost:8086/debug/pprof/threadcreate - # `pprof` returns the following prompt: - - # Entering interactive mode (type "help" for commands, "o" for - options) - + # Entering interactive mode (type "help" for commands, "o" for options) # (pprof) - # At the prompt, get the top N entries. - (pprof) top10 /debug/pprof/trace: get: - description: > - Collects profile data and returns trace execution events for the current - program. + description: | + Collects profile data and returns trace execution events for the current program. operationId: GetDebugPprofTrace parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10650,17 +10204,13 @@ paths: go tool trace ./trace /api/v2/delete: post: - description: > + description: | Deletes data from a bucket. - - Use this endpoint to delete points from a bucket in a specified time - range. - + Use this endpoint to delete points from a bucket in a specified time range. #### InfluxDB Cloud - - Does the following when you send a delete request: 1. Validates the request and queues the delete. @@ -10669,103 +10219,74 @@ paths: #### InfluxDB OSS - - Validates the request, handles the delete synchronously, and then responds with success or failure. #### Required permissions - - `write-buckets` or `write-bucket BUCKET_ID`. `BUCKET_ID` is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) - `write` rate limits apply. - - For more information, see [limits and adjustable - quotas](/influxdb/cloud/account-management/limits/). - + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - - [Delete data](/influxdb/v2.3/write-data/delete-data/). - - - Learn how to use [delete predicate - syntax](/influxdb/v2.3/reference/syntax/delete-predicate/). - - - Learn how InfluxDB handles [deleted - tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) + - [Delete data](/influxdb/v2.3/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/v2.3/reference/syntax/delete-predicate/). + - Learn how InfluxDB handles [deleted tags](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementtagkeys/) and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). operationId: PostDelete parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > + - description: | The organization to delete data from. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Deletes data from the bucket in the organization associated with - the authorization (API token). - + - Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: org schema: description: The organization name or ID. type: string - - description: > + - description: | The name or ID of the bucket to delete data from. - - If you pass both `bucket` and `bucketID`, `bucketID` takes - precedence. + If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. in: query name: bucket schema: description: The bucket name or ID. type: string - - description: > + - description: | The ID of the organization to delete data from. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Deletes data from the bucket in the organization associated with - the authorization (API token). - + - Deletes data from the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: orgID schema: description: The organization ID. type: string - - description: > + - description: | The ID of the bucket to delete data from. - - If you pass both `bucket` and `bucketID`, `bucketID` takes - precedence. + If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. in: query name: bucketID schema: @@ -10776,61 +10297,38 @@ paths: application/json: schema: $ref: '#/components/schemas/DeletePredicateRequest' - description: > + description: | Time range parameters and an optional **delete predicate expression**. - To select points to delete within the specified time range, pass a - - **delete predicate expression** in the `predicate` property of the - request body. - - If you don't pass a `predicate`, InfluxDB deletes all data with - timestamps - + **delete predicate expression** in the `predicate` property of the request body. + If you don't pass a `predicate`, InfluxDB deletes all data with timestamps in the specified time range. - #### Related guides - - - [Delete data](/influxdb/v2.3/write-data/delete-data/). - - - Learn how to use [delete predicate - syntax](/influxdb/v2.3/reference/syntax/delete-predicate/). + - [Delete data](/influxdb/v2.3/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/v2.3/reference/syntax/delete-predicate/). required: true responses: '204': - description: > + description: | Success. - #### InfluxDB Cloud - - Validated and queued the request. + - Handles the delete asynchronously - the deletion might not have completed yet. - - Handles the delete asynchronously - the deletion might not have - completed yet. - - - An HTTP `2xx` status code acknowledges that the write or delete is - queued. - - To ensure that InfluxDB Cloud handles writes and deletes in the - order you request them, - + An HTTP `2xx` status code acknowledges that the write or delete is queued. + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request. - Because writes are asynchronous, data might not yet be written - when you receive the response. - #### InfluxDB OSS - - Deleted the data. '400': content: @@ -10843,17 +10341,13 @@ paths: 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` doesn't match an - organization. + - Returns this error if `org` or `orgID` doesn't match an organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -10869,9 +10363,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ + source: | + curl --request POST INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ --header 'Authorization: Token INFLUX_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ @@ -11088,9 +10581,7 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: >- - Success. The response body contains the currently authenticated - user. + description: Success. The response body contains the currently authenticated user. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -11103,13 +10594,50 @@ paths: /api/v2/me/password: put: description: | + Updates the password for the signed-in [user](/influxdb/v2.3/reference/glossary/#user). + + This endpoint represents the third step in the following three-step process to let a + user with a user session update their password: + 1. Pass the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) to the `POST /api/v2/signin` + endpoint to create a user session and generate a session cookie. + 2. From the response in the first step, extract the session cookie (`Set-Cookie`) header. + 3. Pass the following in a request to the `PUT /api/v2/me/password` endpoint: + - The `Set-Cookie` header from the second step + - The `Authorization Basic` header with the user's _Basic authentication_ credentials + - `{"password": "NEW_PASSWORD"}` in the request body + #### InfluxDB Cloud - InfluxDB Cloud doesn't support changing user passwords through the API. - Use the InfluxDB Cloud user interface to update your password. + - Doesn't allow you to manage passwords through the API. + Use the InfluxDB Cloud user interface (UI) to update your password. + + #### Related endpoints + + - [Signin](#tag/Signin) + - [Signout](#tag/Signout) + - [Users](#tag/Users) + + #### Related guides + + - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) operationId: PutMePassword parameters: - $ref: '#/components/parameters/TraceSpan' + - description: | + The user session cookie for the + [user](/influxdb/v2.3/reference/glossary/#user) + signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). + + #### Related guides + + - [Manage users](/influxdb/v2.4/users/) + example: influxdb-oss-session=19aaaZZZGOvP2GGryXVT2qYftlFKu3bIopurM6AGFow1yF1abhtOlbHfsc-d8gozZFC_6WxmlQIAwLMW5xs523w== + in: cookie + name: influxdb-oss-session + required: true + schema: + type: string requestBody: content: application/json: @@ -11119,13 +10647,20 @@ paths: required: true responses: '204': - description: Success. The password was updated. + description: Success. The password is updated. '400': - description: > + description: | Bad request. - InfluxDB Cloud doesn't support changing passwords through the API - and always responds with this status. + #### InfluxDB Cloud + + - Doesn't allow you to manage through the API; always responds with this status. + + #### InfluxDB OSS + + - Doesn't understand a value passed in the request. + '401': + $ref: '#/components/responses/AuthorizationError' default: content: application/json: @@ -11139,24 +10674,16 @@ paths: - Users /metrics: get: - description: > + description: | Returns metrics about the workload performance of an InfluxDB instance. - Use this endpoint to get performance, resource, and usage metrics. - #### Related guides - - - For the list of metrics categories, see [InfluxDB OSS - metrics](/influxdb/v2.3/reference/internals/metrics/). - - - Learn how to use InfluxDB to [scrape Prometheus - 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/). + - For the list of metrics categories, see [InfluxDB OSS metrics](/influxdb/v2.3/reference/internals/metrics/). + - Learn how to use InfluxDB to [scrape Prometheus 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/). operationId: GetMetrics parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11167,50 +10694,30 @@ paths: examples: expositionResponse: summary: Metrics in plain text - value: > + value: | # HELP go_threads Number of OS threads created. - # TYPE go_threads gauge - go_threads 19 - - # HELP http_api_request_duration_seconds Time taken to - respond to HTTP request - + # HELP http_api_request_duration_seconds Time taken to respond to HTTP request # TYPE http_api_request_duration_seconds histogram - - http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.005"} - 4 - - http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.01"} - 4 - - http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.025"} - 5 + http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.005"} 4 + http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.01"} 4 + http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.025"} 5 schema: externalDocs: description: Prometheus exposition formats url: https://prometheus.io/docs/instrumenting/exposition_formats format: Prometheus text-based exposition type: string - description: > + description: | Success. The response body contains metrics in - - [Prometheus plain-text exposition - format](https://prometheus.io/docs/instrumenting/exposition_formats) - - Metrics contain a name, an optional set of key-value pairs, and a - value. - + [Prometheus plain-text exposition format](https://prometheus.io/docs/instrumenting/exposition_formats) + Metrics contain a name, an optional set of key-value pairs, and a value. The following descriptors precede each metric: - - `HELP`: description of the metric - - - `TYPE`: [Prometheus metric - type](https://prometheus.io/docs/concepts/metric_types/) (`counter`, - `gauge`, `histogram`, or `summary`) + - `TYPE`: [Prometheus metric type](https://prometheus.io/docs/concepts/metric_types/) (`counter`, `gauge`, `histogram`, or `summary`) default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -11226,9 +10733,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - - description: >- - Only show notification endpoints that belong to specific - organization ID. + - description: Only show notification endpoints that belong to specific organization ID. in: query name: orgID required: true @@ -11510,9 +11015,7 @@ paths: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - - description: >- - Only show notification rules that belong to a specific organization - ID. + - description: Only show notification rules that belong to a specific organization ID. in: query name: orgID required: true @@ -11523,9 +11026,7 @@ paths: name: checkID schema: type: string - - description: >- - Only return notification rules that "would match" statuses which - contain the tag key value pairs provided. + - description: Only return notification rules that "would match" statuses which contain the tag key value pairs provided. in: query name: tag schema: @@ -11842,29 +11343,19 @@ paths: - Rules /api/v2/orgs: get: - description: > - Retrieves a list of - [organizations](/influxdb/v2.3/reference/glossary/#organization/). - - - To limit which organizations are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all organizations up - to the default `limit`. + description: | + Retrieves a list of [organizations](/influxdb/v2.3/reference/glossary/#organization/). + To limit which organizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. #### InfluxDB Cloud - - - Only returns the organization that owns the token passed in the - request. - + - Only returns the organization that owns the token passed in the request. #### Related guides - - - [View organizations](/influxdb/v2.3/organizations/view-orgs/). + - [View organizations](/influxdb/v2.3/organizations/view-orgs/) operationId: GetOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11935,22 +11426,16 @@ paths: - Organizations - Security and access endpoints post: - description: > - Creates an - [organization](/influxdb/v2.3/reference/glossary/#organization) - + description: | + Creates an [organization](/influxdb/v2.3/reference/glossary/#organization) and returns the newly created organization. - #### InfluxDB Cloud - - Doesn't allow you to use this endpoint to create organizations. - #### Related guides - - [Manage organizations](/influxdb/v2.3/organizations) operationId: PostOrgs parameters: @@ -12049,7 +11534,7 @@ paths: #### Related guides - - [Delete organization](/influxdb/v2.3/organizations/delete-orgs/) + - [Delete organizations](/influxdb/v2.3/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12108,7 +11593,7 @@ paths: #### Related guides - - [View organization](/influxdb/v2.3/organizations/view-orgs/) + - [View organizations](/influxdb/v2.3/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12158,40 +11643,26 @@ paths: - Organizations - Security and access endpoints patch: - description: > + description: | Updates an organization. - Use this endpoint to update properties - (`name`, `description`) of an organization. - Updating an organization’s name affects all resources that reference the - organization by name, including the following: - - Queries - - Dashboards - - Tasks - - Telegraf configurations - - Templates - - If you change an organization name, be sure to update the organization - name - + If you change an organization name, be sure to update the organization name in these resources as well. - #### Related Guides - - [Update an organization](/influxdb/v2.3/organizations/update-org/) operationId: PatchOrgsID parameters: @@ -12236,51 +11707,35 @@ paths: - Organizations /api/v2/orgs/{orgID}/members: get: - description: > + description: | Retrieves a list of all users that belong to an organization. - InfluxDB [users](/influxdb/v2.3/reference/glossary/#user) have - permission to access InfluxDB. - [Members](/influxdb/v2.3/reference/glossary/#member) are users - within the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `read-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you retrieve a list - of - + `INFLUX_ORG_ID` is the ID of the organization that you retrieve a list of members from. - #### Related guides - - [Manage users](/influxdb/v2.3/users/) - - [Manage members](/influxdb/v2.3/organizations/members/) operationId: GetOrgsIDMembers parameters: @@ -12316,11 +11771,9 @@ paths: status: active schema: $ref: '#/components/schemas/ResourceMembers' - description: > + description: | Success. - - The response body contains a list of all users within the - organization. + The response body contains a list of all users within the organization. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -12353,48 +11806,33 @@ paths: - Organizations - Security and access endpoints post: - description: > - Adds a user to an organization. - + description: | + Add a user to an organization. InfluxDB [users](/influxdb/v2.3/reference/glossary/#user) have - permission to access InfluxDB. - [Members](/influxdb/v2.3/reference/glossary/#member) are users - within the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `write-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want add a member - to. - + `INFLUX_ORG_ID` is the ID of the organization that you want add a member to. #### Related guides - - [Manage users](/influxdb/v2.3/users/) - - [Manage members](/influxdb/v2.3/organizations/members/) operationId: PostOrgsIDMembers parameters: @@ -12458,9 +11896,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ + source: | + curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -12469,44 +11906,31 @@ paths: }' /api/v2/orgs/{orgID}/members/{userID}: delete: - description: > + description: | Removes a member from an organization. - - Use this endpoint to remove a user's member privileges from a bucket. - This - + Use this endpoint to remove a user's member privileges from a bucket. This removes the user's `read` and `write` permissions from the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `write-orgs INFLUX_ORG_ID` - `INFLUX_ORG_ID` is the ID of the organization that you want to remove an - owner from. - #### Related guides - - [Manage members](/influxdb/v2.3/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: @@ -12546,25 +11970,19 @@ paths: - Security and access endpoints /api/v2/orgs/{orgID}/owners: get: - description: > + description: | Retrieves a list of all owners of an organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions - - `read-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve - a - + `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve a list of owners from. operationId: GetOrgsIDOwners parameters: @@ -12612,32 +12030,24 @@ paths: - Organizations - Security and access endpoints post: - description: > + description: | Adds an owner to an organization. - Use this endpoint to assign the organization `owner` role to a user. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Required permissions - - `write-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want add an owner - for. - + `INFLUX_ORG_ID` is the ID of the organization that you want add an owner for. #### Related endpoints - - [Authorizations](#tag/Authorizations) operationId: PostOrgsIDOwners parameters: @@ -12693,9 +12103,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request POST - "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ + source: | + curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ --header "Authorization: Token INFLUX_API_TOKEN" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ @@ -12704,45 +12113,30 @@ paths: }' /api/v2/orgs/{orgID}/owners/{userID}: delete: - description: > + description: | Removes an [owner](/influxdb/v2.3/reference/glossary/#owner) from - the organization. - - Organization owners have permission to delete organizations and remove - user and member - + Organization owners have permission to delete organizations and remove user and member permissions from the organization. - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. #### Limitations - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - #### Required permissions - - `write-orgs INFLUX_ORG_ID` - - `INFLUX_ORG_ID` is the ID of the organization that you want remove an - owner - + `INFLUX_ORG_ID` is the ID of the organization that you want remove an owner from. - #### Related endpoints - - [Authorizations](#tag/Authorizations) operationId: DeleteOrgsIDOwnersID parameters: @@ -12943,44 +12337,29 @@ paths: - Ping /api/v2/query: post: - description: > + description: | Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a - bucket. - + Use this endpoint to send a Flux query request and retrieve data from a bucket. #### Rate limits (with InfluxDB Cloud) - `read` rate limits apply. - - For more information, see [limits and adjustable - quotas](/influxdb/cloud/account-management/limits/). - + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - - [Query with the InfluxDB - API](/influxdb/v2.3/query-data/execute-queries/influx-api/). - - - [Get started with - Flux](https://docs.influxdata.com/flux/v0.x/get-started/) + - [Query with the InfluxDB API](/influxdb/v2.3/query-data/execute-queries/influx-api/) + - [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/) operationId: PostQuery parameters: - $ref: '#/components/parameters/TraceSpan' - - description: >- - The content encoding (usually a compression algorithm) that the - client can understand. + - description: The content encoding (usually a compression algorithm) that the client can understand. in: header name: Accept-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -12992,43 +12371,31 @@ paths: - application/json - application/vnd.flux type: string - - description: > + - description: | The name or ID of the organization executing the query. - #### InfluxDB Cloud - - Doesn't use `org` or `orgID`. - - - Queries the bucket in the organization associated with the - authorization (API token). - + - Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: org schema: type: string - - description: > + - description: | The ID of the organization executing the query. - #### InfluxDB Cloud - - Doesn't use `org` or `orgID`. - - - Queries the bucket in the organization associated with the - authorization (API token). - + - Queries the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. in: query name: orgID @@ -13051,27 +12418,21 @@ paths: '200': content: application/csv: - example: > + 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: type: string description: Success. The response body contains query results. headers: Content-Encoding: - description: >- - Lists encodings (usually compression algorithms) that have been - applied to the response payload. + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity - description: > - The content coding: `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -13092,17 +12453,13 @@ paths: 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` doesn't match an - organization. + - Returns this error if `org` or `orgID` doesn't match an organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -13120,9 +12477,7 @@ paths: - doesn't return this error. headers: Retry-After: - description: >- - Non-negative decimal integer indicating seconds to wait before - retrying the request. + description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: format: int32 type: integer @@ -13147,13 +12502,10 @@ 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 - + description: | + Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax errors and returns the list of errors. - In the following sample query, `from()` is missing the property key. ```json @@ -13165,14 +12517,10 @@ paths: ``` If you pass this in a request to the `/api/v2/analyze` endpoint, - - InfluxDB returns an `errors` list that contains an error object for the - missing key. - + InfluxDB returns an `errors` list that contains an error object for the missing key. #### Limitations - - The endpoint doesn't validate values in the query--for example: - The following sample query has correct syntax, but contains an incorrect `from()` property key: @@ -13208,22 +12556,17 @@ paths: application/json: examples: missingQueryPropertyKey: - description: > - Returns an error object if the Flux query is missing a - property key. + description: | + Returns an error object if the Flux query is missing a property key. + The following sample query is missing the _`bucket`_ property key: - The following sample query is missing the _`bucket`_ - property key: - - ```json - { - "query": "from(: \"iot_center\")\ - - ... - - } - ``` + ```json + { + "query": "from(: \"iot_center\")\ + ... + } + ``` summary: Missing property key error value: errors: @@ -13233,27 +12576,20 @@ paths: message: missing property key schema: $ref: '#/components/schemas/AnalyzeQueryResponse' - description: > + description: | Success. - The response body contains the list of `errors`. - - If the query syntax is valid, the endpoint returns an empty `errors` - list. + 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. + 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 + message: 'invalid json: invalid character ''\'''' looking for beginning of value' schema: $ref: '#/components/schemas/Error' description: | @@ -13272,9 +12608,8 @@ paths: application/json: examples: emptyJSONObject: - description: > - If the request body contains an empty JSON object, returns - `internal error`. + description: | + If the request body contains an empty JSON object, returns `internal error`. summary: Empty JSON object in request body value: code: internal error @@ -13317,33 +12652,20 @@ paths: EOF /api/v2/query/ast: post: - description: > - Analyzes a Flux query and returns a complete package source [Abstract - Syntax - + description: | + Analyzes a Flux query and returns a complete package source [Abstract Syntax Tree (AST)](/influxdb/v2.3/reference/glossary/#abstract-syntax-tree-ast) - for the query. - - Use this endpoint for deep query analysis such as debugging unexpected - 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 - + A Flux query AST provides a semantic, tree-like representation with contextual + information about the query. The AST illustrates how the query is distributed into different components for execution. - #### Limitations - - The endpoint doesn't validate values in the query--for example: The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: @@ -13363,6 +12685,7 @@ paths: ``` The following code sample shows how to pass the query as JSON in the request body: + ```json { "query": "from(foo: \"iot_center\")\ |> range(start: -90d)\ @@ -13542,9 +12865,7 @@ paths: end: column: 47 line: 1 - source: >- - from(bucket: "example-bucket") |> - range(start: -5m) + source: 'from(bucket: "example-bucket") |> range(start: -5m)' start: column: 1 line: 1 @@ -13555,9 +12876,7 @@ paths: end: column: 108 line: 1 - source: >- - fn: (r) => r._measurement == - "example-measurement" + source: 'fn: (r) => r._measurement == "example-measurement"' start: column: 58 line: 1 @@ -13577,9 +12896,7 @@ paths: end: column: 108 line: 1 - source: >- - fn: (r) => r._measurement == - "example-measurement" + source: 'fn: (r) => r._measurement == "example-measurement"' start: column: 58 line: 1 @@ -13643,9 +12960,7 @@ paths: end: column: 108 line: 1 - source: >- - (r) => r._measurement == - "example-measurement" + source: (r) => r._measurement == "example-measurement" start: column: 62 line: 1 @@ -13688,9 +13003,7 @@ paths: end: column: 109 line: 1 - source: >- - filter(fn: (r) => r._measurement == - "example-measurement") + source: 'filter(fn: (r) => r._measurement == "example-measurement")' start: column: 51 line: 1 @@ -13699,10 +13012,7 @@ paths: end: column: 109 line: 1 - source: >- - from(bucket: "example-bucket") |> - range(start: -5m) |> filter(fn: (r) => - r._measurement == "example-measurement") + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' start: column: 1 line: 1 @@ -13711,10 +13021,7 @@ paths: end: column: 109 line: 1 - source: >- - from(bucket: "example-bucket") |> range(start: - -5m) |> filter(fn: (r) => r._measurement == - "example-measurement") + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' start: column: 1 line: 1 @@ -13724,10 +13031,7 @@ paths: end: column: 109 line: 1 - source: >- - from(bucket: "example-bucket") |> range(start: - -5m) |> filter(fn: (r) => r._measurement == - "example-measurement") + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' start: column: 1 line: 1 @@ -13738,20 +13042,16 @@ paths: type: Package schema: $ref: '#/components/schemas/ASTResponse' - description: > + description: | Success. - - The response body contains an Abstract Syntax Tree (AST) of the Flux - query. + 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()`, - + description: | + If the request body contains a missing property key in `from()`, returns `invalid` and problem detail. summary: Invalid AST value: @@ -13796,48 +13096,31 @@ paths: EOL /api/v2/query/suggestions: get: - description: > + description: | Retrieves a list of Flux query suggestions. Each suggestion contains a - - [Flux - function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - + [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name and parameters. - - Use this endpoint to retrieve a list of Flux query suggestions used in - the - - InfluxDB Flux Query Builder. Helper function names have an underscore - (`_`) - + Use this endpoint to retrieve a list of Flux query suggestions used in the + InfluxDB Flux Query Builder. Helper function names have an underscore (`_`) prefix and aren't meant to be used directly in queries--for example: - - **Recommended**: Use `top(n, columns=["_value"], tables=<-)` to sort on a column and keep the top n records instead of `_sortLimit_`. `top` uses the `_sortLimit` helper function. #### Limitations - - Using `/api/v2/query/suggestions/` (note the trailing slash) with cURL - will result in a HTTP `301 Moved Permanently` status code. Please use - `/api/v2/query/suggestions` without a trailing slash. - - When writing a query, avoid using `_functionName()` helper functions - exposed by this endpoint. - #### Related Guides - - - [List of all Flux - functions](/influxdb/v2.3/flux/v0.x/stdlib/all-functions/). + - [List of all Flux functions](/influxdb/v2.3/flux/v0.x/stdlib/all-functions/) operationId: GetQuerySuggestions parameters: - $ref: '#/components/parameters/TraceSpan' @@ -14431,26 +13714,20 @@ paths: tables: stream schema: $ref: '#/components/schemas/FluxSuggestions' - description: > + description: | Success. - - The response body contains a list of Flux query - suggestions--function - + The response body contains a list of Flux query suggestions--function names used in the Flux Query Builder autocomplete suggestions. '301': content: text/html: examples: movedPermanently: - description: > - The URL has been permanently moved. Use - `/api/v2/query/suggestions`. + description: | + The URL has been permanently moved. Use `/api/v2/query/suggestions`. summary: Invalid URL - value: > - Moved - Permanently + value: | + Moved Permanently schema: properties: body: @@ -14473,45 +13750,30 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "https://cloud2.influxdata.com/api/v2/query/suggestions" \ + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/query/suggestions" \ --header "Accept: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" /api/v2/query/suggestions/{name}: get: - description: > - Retrieves a query suggestion that contains the name and parameters of - the - + description: | + Retrieves a query suggestion that contains the name and parameters of the requested function. - - Use this endpoint to pass a branching suggestion (a Flux function name) - and - + Use this endpoint to pass a branching suggestion (a Flux function name) and retrieve the parameters of the requested function. - #### Limitations - - Use `/api/v2/query/suggestions/{name}` (without a trailing slash). - - `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in - a - + `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a HTTP `301 Moved Permanently` status. - - The function `name` must exist and must be spelled correctly. - #### Related Guides - - - [List of all Flux - functions](/influxdb/v2.3/flux/v0.x/stdlib/all-functions/). + - [List of all Flux functions](/influxdb/v2.3/flux/v0.x/stdlib/all-functions/) operationId: GetQuerySuggestionsName parameters: - $ref: '#/components/parameters/TraceSpan' @@ -14561,9 +13823,8 @@ paths: x-codeSamples: - label: cURL lang: Shell - source: > - curl --request GET - "https://cloud2.influxdata.com/api/v2/query/suggestions/sum/" \ + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/query/suggestions/sum/" \ --header "Accept: application/json" \ --header "Authorization: Token INFLUX_API_TOKEN" /ready: @@ -14983,19 +14244,14 @@ paths: operationId: PostRestoreKV parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - The value tells InfluxDB what compression is applied to the line - protocol in the request payload. - - To make an API request with a GZIP payload, send `Content-Encoding: - gzip` as a request header. + - description: | + The value tells InfluxDB what compression is applied to the line protocol in the request payload. + To make an API request with a GZIP payload, send `Content-Encoding: gzip` as a request header. in: header name: Content-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -15022,9 +14278,7 @@ paths: schema: properties: token: - description: >- - token is the root token for the instance after restore - (this is overwritten during the restore) + description: token is the root token for the instance after restore (this is overwritten during the restore) type: string type: object description: KV store successfully overwritten. @@ -15041,19 +14295,14 @@ paths: operationId: PostRestoreShardId parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - The value tells InfluxDB what compression is applied to the line - protocol in the request payload. - - To make an API request with a GZIP payload, send `Content-Encoding: - gzip` as a request header. + - description: | + The value tells InfluxDB what compression is applied to the line protocol in the request payload. + To make an API request with a GZIP payload, send `Content-Encoding: gzip` as a request header. in: header name: Content-Encoding schema: default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. enum: - gzip - identity @@ -15093,19 +14342,14 @@ paths: operationId: PostRestoreSQL parameters: - $ref: '#/components/parameters/TraceSpan' - - description: > - The value tells InfluxDB what compression is applied to the line - protocol in the request payload. - - To make an API request with a GZIP payload, send `Content-Encoding: - gzip` as a request header. + - description: | + The value tells InfluxDB what compression is applied to the line protocol in the request payload. + To make an API request with a GZIP payload, send `Content-Encoding: gzip` as a request header. in: header name: Content-Encoding schema: default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. enum: - gzip - identity @@ -15131,9 +14375,7 @@ paths: default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error - summary: >- - Overwrite the embedded SQL store on the server with a backed-up - snapshot. + summary: Overwrite the embedded SQL store on the server with a backed-up snapshot. tags: - Restore /api/v2/scrapers: @@ -15146,9 +14388,7 @@ paths: name: name schema: type: string - - description: >- - List of scraper target IDs to return. If both `id` and `owner` are - specified, only `id` is used. + - description: List of scraper target IDs to return. If both `id` and `owner` are specified, only `id` is used. in: query name: id schema: @@ -15559,9 +14799,7 @@ paths: - Scraper Targets /api/v2/setup: get: - description: >- - Returns `true` if no default user, organization, or bucket has been - created. + description: Returns `true` if no default user, organization, or bucket has been created. operationId: GetSetup parameters: - $ref: '#/components/parameters/TraceSpan' @@ -15602,27 +14840,67 @@ paths: - Setup /api/v2/signin: post: - description: >- - Authenticates ***Basic Auth*** credentials for a user. If successful, - creates a new UI session for the user. + description: | + Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) + for a [user](/influxdb/v2.3/reference/glossary/#user), + and then, if successful, generates a user session. + + To authenticate a user, pass the HTTP `Authorization` header with the + `Basic` scheme and the base64-encoded username and password--for example: + + ```sh + Authorization: Basic USERNAME:PASSWORD + ``` + + In InfluxDB Cloud, the username is the email address the user signed up with. + + _Note that many HTTP clients provide a Basic authentication option that + accepts the `USERNAME:PASSWORD` syntax and encodes the credentials before + sending the request. + To learn more about HTTP authentication, see + [Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._ + + If authentication is successful, InfluxDB creates a new session for the user + and then returns the session cookie in the `Set-Cookie` response header. + User sessions exist only in memory. + They expire within ten minutes and during restarts of the InfluxDB instance. + + #### User sessions with authorizations + + - In InfluxDB Cloud, a user session inherits all the user's permissions for + the organization. + - In InfluxDB OSS, a user session inherits all the user's permissions for all + the organizations that the user belongs to. + + #### Related endpoints + + - [Signout](#tag/Signout) operationId: PostSignin parameters: - $ref: '#/components/parameters/TraceSpan' responses: '204': - description: Success. User authenticated. + description: | + Success. + The user is authenticated. + The `Set-Cookie` response header contains the session cookie. '401': content: application/json: schema: $ref: '#/components/schemas/Error' - description: Unauthorized access. + description: | + Unauthorized. + This error may be caused by one of the following problems: + - The user doesn't have access. + - The user passed incorrect credentials in the request. + - The credentials are formatted incorrectly in the request. '403': content: application/json: schema: $ref: '#/components/schemas/Error' - description: User account is disabled. + description: Forbidden. The user account is disabled. default: content: application/json: @@ -15634,6 +14912,12 @@ paths: summary: Create a user session. tags: - Signin + x-codeSamples: + - label: 'cURL: signin with --user option encoding' + lang: Shell + source: | + curl --request POST http://localhost:8086/api/v2/signin \ + --user "USERNAME:PASSWORD" /api/v2/signout: post: description: Expires the current UI session for the user. @@ -15906,21 +15190,15 @@ paths: required: true schema: type: string - - description: > + - description: | The stack name. - Finds stack `events` with this name and returns the stacks. - Repeatable. - To filter for more than one stack name, - repeat this parameter with each name--for example: - - - - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` + - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` examples: findStackByName: summary: Find stacks with the event name @@ -15929,21 +15207,15 @@ paths: name: name schema: type: string - - description: > + - description: | The stack ID. - Only returns stacks with this ID. - Repeatable. - To filter for more than one stack ID, - repeat this parameter with each ID--for example: - - - - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` + - `http://localhost:8086/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` examples: findStackByID: summary: Find a stack with the ID @@ -15972,29 +15244,21 @@ paths: summary: The orgID query parameter is missing value: code: invalid - message: >- - organization id[""] is invalid: id must have a length of - 16 bytes + message: 'organization id[""] is invalid: id must have a length of 16 bytes' orgProvidedNotFound: - summary: >- - The org or orgID passed doesn't own the token passed in the - header + 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 an incorrect value is passed for `org` or - `orgID`. + - Returns this error if an incorrect value is passed for `org` or `orgID`. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -16009,13 +15273,10 @@ paths: tags: - Templates post: - description: > + description: | Creates or initializes a stack. - - Use this endpoint to _manually_ initialize a new stack with the - following - + Use this endpoint to _manually_ initialize a new stack with the following optional information: - Stack name @@ -16023,23 +15284,16 @@ paths: - URLs for template manifest files To automatically create a stack when applying templates, - use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). - #### Required permissions - - `write` permission for the organization - #### Related guides - - [InfluxDB stacks](/influxdb/v2.3/influxdb-templates/stacks/) - - - [Use InfluxDB - templates](/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance) + - [Use InfluxDB templates](/influxdb/v2.3/influxdb-templates/use/#apply-templates-to-an-influxdb-instance) operationId: CreateStack requestBody: content: @@ -16074,16 +15328,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -16236,57 +15486,57 @@ paths: - Templates /api/v2/tasks: get: - description: > - Retrieves a list of [tasks](/influxdb/v2.3/process-data/). + description: | + Retrieves a list of [tasks](/influxdb/v2.3/reference/glossary/#task). + To limit which tasks are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. - To limit which tasks are returned, pass query parameters in your - request. + #### Related guide - If no query parameters are passed, InfluxDB returns all tasks up to the - default `limit`. + - [Process data with InfluxDB tasks](/influxdb/v2.3/process-data/) operationId: GetTasks parameters: - $ref: '#/components/parameters/TraceSpan' - description: | - Task name. - Only returns tasks with this name. + A [task](/influxdb/v2.3/reference/glossary/#task) name. + Only returns tasks with the specified name. Different tasks may have the same name. in: query name: name schema: type: string - description: | - Task ID. - Only returns tasks created after this task. + A [task](/influxdb/v2.3/reference/glossary/#task) ID. + Only returns tasks created after the specified task. in: query name: after schema: type: string - description: | - User ID. - Only returns tasks owned by this user. + A [user](/influxdb/v2.3/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. in: query name: user schema: type: string - description: | - Organization name. - Only returns tasks owned by this organization. + An [organization](/influxdb/v2.3/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. in: query name: org schema: type: string - description: | - Organization ID. - Only returns tasks owned by this organization. + An [organization](/influxdb/v2.3/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. in: query name: orgID schema: type: string - description: | - Task status (`active` or `inactive`). - Only returns tasks with this status. + A [task](/influxdb/v2.3/reference/glossary/#task) status. + Only returns tasks that have the specified status (`active` or `inactive`). in: query name: status schema: @@ -16295,8 +15545,12 @@ paths: - inactive type: string - description: | - Limits the number of tasks returned. - The minimum is `1`, the maximum is `500`, and the default is `100`. + The maximum number of [tasks](/influxdb/v2.3/reference/glossary/#task) to return. + Default is `100`. + The minimum is `1` and the maximum is `500`. + + To reduce the payload size, combine _`type=basic`_ and _`limit`_ (see _Request samples_). + For more information about the `basic` response, see the _`type`_ parameter. in: query name: limit schema: @@ -16304,15 +15558,12 @@ paths: maximum: 500 minimum: 1 type: integer - - 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. + - description: | + A [task](/influxdb/v2.3/reference/glossary/#task) type (`basic` or `system`). + Default is `system`. + Specifies the level of detail for tasks in the response. + The default (`system`) response contains all the metadata properties for tasks. + To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`). in: query name: type required: false @@ -16328,7 +15579,10 @@ paths: application/json: examples: basicTypeTaskOutput: - description: Task fields returned with `?type=basic` + description: | + A sample response body for the `?type=basic` parameter. + `type=basic` omits some task fields (`createdAt` and `updatedAt`) + and field values (`org`, `flux`) in the response. summary: Basic output value: links: @@ -16353,7 +15607,9 @@ paths: ownerID: 0772396d1f411000 status: active systemTypeTaskOutput: - description: Task fields returned with `?type=system` + description: | + A sample response body for the `?type=system` parameter. + `type=system` returns all task fields. summary: System output value: links: @@ -16409,22 +15665,15 @@ paths: --header 'Content-Type: application/json' \ --header 'Authorization: Token INFLUX_API_TOKEN' post: - description: > - Creates a [task](/influxdb/v2.3/process-data/) and returns the created - task. - + description: | + Creates a [task](/influxdb/v2.3/reference/glossary/#task) and returns the task. #### Related guides - - [Get started with tasks](/influxdb/v2.3/process-data/get-started/) - - [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/) + - [Task configuration options](/influxdb/v2.3/process-data/task-options/) operationId: PostTasks parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16441,9 +15690,7 @@ paths: application/json: schema: $ref: '#/components/schemas/Task' - description: >- - Success. The response body contains a `tasks` list with the new - task. + description: Success. The response body contains a `tasks` list with the task. '400': content: application/json: @@ -16454,25 +15701,19 @@ paths: code: invalid message: 'failed to decode request: missing flux' orgProvidedNotFound: - summary: >- - The org or orgID passed doesn't own the token passed in the - header + summary: The org or orgID passed doesn't own the token passed in the header value: code: invalid message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/Error' - description: > + description: | Bad request. - The response body contains detail about the error. - #### InfluxDB OSS - - - Returns this error if an incorrect value is passed for `org` or - `orgID`. + - Returns this error if an incorrect value is passed for `org` or `orgID`. '401': $ref: '#/components/responses/AuthorizationError' '500': @@ -16507,19 +15748,13 @@ paths: EOF /api/v2/tasks/{taskID}: delete: - description: > + 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. - 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). + 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' @@ -16579,24 +15814,15 @@ paths: - Data I/O endpoints - Tasks patch: - description: > + description: | Updates a task and then cancels all scheduled runs of the task. + Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`). + Once InfluxDB applies the update, it cancels all previously scheduled runs of the task. - Use this endpoint to set, modify, and clear task properties (for - example: `cron`, `name`, `flux`, `status`). - - Once InfluxDB applies the update, it cancels all previously scheduled - runs of the task. - - - To update a task, pass an object that contains the updated key-value - pairs. - + 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. + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. operationId: PatchTasksID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16654,9 +15880,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelsResponse' - description: >- - Success. The response body contains a list of all labels for the - task. + description: Success. The response body contains a list of all labels for the task. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -16671,12 +15895,10 @@ paths: tags: - Tasks post: - description: > + 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. + 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' @@ -16699,9 +15921,7 @@ paths: application/json: schema: $ref: '#/components/schemas/LabelResponse' - description: >- - Success. The response body contains a list of all labels for the - task. + description: Success. The response body contains a list of all labels for the task. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -16752,20 +15972,13 @@ paths: - 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. + 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: @@ -16785,32 +15998,20 @@ paths: summary: Events for a failed task run. value: events: - - message: >- - Started task from script: "option task = {name: \"test - task\", every: 3d, offset: 0s}" + - 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 + - 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 a successful task run. 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)" + - 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) @@ -16818,14 +16019,10 @@ paths: time: '2022-07-18T14:46:07.242859Z' schema: $ref: '#/components/schemas/Logs' - description: > - Success. The response body contains an `events` list with logs for - the 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. + If a task run fails, InfluxDB logs an event with the reason for the failure. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -16842,11 +16039,9 @@ paths: /api/v2/tasks/{taskID}/members: get: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: GetTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16876,17 +16071,11 @@ paths: - Tasks post: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. - - - Adds a user to members of a task and returns the newly created member - with - - role and user detail. + Adds a user to members of a task and returns the member. operationId: PostTasksIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16922,11 +16111,9 @@ paths: /api/v2/tasks/{taskID}/members/{userID}: delete: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -16957,12 +16144,9 @@ paths: /api/v2/tasks/{taskID}/owners: get: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. - + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. Retrieves all users that have owner permission for a task. operationId: GetTasksIDOwners @@ -16980,15 +16164,11 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceOwners' - description: > + description: | Success. + The response contains a list of `users` that have the `owner` role for the task. - The response contains a list of `users` that have the `owner` role - for the task. - - - If the task has no owners, the response contains an empty `users` - array. + If the task has no owners, the response contains an empty `users` array. '401': $ref: '#/components/responses/AuthorizationError' '422': @@ -16996,16 +16176,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -17020,18 +16196,13 @@ paths: - Tasks post: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. - + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. Assigns a task `owner` role to a user. - Use this endpoint to create a _resource owner_ for the task. - A _resource owner_ is a user with `role: owner` for a specific resource. operationId: PostTasksIDOwners parameters: @@ -17077,16 +16248,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -17102,11 +16269,9 @@ paths: /api/v2/tasks/{taskID}/owners/{userID}: delete: deprecated: true - description: > + description: | **Deprecated**: Tasks don't use `owner` and `member` roles. - - Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user - permissions. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. operationId: DeleteTasksIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17136,15 +16301,11 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs: get: - description: > + description: | Retrieves a list of runs for a [task](/influxdb/v2.3/process-data/). - - To limit which task runs are returned, pass query parameters in your - request. - - If no query parameters are passed, InfluxDB returns all task runs up to - the default `limit`. + To limit which task runs are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all task runs up to the default `limit`. operationId: GetTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17170,20 +16331,16 @@ paths: maximum: 500 minimum: 1 type: integer - - description: > - A timestamp ([RFC3339 date/time - format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - + - description: | + A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled after this time. in: query name: afterTime schema: format: date-time type: string - - description: > - A timestamp ([RFC3339 date/time - format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). - + - description: | + A timestamp ([RFC3339 date/time format](/influxdb/v2.3/reference/glossary/#rfc3339-timestamp)). Only returns runs scheduled before this time. in: query name: beforeTime @@ -17207,22 +16364,15 @@ paths: tags: - Tasks post: - description: > + description: | Schedules a task run to start immediately, ignoring scheduled runs. - Use this endpoint to manually start a task run. - Scheduled runs will continue to run as scheduled. - This may result in concurrently running tasks. - To _retry_ a previous run (and avoid creating a new run), - - use the [`POST - /api/v2/tasks/{taskID}/runs/{runID}/retry`](#operation/PostTasksIDRunsIDRetry) - endpoint. + use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). operationId: PostTasksIDRuns parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17316,10 +16466,8 @@ paths: tags: - Tasks get: - description: > - Retrieves a specific run for a - [task](/influxdb/v2.3/reference/glossary/#task). - + 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 @@ -17348,19 +16496,12 @@ paths: 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 + 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)" + - 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) @@ -17389,15 +16530,11 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/logs: get: - description: > + description: | Retrieves all logs for a task run. + A log is a list of run events with `runID`, `time`, and `message` properties. - A log is a list of run events with `runID`, `time`, and `message` - properties. - - - Use this endpoint to help analyze task performance and troubleshoot - failed task runs. + Use this endpoint to help analyze task performance and troubleshoot failed task runs. operationId: GetTasksIDRunsIDLogs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -17422,32 +16559,20 @@ paths: summary: Events for a failed task. value: events: - - message: >- - Started task from script: "option task = {name: \"test - task\", every: 3d, offset: 0s}" + - 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 + - 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 a successful task run. 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)" + - 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) @@ -17455,14 +16580,10 @@ paths: time: '2022-07-18T14:46:07.242859Z' schema: $ref: '#/components/schemas/Logs' - description: > - Success. The response body contains an `events` list with logs for - the task run. - + description: | + Success. The response body contains an `events` list with logs for the task run. Each log event `message` contains detail about the event. - - If a run fails, InfluxDB logs an event with the reason for the - failure. + If a run fails, InfluxDB logs an event with the reason for the failure. '400': $ref: '#/components/responses/BadRequestError' '401': @@ -17478,28 +16599,34 @@ paths: - Tasks /api/v2/tasks/{taskID}/runs/{runID}/retry: post: - description: > - Queues a task run to retry and returns the newly scheduled run. - - - To manually start a _new_ task run, use the [`POST - /api/v2/tasks/{taskID}/runs`](#operation/PostTasksIDRuns) endpoint. + description: | + Queues a [task](/influxdb/v2.3/reference/glossary/#task) run to + retry and returns the scheduled run. + To manually start a _new_ task run, use the + [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). #### Limitations - - The task must be _active_ (`status: "active"`). operationId: PostTasksIDRunsIDRetry parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the task to retry. + - description: | + A [task](/influxdb/v2.3/reference/glossary/#task) ID. + Specifies the task to retry. in: path name: taskID required: true schema: type: string - - description: The ID of the task run to retry. + - description: | + A [task](/influxdb/v2.3/reference/glossary/#task) run ID. + Specifies the task run to retry. + + To find a task run ID, use the + [`GET /api/v2/tasks/{taskID}/runs` endpoint](#operation/GetTasksIDRuns) + to list task runs. in: path name: runID required: true @@ -17520,10 +16647,8 @@ paths: value: id: 09d60ffe08738000 links: - logs: >- - /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs - retry: >- - /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry + logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs + retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 task: /api/v2/tasks/09a776832f381000 requestedAt: '2022-08-16T20:05:11.84145Z' @@ -17979,9 +17104,7 @@ paths: application/json: schema: $ref: '#/components/schemas/ResourceOwner' - description: >- - Telegraf configuration owner was added. Returns a ResourceOwner that - references the User. + description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. default: content: application/json: @@ -18022,44 +17145,26 @@ paths: - Telegrafs /api/v2/templates/apply: post: - description: > + description: | Applies a template to - - create or update a [stack](/influxdb/v2.3/influxdb-templates/stacks/) of - InfluxDB - + create or update a [stack](/influxdb/v2.3/influxdb-templates/stacks/) of InfluxDB [resources](/influxdb/v2.3/reference/cli/influx/export/all/#resources). - The response contains the diff of changes and the stack ID. - Use this endpoint to install an InfluxDB template to an organization. - Provide template URLs or template objects in your request. - To customize which template resources are installed, use the `actions` - parameter. - By default, when you apply a template, InfluxDB installs the template to - - create and update stack resources and then generates a diff of the - changes. - + create and update stack resources and then generates a diff of the changes. If you pass `dryRun: true` in the request body, InfluxDB validates the - template and generates the resource diff, but doesn’t make any - changes to your instance. - #### Custom values for templates - - - Some templates may contain [environment - references](/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) - for custom metadata. + - Some templates may contain [environment references](/influxdb/v2.3/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. To provide custom values for environment references, pass the _`envRefs`_ property in the request body. For more information and examples, see how to @@ -18074,21 +17179,16 @@ paths: #### Required permissions - - `write` permissions for resource types in the template. - #### Rate limits (with InfluxDB Cloud) - - Adjustable service quotas apply. For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - [Use templates](/influxdb/v2.3/influxdb-templates/use/) - - [Stacks](/influxdb/v2.3/influxdb-templates/stacks/) operationId: ApplyTemplate requestBody: @@ -18188,16 +17288,11 @@ paths: application/json: schema: $ref: '#/components/schemas/TemplateSummary' - description: > + description: | Success. - The template applied successfully. - The response body contains the stack ID, a diff, and a summary. - - The diff compares the initial state to the state after the template - installation. - + The diff compares the initial state to the state after the template installation. The summary contains newly created resources. '422': content: @@ -18367,9 +17462,7 @@ paths: application/x-yaml: schema: $ref: '#/components/schemas/Template' - description: >- - The template was created successfully. Returns the newly created - template. + description: The template was created successfully. Returns the newly created template. default: content: application/json: @@ -18381,33 +17474,39 @@ paths: - Templates /api/v2/users: get: - description: > - Retrieves a list of users. Default limit is `20`. + description: | + Retrieves a list of [users](/influxdb/v2.3/reference/glossary/#user). + Default limit is `20`. + To limit which users are returned, pass query parameters in your request. - To limit which users are returned, pass query parameters in your - request. + #### Required permissions for InfluxDB OSS + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | List all users | _[Operator token](/influxdb/latest/security/tokens/#operator-token)_ | | + | List a specific user | `read-users` or `read-user USER_ID` | | - #### Required permissions + Replace the following: - - - `read-user USER_ID` permission. - `USER_ID` is the ID of the user that you want to list. - - InfluxDB OSS requires an _[operator - token](/influxdb/latest/security/tokens/#operator-token))_ to list all - users. + - `USER_ID`: the ID of the user that you want to retrieve. operationId: GetUsers parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/After' - - in: query + - description: | + A user name. + Only lists the specified [user](/influxdb/v2.3/reference/glossary/#user). + in: query name: name schema: type: string - - in: query + - description: | + A user ID. + Only lists the specified [user](/influxdb/v2.3/reference/glossary/#user). + in: query name: id schema: type: string @@ -18436,16 +17535,13 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, + but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -18458,11 +17554,34 @@ paths: - Users post: description: | - Creates a user and returns the newly created user. + Creates a [user](/influxdb/v2.3/reference/glossary/#user) that can access InfluxDB. + Returns the user. + + Use this endpoint to create a user that can sign in to start a user session + through one of the following interfaces: + + - InfluxDB UI + - `/api/v2/signin` InfluxDB API endpoint + - InfluxDB CLI + + This endpoint represents the first two steps in a four-step process to allow a user + to authenticate with a username and password, and then access data in an organization: + + 1. Create a user: send a `POST` request to `POST /api/v2/users`. `name` is required. + 2. Extract the user ID (`id`) value from the API response for _step 1_. + 3. Create an authorization (and API token) for the user: send a `POST` request to [`POST /api/v2/authorizations`](#operation/PostAuthorizations), passing the user ID (`id`) from _step 2_. + 4. Create a password for the user: send a `POST` request to [`POST /api/v2/users/USER_ID/password`](#operation/PostUsersIDPassword), passing the user ID from _step 2_. #### Required permissions - - `write-users`. Requires an InfluxDB API **Op** token. + | Action | Permission required | Restriction | + |:-------|:--------------------|:------------| + | Create a user | _[Operator token](/influxdb/latest/security/tokens/#operator-token)_ | | + + #### Related guides + + - [Create a user](/influxdb/latest/users/create-user/) + - [Create an API token scoped to a user](/influxdb/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) operationId: PostUsers parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18481,7 +17600,7 @@ paths: $ref: '#/components/schemas/UserResponse' description: | Success. - The response contains the newly created user. + The response body contains the user. '401': content: application/json: @@ -18500,16 +17619,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error' - description: > + description: | Unprocessable entity. - The error may indicate one of the following problems: - - - The request body isn't valid--the request is well-formed, but - InfluxDB can't process it due to semantic errors. - + - The request body isn't valid--the request is well-formed, but InfluxDB can't process it due to semantic errors. - You passed a parameter combination that InfluxDB doesn't support. '500': $ref: '#/components/responses/InternalServerError' @@ -18522,9 +17637,8 @@ paths: x-codeSamples: - label: 'cURL: create a user and set a password' lang: Shell - source: > + source: | # Create the user and assign the user ID to a variable. - USER_ID=$(curl --request POST \ "http://localhost:8086/api/v2/users/" \ --header "Authorization: Token INFLUX_OP_TOKEN" \ @@ -18535,14 +17649,10 @@ paths: "status": "active" } EOF - ) - # Pass the user ID and a password to set the password for the user. - - curl request POST - "http://localhost:8086/api/v2/users/$USER_ID/password/" \ + curl request POST "http://localhost:8086/api/v2/users/$USER_ID/password/" \ --header "Authorization: Token INFLUX_OP_TOKEN" \ --header 'Content-type: application/json' \ --data '{ "password": "USER_PASSWORD" }' @@ -18567,10 +17677,18 @@ paths: tags: - Users get: + description: | + Retrieves a [user](/influxdb/v2.3/reference/glossary/#user). + + #### Related guides + + - [Manage users](/influxdb/v2.3/organizations/users/) operationId: GetUsersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The user ID. + - description: | + A user ID. + Retrieves the specified [user](/influxdb/v2.3/reference/glossary/#user). in: path name: userID required: true @@ -18582,7 +17700,7 @@ paths: application/json: schema: $ref: '#/components/schemas/UserResponse' - description: User details + description: Success. The response body contains the user. default: $ref: '#/components/responses/GeneralServerError' description: Unexpected error @@ -18623,14 +17741,25 @@ paths: /api/v2/users/{userID}/password: post: description: | + Updates a user password. + + Use this endpoint to let a user authenticate with + [Basic authentication credentials](#section/Authentication/BasicAuthentication) + and set a new password. + #### InfluxDB Cloud - InfluxDB Cloud doesn't support changing user passwords through the API. - Use the InfluxDB Cloud user interface to update your password. + - Doesn't allow you to manage user passwords through the API. + Use the InfluxDB Cloud user interface (UI) to update a password. + + #### Related guides + + - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) + - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) operationId: PostUsersIDPassword parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The user ID. + - description: The ID of the user to set the password for. in: path name: userID required: true @@ -18641,29 +17770,52 @@ paths: application/json: schema: $ref: '#/components/schemas/PasswordResetBody' - description: New password + description: The new password to set for the user. required: true responses: '204': - description: Password successfully updated + description: Success. The password is 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: + examples: + updatePasswordNotAllowed: + summary: Cloud API can't update passwords + value: + code: invalid + message: passwords cannot be changed through the InfluxDB Cloud API schema: $ref: '#/components/schemas/Error' - description: Unsuccessful authentication + description: | + Bad request. + + #### InfluxDB Cloud + + - Doesn't allow you to manage passwords through the API; always responds with this status. + + #### InfluxDB OSS + + - Doesn't understand a value passed in the request. + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error security: - BasicAuthentication: [] summary: Update a password tags: - Security and access endpoints - Users + x-codeSamples: + - label: 'cURL: use Basic auth to update the user password' + lang: Shell + source: | + curl --request POST \ + "http://localhost:8086/api/v2/users/USER_ID/password" \ + --header 'Content-type: application/json' \ + --user "USERNAME:PASSWORD" \ + --data-binary @- << EOF + {"password": ""} + EOF /api/v2/variables: get: operationId: GetVariables @@ -18922,18 +18074,13 @@ paths: - Variables /api/v2/write: post: - description: > + description: | Writes data to a bucket. - - Use this endpoint to send data in [line - protocol](/influxdb/v2.3/reference/syntax/line-protocol/) format to - InfluxDB. - + Use this endpoint to send data in [line protocol](/influxdb/v2.3/reference/syntax/line-protocol/) format to InfluxDB. #### InfluxDB Cloud - - Takes the following steps when you send a write request: 1. Validates the request and queues the write. @@ -18949,40 +18096,27 @@ paths: #### InfluxDB OSS - - Validates the request, handles the write synchronously, and then responds with success or failure. - - If all points were written successfully, responds with HTTP `204` - status code; + - If all points were written successfully, responds with HTTP `204` status code; otherwise, returns the first line that failed. #### Required permissions - - `write-buckets` or `write-bucket BUCKET_ID`. `BUCKET_ID` is the ID of the destination bucket. #### Rate limits (with InfluxDB Cloud) - `write` rate limits apply. - - For more information, see [limits and adjustable - quotas](/influxdb/cloud/account-management/limits/). - + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). #### Related guides - - - [Write data with the InfluxDB - API](/influxdb/v2.3/write-data/developer-tools/api). - - - [Optimize writes to - InfluxDB](/influxdb/v2.3/write-data/best-practices/optimize-writes/). - - - [Troubleshoot issues writing - data](/influxdb/v2.3/write-data/troubleshoot/) + - [Write data with the InfluxDB API](/influxdb/v2.3/write-data/developer-tools/api) + - [Optimize writes to InfluxDB](/influxdb/v2.3/write-data/best-practices/optimize-writes/) + - [Troubleshoot issues writing data](/influxdb/v2.3/write-data/troubleshoot/) operationId: PostWrite parameters: - $ref: '#/components/parameters/TraceSpan' @@ -18993,27 +18127,22 @@ paths: name: Content-Encoding schema: default: identity - description: > + description: | Content coding. - - Use `gzip` for compressed data or `identity` for unmodified, - uncompressed data. + Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity type: string - - description: > + - description: | The format of the data in the request body. - - To send a line protocol payload, pass `Content-Type: text/plain; - charset=utf-8`. + To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`. in: header name: Content-Type schema: default: text/plain; charset=utf-8 - description: > - `text/plain` is the content type for line protocol. `UTF-8` is the - default character set. + description: | + `text/plain` is the content type for line protocol. `UTF-8` is the default character set. enum: - text/plain - text/plain; charset=utf-8 @@ -19042,7 +18171,8 @@ paths: - Returns only `application/json` for format and limit errors. #### Related guides - - [Troubleshoot issues writing data](/influxdb/v2.3/write-data/troubleshoot/). + + - [Troubleshoot issues writing data](/influxdb/v2.3/write-data/troubleshoot/) in: header name: Accept schema: @@ -19051,28 +18181,19 @@ paths: enum: - application/json type: string - - description: > + - description: | The destination organization for writes. - InfluxDB writes all points in the batch to this organization. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Writes to the bucket in the organization associated with the - authorization (API token). - + - Writes to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. - - InfluxDB writes all points in the batch to this organization. in: query name: org @@ -19080,27 +18201,19 @@ paths: schema: description: The organization name or ID. type: string - - description: > + - description: | The ID of the destination organization for writes. - If you pass both `orgID` and `org`, they must both be valid. - #### InfluxDB Cloud - - Doesn't require `org` or `orgID`. - - - Writes to the bucket in the organization associated with the - authorization (API token). - + - Writes to the bucket in the organization associated with the authorization (API token). #### InfluxDB OSS - - Requires either `org` or `orgID`. - - InfluxDB writes all points in the batch to this organization. in: query name: orgID @@ -19125,21 +18238,15 @@ paths: text/plain: examples: plain-utf8: - value: > - airSensors,sensor_id=TLM0201 - temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 - 1630424257000000000 - - airSensors,sensor_id=TLM0202 - temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 - 1630424257000000000 + value: | + airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 + airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000 schema: format: byte type: string - description: > + description: | Data in line protocol format. - To send compressed data, do the following: 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. @@ -19148,52 +18255,34 @@ paths: #### Related guides - - - [Best practices for optimizing - writes](/influxdb/v2.3/write-data/best-practices/optimize-writes/). + - [Best practices for optimizing writes](/influxdb/v2.3/write-data/best-practices/optimize-writes/) required: true responses: '204': - description: > + description: | Success. - #### InfluxDB Cloud - - Validated and queued the request. - - - Handles the write asynchronously - the write might not have - completed yet. - + - Handles the write asynchronously - the write might not have completed yet. #### InfluxDB OSS - - Successfully wrote all points in the batch. - #### Related guides - - - [How to check for write - errors](/influxdb/v2.3/write-data/troubleshoot/). + - [How to check for write errors](/influxdb/v2.3/write-data/troubleshoot/) '400': content: application/json: examples: measurementSchemaFieldTypeConflict: - summary: >- - (Cloud) field type conflict thrown by an explicit bucket - schema + summary: (Cloud) field type conflict thrown by an explicit bucket schema value: code: invalid - message: >- - partial write error (2 written): unable to parse - 'air_sensor,service=S1,sensor=L1 - temperature="90.5",humidity=70.0 1632850122': schema: - field type for field "temperature" not permitted by - schema; got String but expected Float + message: 'partial write error (2 written): unable to parse ''air_sensor,service=S1,sensor=L1 temperature="90.5",humidity=70.0 1632850122'': schema: field type for field "temperature" not permitted by schema; got String but expected Float' orgNotFound: summary: (OSS) organization not found value: @@ -19201,34 +18290,21 @@ paths: message: 'failed to decode request body: organization not found' schema: $ref: '#/components/schemas/LineProtocolError' - description: > + description: | Bad request. The response body contains detail about the error. - - InfluxDB returns this error if the line protocol data in the request - is malformed. - - The response body contains the first malformed line in the data, and - indicates what was expected. - - For partial writes, the number of points written and the number of - points rejected are also included. - - For more information, check the `rejected_points` measurement in - your `_monitoring` bucket. - + InfluxDB returns this error if the line protocol data in the request is malformed. + The response body contains the first malformed line in the data, and indicates what was expected. + For partial writes, the number of points written and the number of points rejected are also included. + For more information, check the `rejected_points` measurement in your `_monitoring` bucket. #### InfluxDB Cloud - - Returns this error for bucket schema conflicts. - #### InfluxDB OSS - - - Returns this error if `org` or `orgID` doesn't match an - organization. + - Returns this error if `org` or `orgID` doesn't match an organization. '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -19239,9 +18315,8 @@ paths: examples: dataExceedsSizeLimitOSS: summary: InfluxDB OSS response - value: > - {"code":"request too large","message":"unable to read data: - points batch is too large"} + value: | + {"code":"request too large","message":"unable to read data: points batch is too large"} schema: $ref: '#/components/schemas/LineProtocolLengthError' text/html: @@ -19291,28 +18366,22 @@ paths: - Doesn't return this error. headers: Retry-After: - description: >- - Non-negative decimal integer indicating seconds to wait before - retrying the request. + description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: format: int32 type: integer '500': $ref: '#/components/responses/InternalServerError' '503': - description: > + description: | Service unavailable. - - Returns this error if the server is temporarily unavailable to accept writes. - - Returns a `Retry-After` header that describes when to try the - write again. + - Returns a `Retry-After` header that describes when to try the write again. headers: Retry-After: - description: >- - Non-negative decimal integer indicating seconds to wait before - retrying the request. + description: Non-negative decimal integer indicating seconds to wait before retrying the request. schema: format: int32 type: integer @@ -19329,42 +18398,42 @@ paths: - $ref: '#/components/parameters/TraceSpan' - description: | A user ID. - Only returns legacy authorizations scoped to this user. + Only returns legacy authorizations scoped to the specified [user](/influxdb/v2.4/reference/glossary/#user). in: query name: userID schema: type: string - description: | A user name. - Only returns legacy authorizations scoped to this user. + Only returns legacy authorizations scoped to the specified [user](/influxdb/v2.4/reference/glossary/#user). in: query name: user schema: type: string - description: | An organization ID. - Only returns legacy authorizations that belong to this organization. + Only returns legacy authorizations that belong to the specified [organization](/influxdb/v2.4/reference/glossary/#organization). in: query name: orgID schema: type: string - description: | An organization name. - Only returns legacy authorizations that belong to this organization. + Only returns legacy authorizations that belong to the specified [organization](/influxdb/v2.4/reference/glossary/#organization). in: query name: org schema: type: string - description: | An authorization name token. - Only returns legacy authorizations with this token (name). + Only returns legacy authorizations with the specified name. in: query name: token schema: type: string - description: | An authorization ID. - Only returns the legacy authorization with this ID. + Returns the specified legacy authorization. in: query name: authID schema: @@ -19383,9 +18452,7 @@ paths: $ref: '#/components/schemas/Links' readOnly: true type: object - description: >- - Success. The response body contains a list of legacy - `authorizations`. + description: Success. The response body contains a list of legacy `authorizations`. default: $ref: '#/components/responses/ServerError' description: Unexpected error @@ -19393,20 +18460,14 @@ paths: tags: - Legacy Authorizations post: - description: > - Creates a legacy authorization and returns the newly created - authorization. - + description: | + Creates a legacy authorization and returns the legacy authorization. #### Required permissions + - `write-users USER_ID` if you pass the `userID` property in the request body. - - `write-users USER_ID` if you pass the `userID` property in the request - body. - - - `USER_ID` is the ID of the user that you want to scope the authorization - to. + `USER_ID` is the ID of the user that you want to scope the authorization to. operationId: PostLegacyAuthorizations parameters: - $ref: '#/components/parameters/TraceSpan' @@ -19441,17 +18502,14 @@ paths: schema: properties: code: - description: > - The HTTP status code description. Default is - `unauthorized`. + description: | + The HTTP status code description. Default is `unauthorized`. enum: - unauthorized readOnly: true type: string message: - description: >- - A human-readable message that may contain detail about the - error. + description: A human-readable message that may contain detail about the error. readOnly: true type: string description: | @@ -19584,30 +18642,22 @@ paths: name: Accept schema: default: application/json - description: > + description: | Media type that the client can understand. - - **Note**: With `application/csv`, query results include [**unix - timestamps**](/influxdb/v2.4/reference/glossary/#unix-timestamp) - instead of [RFC3339 - timestamps](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp). + **Note**: With `application/csv`, query results include [**unix timestamps**](/influxdb/v2.4/reference/glossary/#unix-timestamp) instead of [RFC3339 timestamps](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp). enum: - application/json - application/csv - text/csv - application/x-msgpack type: string - - description: >- - The content encoding (usually a compression algorithm) that the - client can understand. + - description: The content encoding (usually a compression algorithm) that the client can understand. in: header name: Accept-Encoding schema: default: identity - description: >- - The content coding. Use `gzip` for compressed data or `identity` - for unmodified, uncompressed data. + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. enum: - gzip - identity @@ -19628,49 +18678,33 @@ paths: name: p schema: type: string - - description: > + - description: | The database to query data from. - - This is mapped to an InfluxDB - [bucket](/influxdb/v2.4/reference/glossary/#bucket). - - For more information, see [Database and retention policy - mapping](/influxdb/v2.4/api/influxdb-1x/dbrp/). + This is mapped to an InfluxDB [bucket](/influxdb/v2.4/reference/glossary/#bucket). + For more information, see [Database and retention policy mapping](/influxdb/v2.4/api/influxdb-1x/dbrp/). in: query name: db required: true schema: type: string - - description: > + - description: | The retention policy to query data from. - - This is mapped to an InfluxDB - [bucket](/influxdb/v2.4/reference/glossary/#bucket). - - For more information, see [Database and retention policy - mapping](/influxdb/v2.4/api/influxdb-1x/dbrp/). + This is mapped to an InfluxDB [bucket](/influxdb/v2.4/reference/glossary/#bucket). + For more information, see [Database and retention policy mapping](/influxdb/v2.4/api/influxdb-1x/dbrp/). in: query name: rp schema: type: string - - description: >- - The InfluxQL query to execute. To execute multiple queries, delimit - queries with a semicolon (`;`). + - description: The InfluxQL query to execute. To execute multiple queries, delimit queries with a semicolon (`;`). in: query name: q required: true schema: type: string - - description: > + - description: | A unix timestamp precision. - - Formats timestamps as [unix (epoch) - timestamps](/influxdb/v2.4/reference/glossary/#unix-timestamp) the - specified precision - - instead of [RFC3339 - timestamps](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp) - with nanosecond precision. + Formats timestamps as [unix (epoch) timestamps](/influxdb/v2.4/reference/glossary/#unix-timestamp) the specified precision + instead of [RFC3339 timestamps](/influxdb/v2.4/reference/glossary/#rfc3339-timestamp) with nanosecond precision. in: query name: epoch schema: @@ -19702,9 +18736,7 @@ paths: description: Query results headers: Content-Encoding: - description: >- - Lists encodings (usually compression algorithms) that have been - applied to the response payload. + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. schema: default: identity description: | @@ -19733,9 +18765,7 @@ paths: - doesn't return this error. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: format: int32 type: integer @@ -19763,9 +18793,7 @@ paths: name: p schema: type: string - - description: >- - Bucket to write to. If none exists, InfluxDB creates a bucket with a - default 3-day retention policy. + - description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy. in: query name: db required: true @@ -19781,16 +18809,12 @@ paths: name: precision schema: type: string - - description: >- - When present, its value indicates to the database that compression - is applied to the line protocol body. + - description: When present, its value indicates to the database that compression is applied to the line protocol body. in: header name: Content-Encoding schema: default: identity - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. enum: - gzip - identity @@ -19804,26 +18828,19 @@ paths: required: true responses: '204': - description: >- - Write data is correctly formatted and accepted for writing to the - bucket. + description: Write data is correctly formatted and accepted for writing to the bucket. '400': content: application/json: schema: $ref: '#/components/schemas/LineProtocolError' - description: >- - Line protocol poorly formed and no points were written. Response - can be used to determine the first malformed line in the body - line-protocol. All data in body was rejected and not written. + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. '401': content: application/json: schema: $ref: '#/components/schemas/Error' - description: >- - Token doesn't have sufficient permissions to write to this - organization and bucket or the organization and bucket do not exist. + description: Token doesn't have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. '403': content: application/json: @@ -19835,31 +18852,20 @@ paths: application/json: schema: $ref: '#/components/schemas/LineProtocolLengthError' - description: >- - Write has been rejected because the payload is too large. Error - message returns max size supported. All data in body was rejected - and not written. + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the write again. + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: format: int32 type: integer '503': - description: >- - Server is temporarily unavailable to accept writes. The Retry-After - header describes when to try the write again. + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: format: int32 type: integer @@ -19877,192 +18883,114 @@ security: servers: - url: / tags: - - description: > + - description: | Use one of the following schemes to authenticate to the InfluxDB API: - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - - - [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - + - [Querystring authentication](#section/Authentication/QuerystringAuthentication) name: Authentication x-traitTag: true - - description: > + - description: | Create and manage authorizations (API tokens). - An _authorization_ contains a list of `read` and `write` - - permissions for organization resources and provides an API token for - authentication. - - An authorization belongs to an organization and only contains permissions - for that organization. - + permissions for organization resources and provides an API token for authentication. + An authorization belongs to an organization and only contains permissions for that organization. #### Limitations - - API tokens are visible to the user who created the authorization and to - any - - user with an _[operator - token](/influxdb/v2.3/security/tokens/#operator-token)_. - - In InfluxDB OSS, even if an API token has `read-authorizations` - permission, the - + API tokens are visible to the user who created the authorization and to any + user with an _[operator token](/influxdb/v2.3/security/tokens/#operator-token)_. + In InfluxDB OSS, even if an API token has `read-authorizations` permission, the token can't be used to view its authorization details. - Tokens stop working when the user who created the token is deleted. - - We recommend creating a generic user to create and manage tokens for - writing data. - + We recommend creating a generic user to create and manage tokens for writing data. #### User sessions with authorizations - If a user signs in with username and password, creating a _user session_, - - the session carries the permissions granted by all the user's - authorizations. - - To create a user session, use the [`POST - /api/v2/signin`](#operation/PostSignin) endpoint. - + the session carries the permissions granted by all the user's authorizations. + To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). ### Related endpoints - - [Signin](#tag/Signin) - - [Signout](#tag/Signout) - ### Related guides - - [Authorize API requests](/influxdb/v2.3/api-guide/api_intro/#authentication). - - [Manage API tokens](/influxdb/v2.3/security/tokens/). - - [Assign a token to a specific user](/influxdb/v2.3/security/tokens/create-token/). + - [Authorize API requests](/influxdb/v2.3/api-guide/api_intro/#authentication) + - [Manage API tokens](/influxdb/v2.3/security/tokens/) + - [Assign a token to a specific user](/influxdb/v2.3/security/tokens/create-token/) name: Authorizations - name: Backup - - description: > - Store your data in InfluxDB - [buckets](/influxdb/v2.3/reference/glossary/#bucket). - + - description: | + Store your data in InfluxDB [buckets](/influxdb/v2.3/reference/glossary/#bucket). A bucket is a named location where time series data is stored. All buckets - - have a [retention - period](/influxdb/v2.3/reference/glossary/#retention-period), - + have a [retention period](/influxdb/v2.3/reference/glossary/#retention-period), a duration of time that each data point persists. InfluxDB drops all - points with timestamps older than the bucket’s retention period. - A bucket belongs to an organization. - ### Related guides - - [Manage buckets](/influxdb/v2.3/organizations/buckets/) + - [Manage buckets](/influxdb/v2.3/organizations/buckets/) name: Buckets - name: Cells - name: Checks - - description: > - Many InfluxDB API endpoints require parameters to specify resources--for - example, - + - description: | + Many InfluxDB API endpoints require parameters to specify resources--for example, writing to a **bucket** in an **organization**. - ### Common query parameters - - | Query parameter | Value type | - Description | - - |:------------------------ |:--------------------- - |:-------------------------------------------| - - | `bucket` | string | The bucket name or ID - ([find your bucket](/influxdb/v2.3/organizations/buckets/view-buckets/). | - - | `bucketID` | string | The bucket ID ([find - your bucket](/influxdb/v2.3/organizations/buckets/view-buckets/). | - - | `org` | string | The organization name - or ID ([find your organization](/influxdb/v2.3/organizations/view-orgs/). - | - - | `orgID` | 16-byte string | The organization ID - ([find your organization](/influxdb/v2.3/organizations/view-orgs/). | + | Query parameter | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/v2.3/organizations/buckets/view-buckets/). | + | `bucketID` | string | The bucket ID ([find your bucket](/influxdb/v2.3/organizations/buckets/view-buckets/). | + | `org` | string | The organization name or ID ([find your organization](/influxdb/v2.3/organizations/view-orgs/). | + | `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/v2.3/organizations/view-orgs/). | name: Common parameters x-traitTag: true - name: Config - name: Dashboards - name: Data I/O endpoints - name: DBRPs - - description: > + - description: | Generate profiling and trace reports. - Use routes under `/debug/pprof` to analyze the Go runtime of InfluxDB. - - These endpoints generate [Go runtime - profiles](https://pkg.go.dev/runtime/pprof) - + These endpoints generate [Go runtime profiles](https://pkg.go.dev/runtime/pprof) and **trace** reports. - **Profiles** are collections of stack traces that show call sequences - leading to instances of a particular event, such as allocation. - For more information about **pprof profile** and **trace** reports, - see the following resources: - - [Google pprof tool](https://github.com/google/pprof) - - [Golang diagnostics](https://go.dev/doc/diagnostics) + + - [Google pprof tool](https://github.com/google/pprof) + - [Golang diagnostics](https://go.dev/doc/diagnostics) name: Debug - description: | Delete data from an InfluxDB bucket. name: Delete - - description: > + - description: | InfluxDB API endpoints use standard HTTP request and response headers. - **Note**: Not all operations support all headers. - ### Request headers - - | Header | Value type | - Description | - - |:------------------------ |:--------------------- - |:-------------------------------------------| - - | `Accept` | string | The content type that - the client can understand. | - - | `Authorization` | string | The authorization - scheme and credential. | - - | `Content-Encoding` | string | The compression - applied to the line protocol in the request payload. | - - | `Content-Length` | integer | The size of the - entity-body, in bytes, sent to the database. | - - | `Content-Type` | string | The format of the - data in the request body. | + | Header | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `Accept` | string | The content type that the client can understand. | + | `Authorization` | string | The authorization scheme and credential. | + | `Content-Encoding` | string | The compression applied to the line protocol in the request payload. | + | `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. | + | `Content-Type` | string | The format of the data in the request body. | name: Headers x-traitTag: true - name: Health @@ -20073,101 +19001,50 @@ tags: - name: Metrics - name: NotificationEndpoints - name: NotificationRules - - description: > - Create and manage your - [organizations](/influxdb/v2.3/reference/glossary/#organization). - + - description: | + Create and manage your [organizations](/influxdb/v2.3/reference/glossary/#organization). An organization is a workspace for a group of users. Organizations can be - used to separate different environments, projects, teams or users within - InfluxDB. - - Use the `/api/v2/orgs` endpoints to create, view, and manage - organizations. + Use the `/api/v2/orgs` endpoints to create, view, and manage organizations. name: Organizations - name: Ping - description: | Retrieve data, analyze queries, and get query suggestions. name: Query - - description: > + - description: | See the [**API Quick Start**](/influxdb/v2.3/api-guide/api_intro/) + to get up and running authenticating with tokens, writing to buckets, and querying data. - to get up and running authenticating with tokens, writing to buckets, and - querying data. - - - [**InfluxDB API client - libraries**](/influxdb/v2.3/api-guide/client-libraries/) - - are available for popular languages and ready to import into your - application. + [**InfluxDB API client libraries**](/influxdb/v2.3/api-guide/client-libraries/) + are available for popular languages and ready to import into your application. name: Quick start x-traitTag: true - name: Ready - name: RemoteConnections - name: Replications - name: Resources - - description: > - InfluxDB API endpoints use standard HTTP status codes for success and - failure responses. - + - description: | + InfluxDB API endpoints use standard HTTP status codes for success and failure responses. The response body may include additional details. - For details about a specific operation's response, - see **Responses** and **Response Samples** for that operation. - API operations may return the following HTTP status codes: - |  Code  | Status | Description | - |:-----------:|:------------------------ |:--------------------- | - | `200` | Success | | - - | `204` | No content | For a `POST` request, `204` - indicates that InfluxDB accepted the request and request data is valid. - Asynchronous operations, such as `write`, might not have completed yet. | - - | `400` | Bad request | May indicate one of the - following:
  • Line protocol is malformed. The response body contains - the first malformed line in the data and indicates what was expected. For - partial writes, the number of points written and the number of points - rejected are also included. For more information, check the - `rejected_points` measurement in your `_monitoring` - bucket.
  • `Authorization` header is missing or malformed or the API - token doesn't have permission for the operation.
| - - | `401` | Unauthorized | May indicate one of the - following:
  • `Authorization: Token` header is missing or - malformed
  • API token value is missing from the header
  • API - token doesn't have permission. For more information about token types and - 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 - resource. | - - | `413` | Request entity too large | Request payload exceeds the - size limit. | - - | `422` | Unprocessable entity | Request data is invalid. `code` - and `message` in the response body provide details about the problem. | - - | `429` | Too many requests | API token is temporarily over - the request quota. The `Retry-After` header describes when to try the - request again. | - + | `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. | + | `400` | Bad request | May indicate one of the following:
  • Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your `_monitoring` bucket.
  • `Authorization` header is missing or malformed or the API token doesn't have permission for the operation.
| + | `401` | Unauthorized | May indicate one of the following:
  • `Authorization: Token` header is missing or malformed
  • API token value is missing from the header
  • API token doesn't have permission. For more information about token types and 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 resource. | + | `413` | Request entity too large | Request payload exceeds the size limit. | + | `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. | + | `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. | | `500` | Internal server error | | - - | `503` | Service unavailable | Server is temporarily - unavailable to process the request. The `Retry-After` header describes - when to try the request again. | + | `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. | name: Response codes x-traitTag: true - name: Restore @@ -20181,99 +19058,60 @@ tags: - name: Signout - name: Sources - name: System information endpoints - - description: > + - 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. - 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. - + Use the `/api/v2/tasks` endpoints to create and manage tasks, retry task runs, and retrieve run logs. #### Related guides - - [Get started with tasks](/influxdb/v2.3/process-data/get-started/) - - - [Common data processing - tasks](/influxdb/v2.3/process-data/common-tasks/) + - [Common data processing tasks](/influxdb/v2.3/process-data/common-tasks/) name: Tasks - name: Telegraf Plugins - name: Telegrafs - - description: > + - description: | Export and apply InfluxDB **templates**. - Manage **stacks** of templated InfluxDB resources. - InfluxDB templates are prepackaged configurations for - everything from dashboards and Telegraf to notifications and alerts. - Use InfluxDB templates to quickly configure a fresh instance of InfluxDB, - back up your dashboard configuration, or share your configuration with the - InfluxData community. - - Use the `/api/v2/templates` endpoints to export templates and apply - templates. - + Use the `/api/v2/templates` endpoints to export templates and apply templates. **InfluxDB stacks** are stateful InfluxDB templates that let you - - add, update, and remove installed template resources over time, avoid - duplicating - + add, update, and remove installed template resources over time, avoid duplicating resources when applying the same or similar templates more than once, and - apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. - Use the `/api/v2/stacks` endpoints to manage installed template resources. - #### Related guides - - [InfluxDB stacks](/influxdb/v2.3/influxdb-templates/stacks/) - - [InfluxDB templates](/influxdb/v2.3/influxdb-templates/) name: Templates - - description: > + - description: | Manage users for your organization. - Users are those with access to InfluxDB. - To grant a user permission to access data, add them as a member of an - organization and provide them with an API token. - #### User sessions with authorizations - Optionally, you can scope an authorization (and its API token) to a user. - If a user signs in with username and password, creating a _user session_, - - the session carries the permissions granted by all the user's - authorizations. - - To create a user session, use the [`POST - /api/v2/signin`](#operation/PostSignin) endpoint. - + the session carries the permissions granted by all the user's authorizations. + To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). #### Related guides - - - [Manage users](/influxdb/v2.3/influxdb/latest/users/). - - - [Create a token scoped to a - user](/influxdb/v2.3/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user). + - [Manage users](/influxdb/v2.3/influxdb/latest/users/) + - [Create a token scoped to a user](/influxdb/v2.3/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user) name: Users - name: Variables - name: Views diff --git a/api-docs/v2.4/swaggerV1Compat.yml b/api-docs/v2.4/swaggerV1Compat.yml index 1238df657..ea2970e92 100644 --- a/api-docs/v2.4/swaggerV1Compat.yml +++ b/api-docs/v2.4/swaggerV1Compat.yml @@ -2,20 +2,13 @@ openapi: 3.0.0 info: title: InfluxDB OSS v1 compatibility API documentation version: 2.4.0 v1 compatibility - description: > - The InfluxDB 1.x compatibility /write and /query endpoints work with - InfluxDB 1.x client libraries and third-party integrations like Grafana and - others. - - - If you want to use the latest InfluxDB /api/v2 API instead, see the - [InfluxDB v2 API documentation](/influxdb/v2.4/api/). + description: | + The InfluxDB 1.x compatibility /write and /query endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. + If you want to use the latest InfluxDB /api/v2 API instead, see the [InfluxDB v2 API documentation](/influxdb/v2.4/api/). This documentation is generated from the - - [InfluxDB OpenAPI - specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.4.0/contracts/swaggerV1Compat.yml). + [InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.4.0/contracts/swaggerV1Compat.yml). servers: - url: / paths: @@ -41,9 +34,7 @@ paths: schema: type: string required: true - description: >- - Bucket to write to. If none exists, InfluxDB creates a bucket with a - default 3-day retention policy. + description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy. - in: query name: rp schema: @@ -56,36 +47,25 @@ paths: description: Write precision. - in: header name: Content-Encoding - description: >- - When present, its value indicates to the database that compression - is applied to the line protocol body. + description: When present, its value indicates to the database that compression is applied to the line protocol body. schema: type: string - description: >- - Specifies that the line protocol in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity responses: '204': - description: >- - Write data is correctly formatted and accepted for writing to the - bucket. + description: Write data is correctly formatted and accepted for writing to the bucket. '400': - description: >- - Line protocol poorly formed and no points were written. Response - can be used to determine the first malformed line in the body - line-protocol. All data in body was rejected and not written. + description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. content: application/json: schema: $ref: '#/components/schemas/LineProtocolError' '401': - description: >- - Token does not have sufficient permissions to write to this - organization and bucket or the organization and bucket do not exist. + description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. content: application/json: schema: @@ -97,35 +77,24 @@ paths: schema: $ref: '#/components/schemas/Error' '413': - description: >- - Write has been rejected because the payload is too large. Error - message returns max size supported. All data in body was rejected - and not written. + description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. content: application/json: schema: $ref: '#/components/schemas/LineProtocolLengthError' '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the write again. + description: Token is temporarily over quota. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 '503': - description: >- - Server is temporarily unavailable to accept writes. The Retry-After - header describes when to try the write again. + description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 @@ -155,10 +124,7 @@ paths: name: Accept schema: type: string - description: >- - Specifies how query results should be encoded in the response. - **Note:** With `application/csv`, query results include epoch - timestamps instead of RFC3339 timestamps. + description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps. default: application/json enum: - application/json @@ -167,15 +133,10 @@ paths: - application/x-msgpack - in: header name: Accept-Encoding - description: >- - The Accept-Encoding request HTTP header advertises which content - encoding, usually a compression algorithm, the client is able to - understand. + description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. schema: type: string - description: >- - Specifies that the query response in the body should be encoded - with gzip or not encoded with identity. + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. default: identity enum: - gzip @@ -207,23 +168,16 @@ paths: description: Query results headers: Content-Encoding: - description: >- - The Content-Encoding entity header is used to compress the - media-type. When present, its value indicates which encodings - were applied to the entity-body + description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body schema: type: string - description: >- - Specifies that the response in the body is encoded with gzip - or not encoded with identity. + description: Specifies that the response in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity Trace-Id: - description: >- - The Trace-Id header reports the request's trace ID, if one was - generated. + description: The Trace-Id header reports the request's trace ID, if one was generated. schema: type: string description: Specifies the request's trace ID. @@ -242,14 +196,10 @@ paths: type: string format: binary '429': - description: >- - Token is temporarily over quota. The Retry-After header describes - when to try the read again. + description: Token is temporarily over quota. The Retry-After header describes when to try the read again. headers: Retry-After: - description: >- - A non-negative decimal integer indicating the seconds to delay - after the response is received. + description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 @@ -330,11 +280,8 @@ components: items: {} InfluxQLCSVResponse: type: string - example: > - name,tags,time,test_field,test_tag - test_measurement,,1603740794286107366,1,tag_value - test_measurement,,1603740870053205649,2,tag_value - test_measurement,,1603741221085428881,3,tag_value + example: | + name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value Error: properties: code: @@ -379,15 +326,11 @@ components: type: string op: readOnly: true - description: >- - Op describes the logical code operation during error. Useful for - debugging. + description: Op describes the logical code operation during error. Useful for debugging. type: string err: readOnly: true - description: >- - Err is a stack of errors that occurred during processing of the - request. Useful for debugging. + description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. type: string line: readOnly: true @@ -425,30 +368,21 @@ components: type: apiKey name: Authorization in: header - description: > - Use the [Token - authentication](#section/Authentication/TokenAuthentication) - + description: | + Use the [Token authentication](#section/Authentication/TokenAuthentication) scheme to authenticate to the InfluxDB API. - In your API requests, send an `Authorization` header. - - For the header value, provide the word `Token` followed by a space and - an InfluxDB API token. - + For the header value, provide the word `Token` followed by a space and an InfluxDB API token. The word `Token` is case-sensitive. - ### Syntax - `Authorization: Token YOUR_INFLUX_TOKEN` - For examples and more information, see the following: - [`/authorizations`](#tag/Authorizations) endpoint. - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication). @@ -456,54 +390,37 @@ components: BasicAuthentication: type: http scheme: basic - description: > - Use the HTTP [Basic - authentication](#section/Authentication/BasicAuthentication) - - scheme with clients that support the InfluxDB 1.x convention of username - and password (that don't support the `Authorization: Token` scheme): + description: | + Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication) + scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme): - - For examples and more information, see how to [authenticate with a - username and password](/influxdb/cloud/reference/api/influxdb-1x/). + For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/). QuerystringAuthentication: type: apiKey in: query name: u=&p= - description: > - Use the [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - - scheme with InfluxDB 1.x API parameters to provide credentials through - the query string. + description: | + Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication) + scheme with InfluxDB 1.x API parameters to provide credentials through the query string. - - For examples and more information, see how to [authenticate with a - username and password](/influxdb/cloud/reference/api/influxdb-1x/). + For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/). security: - TokenAuthentication: [] - BasicAuthentication: [] - QuerystringAuthentication: [] tags: - name: Authentication - description: > + description: | The InfluxDB 1.x API requires authentication for all requests. - InfluxDB Cloud uses InfluxDB API tokens to authenticate requests. - For more information, see the following: - - [Token authentication](#section/Authentication/TokenAuthentication) - - [Basic authentication](#section/Authentication/BasicAuthentication) - - - [Querystring - authentication](#section/Authentication/QuerystringAuthentication) - + - [Querystring authentication](#section/Authentication/QuerystringAuthentication) x-traitTag: true