diff --git a/api-docs/cloud-iox/content/info.yml b/api-docs/cloud-iox/content/info.yml new file mode 100644 index 000000000..d6b273513 --- /dev/null +++ b/api-docs/cloud-iox/content/info.yml @@ -0,0 +1,11 @@ +title: InfluxDB Cloud (IOx) API Service +description: | + The InfluxDB HTTP 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). +version: Cloud 2.x +license: + name: MIT + url: 'https://opensource.org/licenses/MIT' \ No newline at end of file diff --git a/api-docs/cloud-iox/content/servers.yml b/api-docs/cloud-iox/content/servers.yml new file mode 100644 index 000000000..dcc5feee1 --- /dev/null +++ b/api-docs/cloud-iox/content/servers.yml @@ -0,0 +1,8 @@ +- url: https://{baseurl} + description: InfluxDB Cloud (IOx) API URL + variables: + baseurl: + enum: + - 'us-east-1-1.aws.cloud2.influxdata.com' + default: 'us-east-1-1.aws.cloud2.influxdata.com' + description: InfluxDB Cloud (IOx) URL diff --git a/api-docs/cloud-iox/content/tag-groups.yml b/api-docs/cloud-iox/content/tag-groups.yml new file mode 100644 index 000000000..1afc47879 --- /dev/null +++ b/api-docs/cloud-iox/content/tag-groups.yml @@ -0,0 +1,33 @@ +- name: Using the InfluxDB HTTP API + tags: + - Quick start + - Authentication + - Supported operations + - Headers + - Pagination + - Response codes + - Data I/O endpoints + - Security and access endpoints + - System information endpoints +- name: All endpoints + tags: + - Authorizations (API tokens) + - Bucket Schemas + - Buckets + - Delete + - DBRPs + - Invokable Scripts + - Legacy Query + - Legacy Write + - Limits + - Organizations + - Query + - Resources + - Routes + - Secrets + - Tasks + - Telegrafs + - Templates + - Usage + - Variables + - Write diff --git a/api-docs/cloud-iox/content/v1compat/info.yml b/api-docs/cloud-iox/content/v1compat/info.yml new file mode 100644 index 000000000..ef53575a8 --- /dev/null +++ b/api-docs/cloud-iox/content/v1compat/info.yml @@ -0,0 +1,11 @@ +title: InfluxDB Cloud IOx v1 compatibility API documentation +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). +license: + name: MIT + url: 'https://opensource.org/licenses/MIT' \ No newline at end of file diff --git a/api-docs/cloud-iox/ref.yml b/api-docs/cloud-iox/ref.yml new file mode 100644 index 000000000..0400c2df4 --- /dev/null +++ b/api-docs/cloud-iox/ref.yml @@ -0,0 +1,16195 @@ +components: + examples: + AuthorizationPostRequest: + description: Creates an authorization. + summary: An authorization for a resource type + value: + description: iot_users read buckets + orgID: INFLUX_ORG_ID + permissions: + - action: read + resource: + type: buckets + AuthorizationWithResourcePostRequest: + description: Creates an authorization for access to a specific resource. + summary: An authorization for a resource + value: + description: iot_users read buckets + orgID: INFLUX_ORG_ID + permissions: + - action: read + resource: + id: INFLUX_BUCKET_ID + type: buckets + AuthorizationWithUserPostRequest: + description: Creates an authorization scoped to a specific user. + summary: An authorization scoped to a user + value: + description: iot_user write to bucket + orgID: INFLUX_ORG_ID + permissions: + - action: write + resource: + id: INFLUX_BUCKET_ID + type: buckets + userID: INFLUX_USER_ID + TaskWithFluxRequest: + description: Sets the `flux` property with Flux task options and a query. + summary: A task with Flux + value: + description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. + flux: "option task = {name: \"CPU Total 1 Hour New\", every: 1h}from(bucket: \"telegraf\") |> range(start: -1h) |> filter(fn: (r) => (r._measurement == \"cpu\")) |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) |> filter(fn: (r) => (r.cpu == \"cpu-total\")) |> aggregateWindow(every: 1h, fn: max) |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")" + status: active + TaskWithScriptRequest: + description: | + Sets properties for a task that runs an _invokable script_. + summary: A task with an invokable script + value: + description: This task runs an invokable script every hour with the defined parameters. + every: 1h + name: CPU Total 1 Hour New + scriptID: SCRIPT_ID + scriptParameters: + bucket: telegraf + filterField: cpu-total + rangeStart: '-1h' + status: active + parameters: + After: + description: | + A resource ID to seek from. + Returns records created after the specified record; + results don't include the specified record. + + Use `after` instead of the `offset` parameter. + For more information about pagination parameters, see [Pagination](/influxdb/cloud/api/#tag/Pagination). + in: query + name: after + required: false + schema: + type: string + Descending: + in: query + name: descending + required: false + schema: + default: false + type: boolean + Limit: + description: | + Limits the number of records returned. Default is `20`. + in: query + name: limit + required: false + schema: + default: 20 + maximum: 100 + minimum: 1 + type: integer + Offset: + description: | + The offset for pagination. + The number of records to skip. + + For more information about pagination parameters, see [Pagination](/influxdb/cloud/api/#tag/Pagination). + in: query + name: offset + required: false + schema: + minimum: 0 + type: integer + SortBy: + in: query + name: sortBy + required: false + schema: + type: string + TraceSpan: + description: OpenTracing span context + example: + baggage: + key: value + span_id: '1' + trace_id: '1' + in: header + name: Zap-Trace-Span + required: false + schema: + type: string + responses: + AuthorizationError: + content: + application/json: + examples: + tokenNotAuthorized: + summary: Token is not authorized to access a resource + value: + code: unauthorized + message: unauthorized access + schema: + properties: + code: + 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. + readOnly: true + type: string + description: | + Unauthorized. The error may indicate one of the following: + + * The `Authorization: Token` header is missing or malformed. + * The API token value is missing from the header. + * The token doesn't have sufficient permissions to write to this organization and bucket. + BadRequestError: + content: + application/json: + examples: + orgProvidedNotFound: + summary: The org or orgID passed doesn't own the token passed in the header + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. + GeneralServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Non 2XX error response from server. + InternalServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Internal server error. + The server encountered an unexpected situation. + ResourceNotFoundError: + content: + application/json: + examples: + bucket-not-found: + summary: Bucket name not found + value: + code: not found + message: bucket "air_sensor" not found + org-not-found: + summary: Organization name not found + value: + code: not found + message: organization name "my-org" not found + orgID-not-found: + summary: Organization ID not found + value: + code: not found + message: organization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + A requested resource was not found. + The response body contains the requested resource type and the name value + (if you passed it)--for example: + + - `"organization name \"my-org\" not found"` + - `"organization not found"`: indicates you passed an ID that did not match + an organization. + ServerError: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Non 2XX error response from server. + schemas: + ASTResponse: + description: Contains the AST for the supplied Flux query + properties: + ast: + $ref: '#/components/schemas/Package' + type: object + AddResourceMemberRequestBody: + properties: + id: + description: | + The ID of the user to add to the resource. + type: string + name: + description: | + The name of the user to add to the resource. + type: string + required: + - id + type: object + AnalyzeQueryResponse: + properties: + errors: + items: + properties: + character: + type: integer + column: + type: integer + line: + type: integer + message: + type: string + type: object + type: array + type: object + ArrayExpression: + description: Used to create and directly specify the elements of an array object + properties: + elements: + description: Elements of the array + items: + $ref: '#/components/schemas/Expression' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + Authorization: + allOf: + - $ref: '#/components/schemas/AuthorizationUpdateRequest' + - properties: + createdAt: + format: date-time + readOnly: true + type: string + id: + description: The authorization ID. + readOnly: true + type: string + links: + example: + self: /api/v2/authorizations/1 + user: /api/v2/users/12 + properties: + self: + $ref: '#/components/schemas/Link' + readOnly: true + user: + $ref: '#/components/schemas/Link' + readOnly: true + readOnly: true + type: object + org: + description: | + The organization name. + Specifies the [organization](/influxdb/cloud-iox/reference/glossary/#organization) + that the token is scoped to. + readOnly: true + type: string + orgID: + description: | + The organization ID. + Specifies the [organization](/influxdb/cloud-iox/reference/glossary/#organization) that the authorization is scoped to. + type: string + permissions: + description: | + The list of permissions. + An authorization must have at least one permission. + items: + $ref: '#/components/schemas/Permission' + minItems: 1 + type: array + token: + description: | + The API token. + The token value is unique to the authorization. + [API tokens](/influxdb/cloud-iox/reference/glossary/#token) are + used to authenticate and authorize InfluxDB API requests and `influx` + CLI commands--after receiving the request, InfluxDB checks that the + token is valid and that the `permissions` allow the requested action(s). + readOnly: true + type: string + updatedAt: + format: date-time + readOnly: true + type: string + user: + description: | + The user name. + Specifies the [user](/influxdb/cloud-iox/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 user ID. Specifies the [user](/influxdb/cloud-iox/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 + required: + - orgID + - permissions + AuthorizationPostRequest: + allOf: + - $ref: '#/components/schemas/AuthorizationUpdateRequest' + - properties: + orgID: + description: | + An organization ID. + Specifies the organization that owns the authorization. + type: string + permissions: + description: | + A list of permissions for an authorization. + In the list, provide at least one `permission` object. + + In a `permission`, the `resource.type` property grants access to all + resources of the specified type. + To grant access to only a specific resource, specify the + `resource.id` property. + items: + $ref: '#/components/schemas/Permission' + minItems: 1 + type: array + userID: + description: | + A user ID. + Specifies the user that the authorization is scoped to. + + When a user authenticates with username and password, + InfluxDB generates a _user session_ with all the permissions + specified by all the user's authorizations. + type: string + type: object + required: + - orgID + - permissions + AuthorizationUpdateRequest: + properties: + description: + description: A description of the token. + type: string + status: + default: active + description: Status of the token. If `inactive`, InfluxDB rejects requests that use the token. + enum: + - active + - inactive + type: string + Authorizations: + properties: + authorizations: + items: + $ref: '#/components/schemas/Authorization' + type: array + links: + $ref: '#/components/schemas/Links' + readOnly: true + type: object + Axes: + description: The viewport for a View's visualizations + properties: + x: + $ref: '#/components/schemas/Axis' + 'y': + $ref: '#/components/schemas/Axis' + required: + - x + - 'y' + type: object + Axis: + description: Axis used in a visualization. + properties: + base: + description: Radix for formatting axis values. + enum: + - '' + - '2' + - '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. + items: + type: string + maxItems: 2 + minItems: 0 + type: array + label: + description: Description of the axis. + type: string + prefix: + description: Label prefix for formatting axis values. + type: string + scale: + $ref: '#/components/schemas/AxisScale' + suffix: + description: Label suffix for formatting axis values. + type: string + type: object + AxisScale: + description: 'Scale is the axis formatting scale. Supported: "log", "linear"' + enum: + - log + - linear + type: string + BadStatement: + description: A placeholder for statements for which no correct statement nodes can be created + properties: + text: + description: Raw source text + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + BandViewProperties: + properties: + adaptiveZoomHide: + type: boolean + axes: + $ref: '#/components/schemas/Axes' + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + geom: + $ref: '#/components/schemas/XYGeom' + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + lowerColumn: + type: string + mainColumn: + type: string + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + timeFormat: + type: string + type: + enum: + - band + type: string + upperColumn: + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - geom + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + type: object + BinaryExpression: + description: uses binary operators to act on two operands in an expression + properties: + left: + $ref: '#/components/schemas/Expression' + operator: + type: string + right: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Block: + description: A set of statements + properties: + body: + description: Block body + items: + $ref: '#/components/schemas/Statement' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + BooleanLiteral: + description: Represents boolean values + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: boolean + type: object + Bucket: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + labels: /api/v2/buckets/1/labels + members: /api/v2/buckets/1/members + org: /api/v2/orgs/2 + owners: /api/v2/buckets/1/owners + self: /api/v2/buckets/1 + write: /api/v2/write?org=2&bucket=1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: The URL to retrieve labels for this bucket. + members: + $ref: '#/components/schemas/Link' + description: The URL to retrieve members that can read this bucket. + org: + $ref: '#/components/schemas/Link' + description: The URL to retrieve parent organization for this bucket. + owners: + $ref: '#/components/schemas/Link' + description: The URL to retrieve owners that can read and write to this bucket. + self: + $ref: '#/components/schemas/Link' + description: The URL for this bucket. + write: + $ref: '#/components/schemas/Link' + description: The URL to write line protocol to this bucket. + readOnly: true + type: object + name: + type: string + orgID: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + rp: + type: string + schemaType: + $ref: '#/components/schemas/SchemaType' + default: implicit + type: + default: user + enum: + - user + - system + readOnly: true + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - name + - retentionRules + Buckets: + properties: + buckets: + items: + $ref: '#/components/schemas/Bucket' + type: array + links: + $ref: '#/components/schemas/Links' + readOnly: true + type: object + BuilderAggregateFunctionType: + enum: + - filter + - group + type: string + BuilderConfig: + properties: + aggregateWindow: + properties: + fillValues: + type: boolean + period: + type: string + type: object + buckets: + items: + type: string + type: array + functions: + items: + $ref: '#/components/schemas/BuilderFunctionsType' + type: array + tags: + items: + $ref: '#/components/schemas/BuilderTagsType' + type: array + type: object + BuilderFunctionsType: + properties: + name: + type: string + type: object + BuilderTagsType: + properties: + aggregateFunctionType: + $ref: '#/components/schemas/BuilderAggregateFunctionType' + key: + type: string + values: + items: + type: string + type: array + type: object + BuiltinStatement: + description: Declares a builtin identifier and its type + properties: + id: + $ref: '#/components/schemas/Identifier' + type: + $ref: '#/components/schemas/NodeType' + type: object + CallExpression: + description: Represents a function call + properties: + arguments: + description: Function arguments + items: + $ref: '#/components/schemas/Expression' + type: array + callee: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Cell: + properties: + h: + format: int32 + type: integer + id: + type: string + links: + properties: + self: + type: string + view: + type: string + type: object + viewID: + description: The reference to a view from the views API. + type: string + w: + format: int32 + type: integer + x: + format: int32 + type: integer + 'y': + format: int32 + type: integer + type: object + CellUpdate: + properties: + h: + format: int32 + type: integer + w: + format: int32 + type: integer + x: + format: int32 + type: integer + 'y': + format: int32 + type: integer + type: object + CellWithViewProperties: + allOf: + - $ref: '#/components/schemas/Cell' + - properties: + name: + type: string + properties: + $ref: '#/components/schemas/ViewProperties' + type: object + type: object + Cells: + items: + $ref: '#/components/schemas/Cell' + type: array + CellsWithViewProperties: + items: + $ref: '#/components/schemas/CellWithViewProperties' + type: array + Check: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + CheckBase: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + description: An optional description of the check. + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + lastRunError: + readOnly: true + type: string + lastRunStatus: + enum: + - failed + - success + - canceled + readOnly: true + type: string + latestCompleted: + 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 + links: + example: + labels: /api/v2/checks/1/labels + members: /api/v2/checks/1/members + owners: /api/v2/checks/1/owners + query: /api/v2/checks/1/query + self: /api/v2/checks/1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: The URL to retrieve labels for this check. + members: + $ref: '#/components/schemas/Link' + description: The URL to retrieve members for this check. + owners: + $ref: '#/components/schemas/Link' + description: The URL to retrieve owners for this check. + query: + $ref: '#/components/schemas/Link' + description: The URL to retrieve the Flux script for this check. + self: + $ref: '#/components/schemas/Link' + description: The URL for this check. + readOnly: true + type: object + name: + type: string + orgID: + description: The ID of the organization that owns this check. + type: string + ownerID: + description: The ID of creator used to create this check. + readOnly: true + type: string + query: + $ref: '#/components/schemas/DashboardQuery' + status: + $ref: '#/components/schemas/TaskStatusType' + taskID: + description: The ID of the task associated with this check. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - name + - orgID + - query + CheckDiscriminator: + discriminator: + mapping: + custom: '#/components/schemas/CustomCheck' + deadman: '#/components/schemas/DeadmanCheck' + threshold: '#/components/schemas/ThresholdCheck' + propertyName: type + oneOf: + - $ref: '#/components/schemas/DeadmanCheck' + - $ref: '#/components/schemas/ThresholdCheck' + - $ref: '#/components/schemas/CustomCheck' + CheckPatch: + properties: + description: + type: string + name: + type: string + status: + enum: + - active + - inactive + type: string + type: object + CheckStatusLevel: + description: The state to record if check matches a criteria. + enum: + - UNKNOWN + - OK + - INFO + - CRIT + - WARN + type: string + CheckViewProperties: + properties: + adaptiveZoomHide: + type: boolean + check: + $ref: '#/components/schemas/Check' + checkID: + type: string + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + type: + enum: + - check + type: string + required: + - type + - shape + - checkID + - queries + - colors + type: object + Checks: + properties: + checks: + items: + $ref: '#/components/schemas/Check' + type: array + links: + $ref: '#/components/schemas/Links' + 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. + example: + configcat_deployments-autopromotionblocker: '#663cd0' + measurement_birdmigration_europe: '#663cd0' + series_id_1: '#edf529' + series_id_2: '#edf529' + type: object + ColumnDataType: + enum: + - integer + - float + - boolean + - string + - unsigned + type: string + ColumnSemanticType: + enum: + - timestamp + - tag + - field + nullable: false + type: string + ConditionalExpression: + description: Selects one of two expressions, `Alternate` or `Consequent`, depending on a third boolean expression, `Test` + properties: + alternate: + $ref: '#/components/schemas/Expression' + consequent: + $ref: '#/components/schemas/Expression' + test: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + ConstantVariableProperties: + properties: + type: + enum: + - constant + type: string + values: + items: + type: string + type: array + CreateCell: + properties: + h: + format: int32 + type: integer + name: + type: string + usingView: + description: Makes a copy of the provided view. + type: string + w: + format: int32 + type: integer + x: + format: int32 + type: integer + 'y': + format: int32 + type: integer + type: object + CreateDashboardRequest: + properties: + description: + description: The user-facing description of the dashboard. + type: string + name: + description: The user-facing name of the dashboard. + type: string + orgID: + description: The ID of the organization that owns the dashboard. + type: string + required: + - orgID + - name + CustomCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + type: + enum: + - custom + type: string + required: + - type + type: object + DBRP: + properties: + bucketID: + description: | + A bucket ID. + Identifies the bucket used as the target for the translation. + type: string + database: + description: | + A database name. + Identifies the InfluxDB v1 database. + type: string + default: + description: | + If set to `true`, this DBRP mapping is the default retention policy + for the database (specified by the `database` property's value). + type: boolean + id: + description: | + The resource ID that InfluxDB uses to uniquely identify the database retention policy (DBRP) mapping. + readOnly: true + type: string + links: + $ref: '#/components/schemas/Links' + orgID: + description: | + An organization ID. + Identifies the [organization](/influxdb/cloud/reference/glossary/#organization) that owns the mapping. + type: string + retention_policy: + description: | + A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. + Identifies the InfluxDB v1 retention policy mapping. + type: string + virtual: + description: Indicates an autogenerated, virtual mapping based on the bucket name. Currently only available in OSS. + type: boolean + required: + - id + - orgID + - bucketID + - database + - retention_policy + - default + type: object + DBRPCreate: + properties: + bucketID: + description: | + A bucket ID. + Identifies the bucket used as the target for the translation. + type: string + database: + description: | + A database name. + Identifies the InfluxDB v1 database. + type: string + default: + description: | + Set to `true` to use this DBRP mapping as the default retention policy + for the database (specified by the `database` property's value). + type: boolean + org: + description: | + An organization name. + Identifies the [organization](/influxdb/cloud/reference/glossary/#organization) that owns the mapping. + type: string + orgID: + description: | + An organization ID. + Identifies the [organization](/influxdb/cloud/reference/glossary/#organization) that owns the mapping. + type: string + retention_policy: + description: | + A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. + Identifies the InfluxDB v1 retention policy mapping. + type: string + required: + - bucketID + - database + - retention_policy + type: object + DBRPGet: + properties: + content: + $ref: '#/components/schemas/DBRP' + required: true + type: object + DBRPUpdate: + properties: + default: + description: | + Set to `true` to use this DBRP mapping as the default retention policy + for the database (specified by the `database` property's value). + To remove the default mapping, set to `false`. + type: boolean + retention_policy: + description: | + A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) name. + Identifies the InfluxDB v1 retention policy mapping. + type: string + DBRPs: + properties: + content: + items: + $ref: '#/components/schemas/DBRP' + type: array + Dashboard: + allOf: + - $ref: '#/components/schemas/CreateDashboardRequest' + - properties: + cells: + $ref: '#/components/schemas/Cells' + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + cells: /api/v2/dashboards/1/cells + labels: /api/v2/dashboards/1/labels + members: /api/v2/dashboards/1/members + org: /api/v2/labels/1 + owners: /api/v2/dashboards/1/owners + self: /api/v2/dashboards/1 + properties: + cells: + $ref: '#/components/schemas/Link' + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + org: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + type: object + meta: + properties: + createdAt: + format: date-time + type: string + updatedAt: + format: date-time + type: string + type: object + type: object + type: object + DashboardColor: + description: Defines an encoding of data value into color space. + properties: + hex: + description: The hex number of the color + maxLength: 7 + minLength: 7 + type: string + id: + description: The unique ID of the view color. + type: string + name: + description: The user-facing name of the hex color. + type: string + type: + description: Type is how the color is used. + enum: + - min + - max + - threshold + - scale + - text + - background + type: string + value: + description: The data value mapped to this color. + format: float + type: number + required: + - id + - type + - hex + - name + - value + type: object + DashboardQuery: + properties: + builderConfig: + $ref: '#/components/schemas/BuilderConfig' + editMode: + $ref: '#/components/schemas/QueryEditMode' + name: + type: string + text: + description: The text of the Flux query. + type: string + type: object + DashboardWithViewProperties: + allOf: + - $ref: '#/components/schemas/CreateDashboardRequest' + - properties: + cells: + $ref: '#/components/schemas/CellsWithViewProperties' + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + cells: /api/v2/dashboards/1/cells + labels: /api/v2/dashboards/1/labels + members: /api/v2/dashboards/1/members + org: /api/v2/labels/1 + owners: /api/v2/dashboards/1/owners + self: /api/v2/dashboards/1 + properties: + cells: + $ref: '#/components/schemas/Link' + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + org: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + type: object + meta: + properties: + createdAt: + format: date-time + type: string + updatedAt: + format: date-time + type: string + type: object + type: object + type: object + Dashboards: + properties: + dashboards: + items: + $ref: '#/components/schemas/Dashboard' + type: array + links: + $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). + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + format: date-time + type: string + type: object + DeadmanCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + every: + description: Check repetition interval. + type: string + level: + $ref: '#/components/schemas/CheckStatusLevel' + offset: + description: Duration to delay after the schedule, before executing check. + type: string + reportZero: + 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. + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + tags: + description: List of tags to write to each status. + items: + properties: + key: + type: string + value: + type: string + type: object + type: array + timeSince: + description: String duration before deadman triggers. + type: string + type: + enum: + - deadman + type: string + required: + - type + type: object + DecimalPlaces: + 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 + format: int32 + type: integer + isEnforced: + description: Indicates whether decimal point setting should be enforced + type: boolean + type: object + DeletePredicateRequest: + description: The delete predicate request. + properties: + 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](/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](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). + The latest time to delete from. + format: date-time + type: string + required: + - start + - stop + type: object + Dialect: + description: | + Options for tabular data output. + 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). + properties: + annotations: + description: | + Annotation rows to include in the results. + An _annotation_ is metadata associated with an object (column) in the data model. + + #### Related guides + + - See [Annotated CSV annotations](/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). + items: + enum: + - group + - datatype + - default + type: string + type: array + uniqueItems: true + commentPrefix: + default: '#' + description: The character prefixed to comment strings. Default is a number sign (`#`). + maxLength: 1 + minLength: 0 + type: string + dateTimeFormat: + default: RFC3339 + description: | + The format for timestamps in results. + 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 + - RFC3339Nano + type: string + delimiter: + default: ',' + description: The separator used between cells. Default is a comma (`,`). + maxLength: 1 + minLength: 1 + type: string + header: + default: true + description: If true, the results contain a header row. + type: boolean + type: object + DictExpression: + description: Used to create and directly specify the elements of a dictionary + properties: + elements: + description: Elements of the dictionary + items: + $ref: '#/components/schemas/DictItem' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + DictItem: + description: A key-value pair in a dictionary. + properties: + key: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + val: + $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. + properties: + magnitude: + type: integer + type: + $ref: '#/components/schemas/NodeType' + unit: + 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 + properties: + type: + $ref: '#/components/schemas/NodeType' + values: + description: Duration values + items: + $ref: '#/components/schemas/Duration' + type: array + type: object + Error: + properties: + code: + $ref: '#/components/schemas/ErrorCode' + description: code is the machine-readable error code. + enum: + - internal error + - not implemented + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + - request too large + - unsupported media type + readOnly: true + type: string + err: + description: Stack of errors that occurred during processing of the request. Useful for debugging. + readOnly: true + type: string + message: + description: Human-readable message. + readOnly: true + type: string + op: + description: Describes the logical code operation when the error occurred. Useful for debugging. + readOnly: true + type: string + required: + - code + ErrorCode: + description: code is the machine-readable error code. + enum: + - internal error + - not implemented + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + - request too large + - unsupported media type + readOnly: true + type: string + Expression: + oneOf: + - $ref: '#/components/schemas/ArrayExpression' + - $ref: '#/components/schemas/DictExpression' + - $ref: '#/components/schemas/FunctionExpression' + - $ref: '#/components/schemas/BinaryExpression' + - $ref: '#/components/schemas/CallExpression' + - $ref: '#/components/schemas/ConditionalExpression' + - $ref: '#/components/schemas/LogicalExpression' + - $ref: '#/components/schemas/MemberExpression' + - $ref: '#/components/schemas/IndexExpression' + - $ref: '#/components/schemas/ObjectExpression' + - $ref: '#/components/schemas/ParenExpression' + - $ref: '#/components/schemas/PipeExpression' + - $ref: '#/components/schemas/UnaryExpression' + - $ref: '#/components/schemas/BooleanLiteral' + - $ref: '#/components/schemas/DateTimeLiteral' + - $ref: '#/components/schemas/DurationLiteral' + - $ref: '#/components/schemas/FloatLiteral' + - $ref: '#/components/schemas/IntegerLiteral' + - $ref: '#/components/schemas/PipeLiteral' + - $ref: '#/components/schemas/RegexpLiteral' + - $ref: '#/components/schemas/StringLiteral' + - $ref: '#/components/schemas/UnsignedIntegerLiteral' + - $ref: '#/components/schemas/Identifier' + ExpressionStatement: + 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' + type: + $ref: '#/components/schemas/NodeType' + type: object + Field: + properties: + alias: + description: Alias overrides the field name in the returned response. Applies only if type is `func` + type: string + args: + description: Args are the arguments to the function + items: + $ref: '#/components/schemas/Field' + type: array + type: + description: '`type` describes the field type. `func` is a function. `field` is a field reference.' + enum: + - func + - field + - integer + - number + - regex + - wildcard + type: string + value: + description: value is the value of the field. Meaning of the value is implied by the `type` key + type: string + type: object + File: + description: Represents a source from a single file + properties: + body: + description: List of Flux statements + items: + $ref: '#/components/schemas/Statement' + type: array + imports: + description: A list of package imports + items: + $ref: '#/components/schemas/ImportDeclaration' + type: array + name: + description: The name of the file. + type: string + package: + $ref: '#/components/schemas/PackageClause' + type: + $ref: '#/components/schemas/NodeType' + type: object + Flags: + additionalProperties: true + type: object + FloatLiteral: + description: Represents floating point numbers according to the double representations defined by the IEEE-754-1985 + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: number + type: object + FluxResponse: + description: Rendered flux that backs the check or notification. + properties: + flux: + type: string + FluxSuggestion: + properties: + name: + type: string + params: + additionalProperties: + type: string + type: object + type: object + FluxSuggestions: + properties: + funcs: + items: + $ref: '#/components/schemas/FluxSuggestion' + type: array + type: object + FunctionExpression: + description: Function expression + properties: + body: + $ref: '#/components/schemas/Node' + params: + description: Function parameters + items: + $ref: '#/components/schemas/Property' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + GaugeViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + note: + type: string + prefix: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + suffix: + type: string + tickPrefix: + type: string + tickSuffix: + type: string + type: + enum: + - gauge + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - prefix + - tickPrefix + - suffix + - tickSuffix + - decimalPlaces + type: object + GeoCircleViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - properties: + colorDimension: + $ref: '#/components/schemas/Axis' + colorField: + description: Circle color field + type: string + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + interpolateColors: + description: Interpolate circle color based on displayed value + type: boolean + radius: + description: Maximum radius size in pixels + type: integer + radiusDimension: + $ref: '#/components/schemas/Axis' + radiusField: + description: Radius field + type: string + required: + - radiusField + - radiusDimension + - colorField + - colorDimension + - colors + type: object + GeoHeatMapViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - properties: + blur: + description: Blur for heatmap points + type: integer + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + intensityDimension: + $ref: '#/components/schemas/Axis' + intensityField: + description: Intensity field + type: string + radius: + description: Radius size in pixels + type: integer + required: + - intensityField + - intensityDimension + - radius + - blur + - colors + type: object + GeoPointMapViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - properties: + colorDimension: + $ref: '#/components/schemas/Axis' + colorField: + description: Marker color field + type: string + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + isClustered: + description: Cluster close markers together + type: boolean + tooltipColumns: + description: An array for which columns to display in tooltip + items: + type: string + type: array + required: + - colorField + - colorDimension + - colors + type: object + GeoTrackMapViewLayer: + allOf: + - $ref: '#/components/schemas/GeoViewLayerProperties' + - required: + - trackWidth + - speed + - randomColors + - trackPointVisualization + type: object + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + randomColors: + description: Assign different colors to different tracks + type: boolean + speed: + description: Speed of the track animation + type: integer + trackWidth: + description: Width of the track + type: integer + GeoViewLayer: + oneOf: + - $ref: '#/components/schemas/GeoCircleViewLayer' + - $ref: '#/components/schemas/GeoHeatMapViewLayer' + - $ref: '#/components/schemas/GeoPointMapViewLayer' + - $ref: '#/components/schemas/GeoTrackMapViewLayer' + type: object + GeoViewLayerProperties: + properties: + type: + enum: + - heatmap + - circleMap + - pointMap + - trackMap + type: string + required: + - type + type: object + GeoViewProperties: + properties: + allowPanAndZoom: + default: true + description: If true, map zoom and pan controls are enabled on the dashboard view + type: boolean + center: + description: Coordinates of the center of the map + properties: + lat: + description: Latitude of the center of the map + format: double + type: number + lon: + description: Longitude of the center of the map + format: double + type: number + required: + - lat + - lon + type: object + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + detectCoordinateFields: + default: true + 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' + layers: + description: List of individual layers shown in the map + items: + $ref: '#/components/schemas/GeoViewLayer' + type: array + mapStyle: + description: Define map type - regular, satellite etc. + type: string + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + s2Column: + description: String to define the column + type: string + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + type: + enum: + - geo + type: string + useS2CellID: + description: If true, S2 column is used to calculate lat/lon + type: boolean + zoom: + description: Zoom level used for initial display of the map + format: double + maximum: 28 + minimum: 1 + type: number + required: + - type + - shape + - queries + - note + - showNoteWhenEmpty + - center + - zoom + - allowPanAndZoom + - detectCoordinateFields + - layers + type: object + GreaterThreshold: + allOf: + - $ref: '#/components/schemas/ThresholdBase' + - properties: + type: + enum: + - greater + type: string + value: + format: float + type: number + required: + - type + - value + type: object + HTTPNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + authMethod: + enum: + - none + - basic + - bearer + type: string + contentTemplate: + type: string + headers: + additionalProperties: + type: string + description: Customized headers. + type: object + method: + enum: + - POST + - GET + - PUT + type: string + password: + type: string + token: + type: string + url: + type: string + username: + type: string + required: + - url + - authMethod + - method + type: object + type: object + HTTPNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/HTTPNotificationRuleBase' + HTTPNotificationRuleBase: + properties: + type: + enum: + - http + type: string + url: + type: string + required: + - type + type: object + HealthCheck: + properties: + checks: + items: + $ref: '#/components/schemas/HealthCheck' + type: array + commit: + type: string + message: + type: string + name: + type: string + status: + enum: + - pass + - fail + type: string + version: + type: string + required: + - name + - status + type: object + HeatmapViewProperties: + properties: + adaptiveZoomHide: + type: boolean + binSize: + type: number + colors: + description: Colors define color encoding of data into a visualization + items: + type: string + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + timeFormat: + type: string + type: + enum: + - heatmap + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + type: number + maxItems: 2 + type: array + xPrefix: + type: string + xSuffix: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yAxisLabel: + type: string + yColumn: + type: string + yDomain: + items: + type: number + maxItems: 2 + type: array + yPrefix: + type: string + ySuffix: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - yColumn + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + - binSize + type: object + HistogramViewProperties: + properties: + binCount: + type: integer + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + fillColumns: + items: + type: string + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + type: + enum: + - histogram + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + format: float + type: number + type: array + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - fillColumns + - xDomain + - xAxisLabel + - position + - binCount + type: object + Identifier: + description: A valid Flux identifier + properties: + name: + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + ImportDeclaration: + description: Declares a package import + properties: + as: + $ref: '#/components/schemas/Identifier' + path: + $ref: '#/components/schemas/StringLiteral' + type: + $ref: '#/components/schemas/NodeType' + type: object + IndexExpression: + description: Represents indexing into an array + properties: + array: + $ref: '#/components/schemas/Expression' + index: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + 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 + type: string + InfluxqlJsonResponse: + description: JSON Response to InfluxQL Query + properties: + results: + items: + properties: + error: + type: string + series: + items: + properties: + columns: + items: + type: string + type: array + name: + type: string + partial: + type: boolean + tags: + additionalProperties: + type: string + type: object + values: + items: + items: {} + type: array + type: array + type: object + type: array + statement_id: + type: integer + type: object + type: array + type: object + IntegerLiteral: + description: Represents integer numbers + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + IsOnboarding: + properties: + allowed: + description: | + If `true`, the InfluxDB instance hasn't had initial setup; + `false` otherwise. + type: boolean + type: object + Label: + properties: + id: + readOnly: true + type: string + name: + type: string + orgID: + readOnly: true + type: string + properties: + additionalProperties: + type: string + description: | + Key-value pairs associated with this label. + To remove a property, send an update with an empty value (`""`) for the key. + example: + color: ffb3b3 + description: this is a description + type: object + type: object + LabelCreateRequest: + properties: + name: + type: string + orgID: + type: string + properties: + additionalProperties: + type: string + description: | + Key-value pairs associated with this label. + + To remove a property, send an update with an empty value (`""`) for the key. + example: + color: ffb3b3 + description: this is a description + type: object + required: + - orgID + - name + type: object + LabelMapping: + description: A _label mapping_ contains a `label` ID to attach to a resource. + properties: + labelID: + description: | + A label ID. + Specifies the label to attach. + type: string + required: + - labelID + type: object + LabelResponse: + properties: + label: + $ref: '#/components/schemas/Label' + links: + $ref: '#/components/schemas/Links' + type: object + LabelUpdate: + properties: + name: + type: string + properties: + additionalProperties: + description: | + Key-value pairs associated with this label. + + To remove a property, send an update with an empty value (`""`) for the key. + type: string + example: + color: ffb3b3 + description: this is a description + type: object + type: object + Labels: + items: + $ref: '#/components/schemas/Label' + type: array + LabelsResponse: + properties: + labels: + $ref: '#/components/schemas/Labels' + links: + $ref: '#/components/schemas/Links' + type: object + LanguageRequest: + description: Flux query to be analyzed. + properties: + query: + description: | + The Flux query script to be analyzed. + type: string + required: + - query + type: object + LatLonColumn: + description: Object type for key and column definitions + properties: + column: + description: Column to look up Lat/Lon + type: string + key: + description: Key to determine whether the column is tag/field + type: string + required: + - key + - column + type: object + LatLonColumns: + description: Object type to define lat/lon columns + properties: + lat: + $ref: '#/components/schemas/LatLonColumn' + lon: + $ref: '#/components/schemas/LatLonColumn' + required: + - lat + - lon + type: object + LegacyAuthorizationPostRequest: + allOf: + - $ref: '#/components/schemas/AuthorizationUpdateRequest' + - properties: + orgID: + description: The organization ID. Identifies the organization that the authorization is scoped to. + type: string + permissions: + description: | + The list of permissions that provide `read` and `write` access to organization resources. + An authorization must contain at least one permission. + items: + $ref: '#/components/schemas/Permission' + minItems: 1 + type: array + token: + description: The name that you provide for the authorization. + type: string + userID: + description: The user ID. Identifies the user that the authorization is scoped to. + type: string + type: object + required: + - orgID + - permissions + LesserThreshold: + allOf: + - $ref: '#/components/schemas/ThresholdBase' + - properties: + type: + enum: + - lesser + type: string + value: + format: float + type: number + required: + - type + - value + type: object + Limit: + description: These are org limits similar to those configured in/by quartz. + properties: + bucket: + properties: + maxBuckets: + type: integer + maxRetentionDuration: + description: Max bucket retention duration in nanoseconds. 0 is unlimited. + type: integer + required: + - maxBuckets + - maxRetentionDuration + type: object + check: + properties: + maxChecks: + type: integer + required: + - maxChecks + type: object + dashboard: + properties: + maxDashboards: + type: integer + required: + - maxDashboards + type: object + features: + properties: + allowDelete: + description: allow delete predicate endpoint + type: boolean + type: object + notificationEndpoint: + properties: + blockedNotificationEndpoints: + description: comma separated list of notification endpoints + example: http,pagerduty + type: string + required: + - blockNotificationEndpoints + type: object + notificationRule: + properties: + blockedNotificationRules: + description: comma separated list of notification rules + example: http,pagerduty + type: string + maxNotifications: + type: integer + required: + - maxNotifications + - blockNotificationRules + type: object + orgID: + type: string + rate: + properties: + cardinality: + description: Allowed organization total cardinality. 0 is unlimited. + type: integer + concurrentDeleteRequests: + description: Allowed organization concurrent outstanding delete requests. + type: integer + concurrentReadRequests: + description: Allowed concurrent queries. 0 is unlimited. + type: integer + concurrentWriteRequests: + description: Allowed concurrent writes. 0 is unlimited. + type: integer + deleteRequestsPerSecond: + description: Allowed organization delete request rate. + type: integer + queryTime: + description: Query Time in nanoseconds + type: integer + readKBs: + description: Query limit in kb/sec. 0 is unlimited. + type: integer + writeKBs: + description: Write limit in kb/sec. 0 is unlimited. + type: integer + required: + - readKBs + - queryTime + - concurrentReadRequests + - writeKBs + - concurrentWriteRequests + - cardinality + type: object + stack: + properties: + enabled: + type: boolean + required: + - enabled + type: object + task: + properties: + maxTasks: + type: integer + required: + - maxTasks + type: object + timeout: + properties: + queryUnconditionalTimeoutSeconds: + type: integer + queryidleWriteTimeoutSeconds: + type: integer + required: + - queryUnconditionalTimeoutSeconds + - queryidleWriteTimeoutSeconds + type: object + required: + - rate + - bucket + - task + - dashboard + - check + - notificationRule + - notificationEndpoint + type: object + LinePlusSingleStatProperties: + properties: + adaptiveZoomHide: + type: boolean + axes: + $ref: '#/components/schemas/Axes' + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + prefix: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shadeBelow: + type: boolean + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + suffix: + type: string + timeFormat: + type: string + type: + enum: + - line-plus-single-stat + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + - prefix + - suffix + - decimalPlaces + - position + type: object + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + readOnly: true + type: string + err: + description: Stack of errors that occurred during processing of the request. Useful for debugging. + readOnly: true + type: string + line: + description: First line in the request body that contains malformed data. + format: int32 + readOnly: true + type: integer + message: + description: Human-readable message. + readOnly: true + type: string + op: + description: Describes the logical code operation when the error occurred. Useful for debugging. + readOnly: true + type: string + required: + - code + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + enum: + - invalid + readOnly: true + type: string + message: + description: Human-readable message. + readOnly: true + type: string + required: + - code + - message + Link: + description: URI of resource. + format: uri + readOnly: true + type: string + Links: + description: | + URI pointers for additional paged results. + properties: + next: + $ref: '#/components/schemas/Link' + prev: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + required: + - self + type: object + LogEvent: + properties: + message: + description: A description of the event that occurred. + example: Halt and catch fire + readOnly: true + type: string + runID: + description: The ID of the task run that generated the event. + readOnly: true + type: string + time: + 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 + properties: + left: + $ref: '#/components/schemas/Expression' + operator: + type: string + right: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Logs: + properties: + events: + items: + $ref: '#/components/schemas/LogEvent' + readOnly: true + type: array + type: object + MapVariableProperties: + properties: + type: + enum: + - map + type: string + values: + additionalProperties: + type: string + type: object + MarkdownViewProperties: + properties: + note: + type: string + shape: + enum: + - chronograf-v2 + type: string + type: + enum: + - markdown + type: string + required: + - type + - shape + - note + type: object + MeasurementSchema: + description: Definition of a measurement schema. + example: + bucketID: ba3c5e7f9b0a0010 + columns: + - format: unix timestamp + name: time + type: integer + - name: host + type: tag + - name: region + type: tag + - dataType: float + name: usage_user + type: field + - dataType: float + name: usage_user + type: field + createdAt: '2021-01-21T00:48:40.993Z' + id: 1a3c5e7f9b0a8642 + name: cpu + orgID: 0a3c5e7f9b0a0001 + updatedAt: '2021-01-21T00:48:40.993Z' + properties: + bucketID: + description: The ID of the bucket that the measurement schema is associated with. + type: string + columns: + description: Ordered collection of column definitions. + items: + $ref: '#/components/schemas/MeasurementSchemaColumn' + type: array + createdAt: + format: date-time + readOnly: true + type: string + id: + readOnly: true + type: string + name: + nullable: false + type: string + orgID: + description: The ID of the organization. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - id + - name + - columns + - createdAt + - updatedAt + type: object + MeasurementSchemaColumn: + description: Definition of a measurement schema column. + example: + format: unix timestamp + name: time + type: integer + properties: + dataType: + $ref: '#/components/schemas/ColumnDataType' + name: + type: string + type: + $ref: '#/components/schemas/ColumnSemanticType' + required: + - name + - type + type: object + MeasurementSchemaCreateRequest: + description: Create a new measurement schema. + example: + columns: + - format: unix timestamp + name: time + type: integer + - name: host + type: tag + - name: region + type: tag + - dataType: float + name: usage_user + type: field + - dataType: float + name: usage_user + type: field + name: cpu + properties: + columns: + description: Ordered collection of column definitions. + items: + $ref: '#/components/schemas/MeasurementSchemaColumn' + type: array + name: + description: | + The [measurement](/influxdb/cloud/reference/glossary/#measurement) + name. + type: string + required: + - name + - columns + type: object + MeasurementSchemaList: + description: A list of measurement schemas returning summary information + example: + measurementSchemas: + - bucketID: ba3c5e7f9b0a0010 + createdAt: '2021-01-21T00:48:40.993Z' + id: 1a3c5e7f9b0a8642 + name: cpu + orgID: 0a3c5e7f9b0a0001 + updatedAt: '2021-01-21T00:48:40.993Z' + - bucketID: ba3c5e7f9b0a0010 + createdAt: '2021-01-21T00:48:40.993Z' + id: 1a3c5e7f9b0a8643 + name: memory + orgID: 0a3c5e7f9b0a0001 + updatedAt: '2021-01-21T00:48:40.993Z' + - bucketID: ba3c5e7f9b0a0010 + createdAt: '2021-01-21T00:48:40.993Z' + id: 1a3c5e7f9b0a8644 + name: disk + orgID: 0a3c5e7f9b0a0001 + updatedAt: '2021-01-21T00:48:40.993Z' + properties: + measurementSchemas: + items: + $ref: '#/components/schemas/MeasurementSchema' + type: array + required: + - measurementSchemas + type: object + MeasurementSchemaUpdateRequest: + description: Update an existing measurement schema + example: + columns: + - format: unix timestamp + name: time + type: integer + - name: host + type: tag + - name: region + type: tag + - dataType: float + name: usage_user + type: field + - dataType: float + name: usage_user + type: field + properties: + columns: + description: An ordered collection of column definitions + items: + $ref: '#/components/schemas/MeasurementSchemaColumn' + type: array + required: + - columns + type: object + MemberAssignment: + description: Object property assignment + properties: + init: + $ref: '#/components/schemas/Expression' + member: + $ref: '#/components/schemas/MemberExpression' + type: + $ref: '#/components/schemas/NodeType' + type: object + MemberExpression: + description: Represents accessing a property of an object + properties: + object: + $ref: '#/components/schemas/Expression' + property: + $ref: '#/components/schemas/PropertyKey' + type: + $ref: '#/components/schemas/NodeType' + type: object + MosaicViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + type: string + type: array + fillColumns: + items: + type: string + type: array + generateXAxisTicks: + items: + type: string + type: array + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + timeFormat: + type: string + type: + enum: + - mosaic + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + type: number + maxItems: 2 + type: array + xPrefix: + type: string + xSuffix: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yAxisLabel: + type: string + yDomain: + items: + type: number + maxItems: 2 + type: array + yLabelColumnSeparator: + type: string + yLabelColumns: + items: + type: string + type: array + yPrefix: + type: string + ySeriesColumns: + items: + type: string + type: array + ySuffix: + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - ySeriesColumns + - fillColumns + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + type: object + Node: + oneOf: + - $ref: '#/components/schemas/Expression' + - $ref: '#/components/schemas/Block' + NodeType: + description: Type of AST node + type: string + NotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + NotificationEndpointBase: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + description: An optional description of the notification endpoint. + type: string + id: + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + example: + labels: /api/v2/notificationEndpoints/1/labels + members: /api/v2/notificationEndpoints/1/members + owners: /api/v2/notificationEndpoints/1/owners + self: /api/v2/notificationEndpoints/1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: The URL to retrieve labels for this endpoint. + members: + $ref: '#/components/schemas/Link' + description: The URL to retrieve members for this endpoint. + owners: + $ref: '#/components/schemas/Link' + description: The URL to retrieve owners for this endpoint. + self: + $ref: '#/components/schemas/Link' + description: The URL for this endpoint. + readOnly: true + type: object + name: + type: string + orgID: + type: string + status: + default: active + description: The status of the endpoint. + enum: + - active + - inactive + type: string + type: + $ref: '#/components/schemas/NotificationEndpointType' + updatedAt: + format: date-time + readOnly: true + type: string + userID: + type: string + required: + - type + - name + type: object + NotificationEndpointDiscriminator: + discriminator: + mapping: + http: '#/components/schemas/HTTPNotificationEndpoint' + pagerduty: '#/components/schemas/PagerDutyNotificationEndpoint' + slack: '#/components/schemas/SlackNotificationEndpoint' + telegram: '#/components/schemas/TelegramNotificationEndpoint' + propertyName: type + oneOf: + - $ref: '#/components/schemas/SlackNotificationEndpoint' + - $ref: '#/components/schemas/PagerDutyNotificationEndpoint' + - $ref: '#/components/schemas/HTTPNotificationEndpoint' + - $ref: '#/components/schemas/TelegramNotificationEndpoint' + NotificationEndpointType: + enum: + - slack + - pagerduty + - http + - telegram + type: string + NotificationEndpointUpdate: + properties: + description: + type: string + name: + type: string + status: + enum: + - active + - inactive + type: string + type: object + NotificationEndpoints: + properties: + links: + $ref: '#/components/schemas/Links' + notificationEndpoints: + items: + $ref: '#/components/schemas/NotificationEndpoint' + type: array + NotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleDiscriminator' + NotificationRuleBase: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + description: An optional description of the notification rule. + type: string + endpointID: + type: string + every: + description: The notification repetition interval. + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + lastRunError: + readOnly: true + type: string + lastRunStatus: + enum: + - failed + - success + - canceled + readOnly: true + type: string + latestCompleted: + 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. + type: integer + limitEvery: + description: Don't notify me more than times every seconds. If set, limit cannot be empty. + type: integer + links: + example: + labels: /api/v2/notificationRules/1/labels + members: /api/v2/notificationRules/1/members + owners: /api/v2/notificationRules/1/owners + query: /api/v2/notificationRules/1/query + self: /api/v2/notificationRules/1 + properties: + labels: + $ref: '#/components/schemas/Link' + description: The URL to retrieve labels for this notification rule. + members: + $ref: '#/components/schemas/Link' + description: The URL to retrieve members for this notification rule. + owners: + $ref: '#/components/schemas/Link' + description: The URL to retrieve owners for this notification rule. + query: + $ref: '#/components/schemas/Link' + description: The URL to retrieve the Flux script for this notification rule. + self: + $ref: '#/components/schemas/Link' + description: The URL for this endpoint. + readOnly: true + type: object + name: + description: Human-readable name describing the notification rule. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + orgID: + description: The ID of the organization that owns this notification rule. + type: string + ownerID: + description: The ID of creator used to create this notification rule. + readOnly: true + type: string + runbookLink: + type: string + sleepUntil: + type: string + status: + $ref: '#/components/schemas/TaskStatusType' + statusRules: + description: List of status rules the notification rule attempts to match. + items: + $ref: '#/components/schemas/StatusRule' + minItems: 1 + type: array + tagRules: + description: List of tag rules the notification rule attempts to match. + items: + $ref: '#/components/schemas/TagRule' + type: array + taskID: + description: The ID of the task associated with this notification rule. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - orgID + - status + - name + - statusRules + - endpointID + type: object + NotificationRuleDiscriminator: + discriminator: + mapping: + http: '#/components/schemas/HTTPNotificationRule' + pagerduty: '#/components/schemas/PagerDutyNotificationRule' + slack: '#/components/schemas/SlackNotificationRule' + smtp: '#/components/schemas/SMTPNotificationRule' + telegram: '#/components/schemas/TelegramNotificationRule' + propertyName: type + oneOf: + - $ref: '#/components/schemas/SlackNotificationRule' + - $ref: '#/components/schemas/SMTPNotificationRule' + - $ref: '#/components/schemas/PagerDutyNotificationRule' + - $ref: '#/components/schemas/HTTPNotificationRule' + - $ref: '#/components/schemas/TelegramNotificationRule' + NotificationRuleUpdate: + properties: + description: + type: string + name: + type: string + status: + enum: + - active + - inactive + type: string + type: object + NotificationRules: + properties: + links: + $ref: '#/components/schemas/Links' + notificationRules: + items: + $ref: '#/components/schemas/NotificationRule' + type: array + ObjectExpression: + description: Allows the declaration of an anonymous object within a declaration + properties: + properties: + description: Object properties + items: + $ref: '#/components/schemas/Property' + type: array + type: + $ref: '#/components/schemas/NodeType' + type: object + OnboardingRequest: + properties: + bucket: + type: string + limit: + $ref: '#/components/schemas/Limit' + org: + type: string + password: + type: string + retentionPeriodHrs: + deprecated: true + type: integer + retentionPeriodSeconds: + type: integer + username: + type: string + required: + - username + - org + - bucket + type: object + OnboardingResponse: + properties: + auth: + $ref: '#/components/schemas/Authorization' + bucket: + $ref: '#/components/schemas/Bucket' + org: + $ref: '#/components/schemas/Organization' + user: + $ref: '#/components/schemas/UserResponse' + type: object + OptionStatement: + description: A single variable declaration + properties: + assignment: + oneOf: + - $ref: '#/components/schemas/VariableAssignment' + - $ref: '#/components/schemas/MemberAssignment' + type: + $ref: '#/components/schemas/NodeType' + type: object + Organization: + properties: + createdAt: + format: date-time + readOnly: true + type: string + defaultStorageType: + description: Discloses whether the organization uses TSM or IOx. + enum: + - tsm + - iox + type: string + description: + type: string + id: + readOnly: true + type: string + links: + example: + buckets: /api/v2/buckets?org=myorg + dashboards: /api/v2/dashboards?org=myorg + labels: /api/v2/orgs/1/labels + members: /api/v2/orgs/1/members + owners: /api/v2/orgs/1/owners + secrets: /api/v2/orgs/1/secrets + self: /api/v2/orgs/1 + tasks: /api/v2/tasks?org=myorg + properties: + buckets: + $ref: '#/components/schemas/Link' + dashboards: + $ref: '#/components/schemas/Link' + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + secrets: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + tasks: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + name: + type: string + status: + default: active + description: If inactive, the organization is inactive. + enum: + - active + - inactive + type: string + updatedAt: + format: date-time + readOnly: true + type: string + required: + - name + Organizations: + properties: + links: + $ref: '#/components/schemas/Links' + orgs: + items: + $ref: '#/components/schemas/Organization' + type: array + type: object + Package: + description: Represents a complete package source tree. + properties: + files: + description: Package files + items: + $ref: '#/components/schemas/File' + type: array + package: + description: Package name + type: string + path: + description: Package import path + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + PackageClause: + description: Defines a package identifier + properties: + name: + $ref: '#/components/schemas/Identifier' + type: + $ref: '#/components/schemas/NodeType' + type: object + PagerDutyNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + clientURL: + type: string + routingKey: + type: string + required: + - routingKey + type: object + type: object + PagerDutyNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/PagerDutyNotificationRuleBase' + PagerDutyNotificationRuleBase: + properties: + messageTemplate: + type: string + type: + enum: + - pagerduty + type: string + required: + - type + - messageTemplate + type: object + Params: + properties: + params: + additionalProperties: + enum: + - any + - bool + - duration + - float + - int + - string + - time + - uint + type: string + description: | + The `params` keys and value type defined in the script. + type: object + type: object + ParenExpression: + description: Represents an expression wrapped in parenthesis + properties: + expression: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + PasswordResetBody: + properties: + password: + type: string + required: + - password + PatchBucketRequest: + description: | + An object that contains updated bucket properties to apply. + properties: + description: + description: | + A description of the bucket. + type: string + name: + description: | + The name of the bucket. + type: string + retentionRules: + $ref: '#/components/schemas/PatchRetentionRules' + type: object + PatchOrganizationRequest: + description: | + An object that contains updated organization properties to apply. + properties: + description: + description: | + The description of the organization. + type: string + name: + description: | + The name of the organization. + type: string + type: object + PatchRetentionRule: + properties: + everySeconds: + default: 2592000 + description: | + The number of seconds to keep data. + Default duration is `2592000` (30 days). + `0` represents infinite retention. + example: 86400 + format: int64 + minimum: 0 + type: integer + shardGroupDurationSeconds: + 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](/influxdb/cloud/reference/internals/shards/#shard-group-duration). + + #### Related guides + + - InfluxDB [shards and shard groups](/influxdb/cloud/reference/internals/shards/) + format: int64 + type: integer + type: + default: expire + enum: + - expire + type: string + required: + - everySeconds + type: object + PatchRetentionRules: + description: Updates to rules to expire or retain data. No rules means no updates. + items: + $ref: '#/components/schemas/PatchRetentionRule' + type: array + Permission: + properties: + action: + enum: + - read + - write + type: string + resource: + $ref: '#/components/schemas/Resource' + properties: + id: + description: | + A resource ID. + Identifies a specific resource. + type: string + name: + description: | + The name of the resource. + _Note: not all resource types have a `name` property_. + type: string + org: + description: | + An organization name. + The organization that owns the resource. + type: string + orgID: + description: | + An organization ID. + Identifies the organization that owns the resource. + type: string + type: + description: | + A resource type. + Identifies the API resource's type (or _kind_). + enum: + - authorizations + - buckets + - dashboards + - orgs + - tasks + - telegrafs + - users + - variables + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - annotations + - sources + - scrapers + - notebooks + - remotes + - replications + - instance + - flows + - functions + - subscriptions + type: string + required: + - type + type: object + required: + - action + - resource + PipeExpression: + description: Call expression with pipe argument + properties: + argument: + $ref: '#/components/schemas/Expression' + call: + $ref: '#/components/schemas/CallExpression' + type: + $ref: '#/components/schemas/NodeType' + type: object + PipeLiteral: + description: Represents a specialized literal value, indicating the left hand value of a pipe expression + properties: + type: + $ref: '#/components/schemas/NodeType' + type: object + PostBucketRequest: + properties: + description: + description: | + A description of the bucket. + type: string + name: + description: | + The bucket name. + type: string + orgID: + description: | + The organization ID. + Specifies the organization that owns the bucket. + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + rp: + default: '0' + description: | + The retention policy for the bucket. + For InfluxDB 1.x, specifies the duration of time that each data point + in the retention policy persists. + + If you need compatibility with InfluxDB 1.x, specify a value for the `rp` property; + otherwise, see the `retentionRules` property. + + [Retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) + is an InfluxDB 1.x concept. + The InfluxDB 2.x and Cloud equivalent is + [retention period](/influxdb/cloud/reference/glossary/#retention-period). + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. + type: string + schemaType: + $ref: '#/components/schemas/SchemaType' + default: implicit + description: | + The schema Type. Default is `implicit`. + + #### InfluxDB Cloud + + - Use `explicit` to enforce column names, tags, fields, and data types for + your data. + + #### InfluxDB OSS + + - Doesn't support `explicit` bucket schemas. + required: + - orgID + - name + PostCheck: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + PostNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + PostNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleDiscriminator' + PostOrganizationRequest: + properties: + description: + description: | + The description of the organization. + type: string + name: + description: | + The name of the organization. + type: string + required: + - name + type: object + Property: + description: The value associated with a key + properties: + key: + $ref: '#/components/schemas/PropertyKey' + type: + $ref: '#/components/schemas/NodeType' + value: + $ref: '#/components/schemas/Expression' + type: object + PropertyKey: + oneOf: + - $ref: '#/components/schemas/Identifier' + - $ref: '#/components/schemas/StringLiteral' + Query: + description: Query InfluxDB with the Flux language + properties: + dialect: + $ref: '#/components/schemas/Dialect' + extern: + $ref: '#/components/schemas/File' + now: + description: | + Specifies the time that should be reported as `now` in the query. + Default is the server `now` time. + format: date-time + type: string + params: + additionalProperties: true + description: | + Key-value pairs passed as parameters during query execution. + + To use parameters in your query, pass a _`query`_ with `params` references (in dot notation)--for example: + + ```json + query: "from(bucket: params.mybucket)\ + |> range(start: params.rangeStart) |> limit(n:1)" + ``` + + and pass _`params`_ with the key-value pairs--for example: + + ```json + params: { + "mybucket": "environment", + "rangeStart": "-30d" + } + ``` + + During query execution, InfluxDB passes _`params`_ to your script and substitutes the values. + + #### Limitations + + - If you use _`params`_, you can't use _`extern`_. + type: object + query: + description: The query script to execute. + type: string + type: + description: The type of query. Must be "flux". + enum: + - flux + type: string + required: + - query + type: object + QueryEditMode: + enum: + - builder + - advanced + type: string + QueryVariableProperties: + properties: + type: + enum: + - query + type: string + values: + properties: + language: + type: string + query: + type: string + type: object + RangeThreshold: + allOf: + - $ref: '#/components/schemas/ThresholdBase' + - properties: + max: + format: float + type: number + min: + format: float + type: number + type: + enum: + - range + type: string + within: + type: boolean + required: + - type + - min + - max + - within + type: object + Ready: + properties: + started: + example: '2019-03-13T10:09:33.891196-04:00' + format: date-time + type: string + status: + enum: + - ready + type: string + up: + example: 14m45.911966424s + type: string + type: object + RegexpLiteral: + description: Expressions begin and end with `/` and are regular expressions with syntax accepted by RE2 + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + RenamableField: + description: Describes a field that can be renamed and made visible or invisible. + properties: + displayName: + description: The name that a field is renamed to by the user. + type: string + internalName: + description: The calculated name of a field. + readOnly: true + type: string + visible: + description: Indicates whether this field should be visible on the table. + type: boolean + type: object + Resource: + properties: + id: + description: | + A resource ID. + Identifies a specific resource. + type: string + name: + description: | + The name of the resource. + _Note: not all resource types have a `name` property_. + type: string + org: + description: | + An organization name. + The organization that owns the resource. + type: string + orgID: + description: | + An organization ID. + Identifies the organization that owns the resource. + type: string + type: + description: | + A resource type. + Identifies the API resource's type (or _kind_). + enum: + - authorizations + - buckets + - dashboards + - orgs + - tasks + - telegrafs + - users + - variables + - secrets + - labels + - views + - documents + - notificationRules + - notificationEndpoints + - checks + - dbrp + - annotations + - sources + - scrapers + - notebooks + - remotes + - replications + - instance + - flows + - functions + - subscriptions + type: string + required: + - type + type: object + ResourceMember: + allOf: + - $ref: '#/components/schemas/UserResponse' + - properties: + role: + default: member + enum: + - member + type: string + type: object + ResourceMembers: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/ResourceMember' + type: array + type: object + ResourceOwner: + allOf: + - $ref: '#/components/schemas/UserResponse' + - properties: + role: + default: owner + enum: + - owner + type: string + type: object + ResourceOwners: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/ResourceOwner' + type: array + type: object + RetentionRule: + properties: + everySeconds: + default: 2592000 + 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: | + 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](/influxdb/cloud/reference/internals/shards/#shard-group-duration). + format: int64 + type: integer + type: + default: expire + enum: + - expire + type: string + required: + - everySeconds + type: object + RetentionRules: + description: | + Retention rules to expire or retain data. + The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](/influxdb/cloud/reference/glossary/#retention-period). + + #### InfluxDB Cloud + + - `retentionRules` is required. + + #### InfluxDB OSS + + - `retentionRules` isn't required. + items: + $ref: '#/components/schemas/RetentionRule' + type: array + ReturnStatement: + description: Defines an expression to return + properties: + argument: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + Routes: + properties: + authorizations: + format: uri + type: string + buckets: + format: uri + type: string + dashboards: + format: uri + type: string + external: + properties: + statusFeed: + format: uri + type: string + type: object + flags: + format: uri + type: string + me: + format: uri + type: string + orgs: + format: uri + type: string + query: + properties: + analyze: + format: uri + type: string + ast: + format: uri + type: string + self: + format: uri + type: string + suggestions: + format: uri + type: string + type: object + setup: + format: uri + type: string + signin: + format: uri + type: string + signout: + format: uri + type: string + sources: + format: uri + type: string + system: + properties: + debug: + format: uri + type: string + health: + format: uri + type: string + metrics: + format: uri + type: string + type: object + tasks: + format: uri + type: string + telegrafs: + format: uri + type: string + users: + format: uri + type: string + variables: + format: uri + type: string + write: + format: uri + type: string + RuleStatusLevel: + description: The state to record if check matches a criteria. + enum: + - UNKNOWN + - OK + - INFO + - CRIT + - WARN + - ANY + type: string + Run: + properties: + finishedAt: + 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 + type: string + flux: + description: Flux used for the task + readOnly: true + type: string + id: + readOnly: true + type: string + links: + example: + retry: /api/v2/tasks/1/runs/1/retry + self: /api/v2/tasks/1/runs/1 + task: /api/v2/tasks/1 + properties: + retry: + format: uri + type: string + self: + format: uri + type: string + task: + format: uri + type: string + readOnly: true + type: object + log: + description: An array of logs associated with the run. + items: + $ref: '#/components/schemas/LogEvent' + readOnly: true + type: array + requestedAt: + 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](/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. + example: 2006-01-02T15:04:05.999999999Z07:00 + format: date-time + readOnly: true + type: string + status: + enum: + - scheduled + - started + - failed + - success + - canceled + readOnly: true + type: string + taskID: + readOnly: true + type: string + RunManually: + properties: + scheduledFor: + 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 + type: string + Runs: + properties: + links: + $ref: '#/components/schemas/Links' + runs: + items: + $ref: '#/components/schemas/Run' + type: array + type: object + SMTPNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/SMTPNotificationRuleBase' + SMTPNotificationRuleBase: + properties: + bodyTemplate: + type: string + subjectTemplate: + type: string + to: + type: string + type: + enum: + - smtp + type: string + required: + - type + - subjectTemplate + - to + type: object + ScatterViewProperties: + properties: + adaptiveZoomHide: + type: boolean + colors: + description: Colors define color encoding of data into a visualization + items: + type: string + type: array + fillColumns: + items: + type: string + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + symbolColumns: + items: + type: string + type: array + timeFormat: + type: string + type: + enum: + - scatter + type: string + xAxisLabel: + type: string + xColumn: + type: string + xDomain: + items: + type: number + maxItems: 2 + type: array + xPrefix: + type: string + xSuffix: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yAxisLabel: + type: string + yColumn: + type: string + yDomain: + items: + type: number + maxItems: 2 + type: array + yPrefix: + type: string + ySuffix: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - xColumn + - yColumn + - fillColumns + - symbolColumns + - xDomain + - yDomain + - xAxisLabel + - yAxisLabel + - xPrefix + - yPrefix + - xSuffix + - ySuffix + type: object + SchemaType: + enum: + - implicit + - explicit + type: string + Script: + properties: + createdAt: + format: date-time + readOnly: true + type: string + description: + type: string + id: + readOnly: true + type: string + language: + $ref: '#/components/schemas/ScriptLanguage' + name: + type: string + orgID: + type: string + script: + description: The script to execute. + type: string + updatedAt: + format: date-time + readOnly: true + type: string + url: + description: The invocation endpoint address. + type: string + required: + - name + - orgID + - script + ScriptCreateRequest: + properties: + description: + description: Script description. A description of the script. + type: string + language: + $ref: '#/components/schemas/ScriptLanguage' + name: + description: Script name. The name must be unique within the organization. + type: string + script: + description: The script to execute. + type: string + required: + - name + - script + - language + - description + type: object + ScriptHTTPResponseData: + description: | + The response body contains the results of the executed script. + The response is user-defined and dynamic. + format: binary + type: string + ScriptInvocationParams: + properties: + params: + additionalProperties: true + description: | + The script parameters. + `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 + invocation parameters to the script. + type: object + type: object + ScriptLanguage: + enum: + - flux + - sql + type: string + ScriptUpdateRequest: + properties: + description: + description: A description of the script. + type: string + script: + description: The script to execute. + type: string + type: object + Scripts: + properties: + scripts: + items: + $ref: '#/components/schemas/Script' + type: array + type: object + SecretKeys: + properties: + secrets: + items: + type: string + type: array + type: object + SecretKeysResponse: + allOf: + - $ref: '#/components/schemas/SecretKeys' + - properties: + links: + properties: + org: + type: string + self: + type: string + readOnly: true + type: object + type: object + Secrets: + additionalProperties: + type: string + example: + apikey: abc123xyz + SimpleTableViewProperties: + properties: + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showAll: + type: boolean + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + type: + enum: + - simple-table + type: string + required: + - type + - showAll + - queries + - shape + - note + - showNoteWhenEmpty + type: object + SingleStatViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + note: + type: string + prefix: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + suffix: + type: string + tickPrefix: + type: string + tickSuffix: + type: string + type: + enum: + - single-stat + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - prefix + - tickPrefix + - suffix + - tickSuffix + - decimalPlaces + type: object + SlackNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + token: + 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`. + type: string + type: object + type: object + SlackNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/SlackNotificationRuleBase' + SlackNotificationRuleBase: + properties: + channel: + type: string + messageTemplate: + type: string + type: + enum: + - slack + type: string + required: + - type + - messageTemplate + type: object + Stack: + properties: + createdAt: + format: date-time + readOnly: true + type: string + events: + items: + properties: + description: + type: string + eventType: + type: string + name: + type: string + resources: + items: + properties: + apiVersion: + type: string + associations: + items: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + metaName: + type: string + type: object + type: array + kind: + $ref: '#/components/schemas/TemplateKind' + links: + properties: + self: + type: string + type: object + resourceID: + type: string + templateMetaName: + type: string + type: object + type: array + sources: + items: + type: string + type: array + updatedAt: + format: date-time + readOnly: true + type: string + urls: + items: + type: string + type: array + type: object + type: array + id: + type: string + orgID: + type: string + type: object + Statement: + oneOf: + - $ref: '#/components/schemas/BadStatement' + - $ref: '#/components/schemas/VariableAssignment' + - $ref: '#/components/schemas/MemberAssignment' + - $ref: '#/components/schemas/ExpressionStatement' + - $ref: '#/components/schemas/ReturnStatement' + - $ref: '#/components/schemas/OptionStatement' + - $ref: '#/components/schemas/BuiltinStatement' + - $ref: '#/components/schemas/TestStatement' + StaticLegend: + description: StaticLegend represents the options specific to the static legend + properties: + colorizeRows: + type: boolean + heightRatio: + format: float + type: number + opacity: + format: float + type: number + orientationThreshold: + type: integer + show: + type: boolean + valueAxis: + type: string + widthRatio: + format: float + type: number + type: object + StatusRule: + properties: + count: + type: integer + currentLevel: + $ref: '#/components/schemas/RuleStatusLevel' + period: + type: string + previousLevel: + $ref: '#/components/schemas/RuleStatusLevel' + type: object + StringLiteral: + description: Expressions begin and end with double quote marks + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + TableViewProperties: + properties: + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + decimalPlaces: + $ref: '#/components/schemas/DecimalPlaces' + fieldOptions: + description: fieldOptions represent the fields retrieved by the query with customization options + items: + $ref: '#/components/schemas/RenamableField' + type: array + note: + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + tableOptions: + properties: + fixFirstColumn: + 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 + type: boolean + wrapping: + description: Wrapping describes the text wrapping style to be used in table views + enum: + - truncate + - wrap + - single-line + type: string + type: object + timeFormat: + description: timeFormat describes the display format for time values according to moment.js date formatting + type: string + type: + enum: + - table + type: string + required: + - type + - queries + - colors + - shape + - note + - showNoteWhenEmpty + - tableOptions + - fieldOptions + - timeFormat + - decimalPlaces + type: object + TagRule: + properties: + key: + type: string + operator: + enum: + - equal + - notequal + - equalregex + - notequalregex + type: string + value: + type: string + type: object + Task: + properties: + authorizationID: + description: | + An authorization ID. + Specifies the authorization used when the task communicates with the query engine. + + To find an authorization ID, use the + [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to + list authorizations. + type: string + 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. + type: string + description: + description: A description of the task. + type: string + every: + 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 executes. + + #### Limitations + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + format: flux + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + lastRunError: + readOnly: true + type: string + lastRunStatus: + enum: + - failed + - success + - canceled + readOnly: true + type: string + latestCompleted: + 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 + links: + example: + labels: /api/v2/tasks/1/labels + logs: /api/v2/tasks/1/logs + members: /api/v2/tasks/1/members + owners: /api/v2/tasks/1/owners + runs: /api/v2/tasks/1/runs + self: /api/v2/tasks/1 + properties: + labels: + $ref: '#/components/schemas/Link' + logs: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + runs: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + name: + description: The name of the task. + type: string + offset: + description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. + format: duration + type: string + org: + description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string + orgID: + description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string + ownerID: + 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: | + A script ID. + Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. + + #### Limitations + + - If you use the `scriptID` property, you can't use the `flux` property. + + #### Related guides + + - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) + type: string + scriptParameters: + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the script specified by `scriptID`. + When running the task, InfluxDB executes the script with the parameters + you provide. + + #### Limitations + + - To use `scriptParameters`, you must provide a `scriptID`. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. + type: object + status: + $ref: '#/components/schemas/TaskStatusType' + updatedAt: + format: date-time + readOnly: true + type: string + required: + - id + - name + - orgID + type: object + TaskCreateRequest: + properties: + cron: + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time. + type: string + description: + description: The description of the task. + type: string + every: + description: | + The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. + `every` also determines when the task first runs, depending on the specified time. + type: string + flux: + description: | + The Flux script that the task runs. + + #### Limitations + + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + type: string + name: + description: The name of the task + type: string + offset: + description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. + format: duration + type: string + org: + description: The name of the organization that owns the task. + type: string + orgID: + description: The ID of the organization that owns the task. + type: string + scriptID: + description: | + The ID of the script that the task runs. + + #### Limitations + + - If you use the `scriptID` property, you can't use the `flux` property. + type: string + scriptParameters: + description: | + The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. + + #### Limitations + + - `scriptParameters` requires `scriptID`. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. + type: object + status: + $ref: '#/components/schemas/TaskStatusType' + type: object + TaskStatusType: + description: | + `inactive` cancels scheduled runs and prevents manual runs of the task. + enum: + - active + - inactive + type: string + TaskUpdateRequest: + properties: + cron: + description: Update the 'cron' option in the flux script. + type: string + description: + description: Update the description of the task. + type: string + every: + description: Update the 'every' option in the flux script. + type: string + flux: + description: Update the Flux script that the task runs. + type: string + name: + description: Update the 'name' option in the flux script. + type: string + offset: + description: Update the 'offset' option in the flux script. + type: string + scriptID: + description: Update the 'scriptID' of the task. + type: string + scriptParameters: + description: Update the 'scriptParameters' of the task. + type: object + status: + $ref: '#/components/schemas/TaskStatusType' + type: object + Tasks: + properties: + links: + $ref: '#/components/schemas/Links' + readOnly: true + tasks: + items: + $ref: '#/components/schemas/Task' + type: array + type: object + Telegraf: + allOf: + - $ref: '#/components/schemas/TelegrafRequest' + - properties: + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + readOnly: true + links: + example: + lables: /api/v2/telegrafs/1/labels + members: /api/v2/telegrafs/1/members + owners: /api/v2/telegrafs/1/owners + self: /api/v2/telegrafs/1 + properties: + labels: + $ref: '#/components/schemas/Link' + members: + $ref: '#/components/schemas/Link' + owners: + $ref: '#/components/schemas/Link' + self: + $ref: '#/components/schemas/Link' + readOnly: true + type: object + type: object + type: object + TelegrafPlugin: + properties: + config: + type: string + description: + type: string + name: + type: string + type: + type: string + type: object + TelegrafPluginRequest: + properties: + config: + type: string + description: + type: string + metadata: + properties: + buckets: + items: + type: string + type: array + type: object + name: + type: string + orgID: + type: string + plugins: + items: + properties: + alias: + type: string + config: + type: string + description: + type: string + name: + type: string + type: + type: string + type: object + type: array + type: object + TelegrafPlugins: + properties: + os: + type: string + plugins: + items: + $ref: '#/components/schemas/TelegrafPlugin' + type: array + version: + type: string + type: object + TelegrafRequest: + properties: + config: + type: string + description: + type: string + metadata: + properties: + buckets: + items: + type: string + type: array + type: object + name: + type: string + orgID: + type: string + type: object + Telegrafs: + properties: + configurations: + items: + $ref: '#/components/schemas/Telegraf' + type: array + type: object + TelegramNotificationEndpoint: + allOf: + - $ref: '#/components/schemas/NotificationEndpointBase' + - properties: + channel: + 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 . + type: string + required: + - token + - channel + type: object + type: object + TelegramNotificationRule: + allOf: + - $ref: '#/components/schemas/NotificationRuleBase' + - $ref: '#/components/schemas/TelegramNotificationRuleBase' + TelegramNotificationRuleBase: + properties: + disableWebPagePreview: + 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". + enum: + - MarkdownV2 + - HTML + - Markdown + type: string + type: + description: The discriminator between other types of notification rules is "telegram". + enum: + - telegram + type: string + required: + - type + - messageTemplate + - channel + type: object + Template: + items: + description: | + A template entry. + Defines an InfluxDB resource in a template. + properties: + apiVersion: + example: influxdata.com/v2alpha1 + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + metadata: + 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. + Key-value pairs map to the specification for the resource. + + The following code samples show `spec` configurations for template resources: + + - A bucket: + + ```json + { "spec": { + "name": "iot_center", + "retentionRules": [{ + "everySeconds": 2.592e+06, + "type": "expire" + }] + } + } + ``` + + - A variable: + + ```json + { "spec": { + "language": "flux", + "name": "Node_Service", + "query": "import \"influxdata/influxdb/v1\"\r\nv1.tagValues(bucket: \"iot_center\", + tag: \"service\")", + "type": "query" + } + } + ``` + type: object + type: object + type: array + TemplateApply: + properties: + actions: + description: | + A list of `action` objects. + Actions let you customize how InfluxDB applies templates in the request. + + You can use the following actions to prevent creating or updating resources: + + - A `skipKind` action skips template resources of a specified `kind`. + - A `skipResource` action skips template resources with a specified `metadata.name` + and `kind`. + items: + oneOf: + - properties: + action: + enum: + - skipKind + type: string + properties: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + required: + - kind + type: object + type: object + - properties: + action: + enum: + - skipResource + type: string + properties: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + resourceTemplateName: + type: string + required: + - kind + - resourceTemplateName + type: object + type: object + type: array + dryRun: + 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. + type: boolean + envRefs: + additionalProperties: + oneOf: + - type: string + - 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` + property. + To substitute a custom environment reference value when applying templates, + pass `envRefs` with the `envRef.key` and the value. + + When you apply a template, InfluxDB replaces `envRef` objects in the template + with the values that you provide in the `envRefs` parameter. + For more examples, see how to [define environment references](/influxdb/cloud/influxdb-templates/use/#define-environment-references). + + The following template fields may use environment references: + + - `metadata.name` + - `spec.endpointName` + - `spec.associations.name` + + For more information about including environment references in template fields, see how to + [include user-definable resource names](/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names). + type: object + orgID: + 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](/influxdb/cloud/organizations/view-orgs/). + type: string + remotes: + description: | + A list of URLs for template files. + + To apply a template manifest file located at a URL, pass `remotes` + with an array that contains the URL. + items: + properties: + contentType: + type: string + url: + type: string + required: + - url + type: object + type: array + secrets: + additionalProperties: + type: string + description: | + An object with key-value pairs that map to **secrets** in queries. + + Queries may reference secrets stored in InfluxDB--for example, + the following Flux script retrieves `POSTGRES_USERNAME` and `POSTGRES_PASSWORD` + secrets and then uses them to connect to a PostgreSQL database: + + ```js + import "sql" + import "influxdata/influxdb/secrets" + + username = secrets.get(key: "POSTGRES_USERNAME") + password = secrets.get(key: "POSTGRES_PASSWORD") + + sql.from( + driverName: "postgres", + dataSourceName: "postgresql://${username}:${password}@localhost:5432", + query: "SELECT * FROM example_table", + ) + ``` + + To define secret values in your `/api/v2/templates/apply` request, + pass the `secrets` parameter with key-value pairs--for example: + + ```json + { + ... + "secrets": { + "POSTGRES_USERNAME": "pguser", + "POSTGRES_PASSWORD": "foo" + } + ... + } + ``` + + InfluxDB stores the key-value pairs as secrets that you can access with `secrets.get()`. + Once stored, you can't view secret values in InfluxDB. + + #### Related guides + + - [How to pass secrets when installing a template](/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template) + type: object + stackID: + description: | + ID of the stack to update. + + To apply templates to an existing stack in the organization, use the `stackID` parameter. + If you apply templates without providing a stack ID, + InfluxDB initializes a new stack with all new resources. + + To find a stack ID, use the InfluxDB [`/api/v2/stacks` API endpoint](#operation/ListStacks) to list stacks. + + #### Related guides + + - [Stacks](/influxdb/cloud/influxdb-templates/stacks/) + - [View stacks](/influxdb/cloud/influxdb-templates/stacks/view/) + type: string + template: + description: | + A template object to apply. + A template object has a `contents` property + with an array of InfluxDB resource configurations. + + Pass `template` to apply only one template object. + If you use `template`, you can't use the `templates` parameter. + If you want to apply multiple template objects, use `templates` instead. + properties: + contentType: + type: string + contents: + $ref: '#/components/schemas/Template' + sources: + items: + type: string + type: array + type: object + templates: + description: | + A list of template objects to apply. + A template object has a `contents` property + with an array of InfluxDB resource configurations. + + Use the `templates` parameter to apply multiple template objects. + If you use `templates`, you can't use the `template` parameter. + items: + properties: + contentType: + type: string + contents: + $ref: '#/components/schemas/Template' + sources: + items: + type: string + type: array + type: object + type: array + type: object + TemplateChart: + properties: + height: + type: integer + properties: + $ref: '#/components/schemas/ViewProperties' + width: + type: integer + xPos: + type: integer + yPos: + type: integer + type: object + TemplateEnvReferences: + items: + properties: + defaultValue: + description: Default value that will be provided for the reference when no value is provided + nullable: true + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + envRefKey: + description: Key identified as environment reference and is the key identified in the template + type: string + resourceField: + description: Field the environment reference corresponds too + type: string + value: + description: Value provided to fulfill reference + nullable: true + oneOf: + - type: string + - type: integer + - type: number + - type: boolean + required: + - resourceField + - envRefKey + type: object + type: array + TemplateExportByID: + properties: + orgIDs: + items: + properties: + orgID: + type: string + resourceFilters: + properties: + byLabel: + items: + type: string + type: array + byResourceKind: + items: + $ref: '#/components/schemas/TemplateKind' + type: array + type: object + type: object + type: array + resources: + items: + properties: + id: + type: string + 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 + type: string + required: + - id + - kind + type: object + type: array + stackID: + type: string + type: object + TemplateExportByName: + properties: + orgIDs: + items: + properties: + orgID: + type: string + resourceFilters: + properties: + byLabel: + items: + type: string + type: array + byResourceKind: + items: + $ref: '#/components/schemas/TemplateKind' + type: array + type: object + type: object + type: array + resources: + items: + properties: + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + required: + - name + - kind + type: object + type: array + stackID: + type: string + type: object + TemplateKind: + enum: + - Bucket + - Check + - CheckDeadman + - CheckThreshold + - Dashboard + - Label + - NotificationEndpoint + - NotificationEndpointHTTP + - NotificationEndpointPagerDuty + - NotificationEndpointSlack + - NotificationRule + - Task + - Telegraf + - Variable + type: string + TemplateSummary: + properties: + diff: + properties: + buckets: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + description: + type: string + name: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + type: object + old: + properties: + description: + type: string + name: + type: string + retentionRules: + $ref: '#/components/schemas/RetentionRules' + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + checks: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/CheckDiscriminator' + old: + $ref: '#/components/schemas/CheckDiscriminator' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + dashboards: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + name: + type: string + type: object + old: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + labelMappings: + items: + properties: + labelID: + type: string + labelName: + type: string + labelTemplateMetaName: + type: string + resourceID: + type: string + resourceName: + type: string + resourceTemplateMetaName: + type: string + resourceType: + type: string + status: + type: string + type: object + type: array + labels: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + color: + type: string + description: + type: string + name: + type: string + type: object + old: + properties: + color: + type: string + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + notificationEndpoints: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/NotificationEndpointDiscriminator' + old: + $ref: '#/components/schemas/NotificationEndpointDiscriminator' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + notificationRules: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + description: + type: string + endpointID: + type: string + endpointName: + type: string + endpointType: + type: string + every: + type: string + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array + type: object + old: + properties: + description: + type: string + endpointID: + type: string + endpointName: + type: string + endpointType: + type: string + every: + type: string + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + tasks: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + cron: + type: string + description: + type: string + every: + type: string + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + type: object + old: + properties: + cron: + type: string + description: + type: string + every: + type: string + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + telegrafConfigs: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + $ref: '#/components/schemas/TelegrafRequest' + old: + $ref: '#/components/schemas/TelegrafRequest' + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + variables: + items: + properties: + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + new: + properties: + args: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + name: + type: string + type: object + old: + properties: + args: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + name: + type: string + type: object + stateStatus: + type: string + templateMetaName: + type: string + type: object + type: array + type: object + errors: + items: + properties: + fields: + items: + type: string + type: array + indexes: + items: + type: integer + type: array + kind: + $ref: '#/components/schemas/TemplateKind' + reason: + type: string + type: object + type: array + sources: + items: + type: string + type: array + stackID: + type: string + summary: + properties: + buckets: + items: + properties: + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + retentionPeriod: + type: integer + templateMetaName: + type: string + type: object + type: array + checks: + items: + allOf: + - $ref: '#/components/schemas/CheckDiscriminator' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + dashboards: + items: + properties: + charts: + items: + $ref: '#/components/schemas/TemplateChart' + type: array + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + templateMetaName: + type: string + type: object + type: array + labelMappings: + items: + properties: + labelID: + type: string + labelName: + type: string + labelTemplateMetaName: + type: string + resourceID: + type: string + resourceName: + type: string + resourceTemplateMetaName: + type: string + resourceType: + type: string + status: + type: string + type: object + type: array + labels: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + missingEnvRefs: + items: + type: string + type: array + missingSecrets: + items: + type: string + type: array + notificationEndpoints: + items: + allOf: + - $ref: '#/components/schemas/NotificationEndpointDiscriminator' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + notificationRules: + items: + properties: + description: + type: string + endpointID: + type: string + endpointTemplateMetaName: + type: string + endpointType: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + every: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + messageTemplate: + type: string + name: + type: string + offset: + type: string + status: + type: string + statusRules: + items: + properties: + currentLevel: + type: string + previousLevel: + type: string + type: object + type: array + tagRules: + items: + properties: + key: + type: string + operator: + type: string + value: + type: string + type: object + type: array + templateMetaName: + type: string + type: object + type: array + tasks: + items: + properties: + cron: + type: string + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + every: + type: string + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + offset: + type: string + query: + type: string + status: + type: string + templateMetaName: + type: string + type: object + type: array + telegrafConfigs: + items: + allOf: + - $ref: '#/components/schemas/TelegrafRequest' + - properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + templateMetaName: + type: string + type: object + type: array + variables: + items: + properties: + arguments: + $ref: '#/components/schemas/VariableProperties' + description: + type: string + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + labelAssociations: + items: + $ref: '#/components/schemas/TemplateSummaryLabel' + type: array + name: + type: string + orgID: + type: string + templateMetaName: + type: string + type: object + type: array + type: object + type: object + TemplateSummaryLabel: + properties: + envReferences: + $ref: '#/components/schemas/TemplateEnvReferences' + id: + type: string + kind: + $ref: '#/components/schemas/TemplateKind' + name: + type: string + orgID: + type: string + properties: + properties: + color: + type: string + description: + type: string + type: object + templateMetaName: + type: string + type: object + TestStatement: + description: Declares a Flux test case + properties: + assignment: + $ref: '#/components/schemas/VariableAssignment' + type: + $ref: '#/components/schemas/NodeType' + type: object + Threshold: + discriminator: + mapping: + greater: '#/components/schemas/GreaterThreshold' + lesser: '#/components/schemas/LesserThreshold' + range: '#/components/schemas/RangeThreshold' + propertyName: type + oneOf: + - $ref: '#/components/schemas/GreaterThreshold' + - $ref: '#/components/schemas/LesserThreshold' + - $ref: '#/components/schemas/RangeThreshold' + ThresholdBase: + properties: + allValues: + description: If true, only alert if all values meet threshold. + type: boolean + level: + $ref: '#/components/schemas/CheckStatusLevel' + ThresholdCheck: + allOf: + - $ref: '#/components/schemas/CheckBase' + - properties: + every: + description: Check repetition interval. + type: string + offset: + description: Duration to delay after the schedule, before executing check. + type: string + statusMessageTemplate: + description: The template used to generate and write a status message. + type: string + tags: + description: List of tags to write to each status. + items: + properties: + key: + type: string + value: + type: string + type: object + type: array + thresholds: + items: + $ref: '#/components/schemas/Threshold' + type: array + type: + enum: + - threshold + type: string + required: + - type + type: object + Token: + properties: + token: + type: string + type: object + UnaryExpression: + description: Uses operators to act on a single operand in an expression + properties: + argument: + $ref: '#/components/schemas/Expression' + operator: + type: string + type: + $ref: '#/components/schemas/NodeType' + type: object + UnsignedIntegerLiteral: + description: Represents integer numbers + properties: + type: + $ref: '#/components/schemas/NodeType' + value: + type: string + type: object + User: + properties: + id: + readOnly: true + type: string + name: + type: string + org_id: + type: string + role: + enum: + - owner + - member + type: string + status: + default: active + description: If inactive the user is inactive. + enum: + - active + - inactive + type: string + required: + - name + UserResponse: + properties: + id: + description: | + The user ID. + readOnly: true + type: string + links: + example: + self: /api/v2/users/1 + properties: + self: + format: uri + type: string + readOnly: true + type: object + name: + description: | + The user name. + type: string + status: + default: active + description: | + The status of a user. + An inactive user can't read or write resources. + enum: + - active + - inactive + type: string + required: + - name + Users: + properties: + links: + properties: + self: + format: uri + type: string + type: object + users: + items: + $ref: '#/components/schemas/UserResponse' + type: array + type: object + Variable: + properties: + arguments: + $ref: '#/components/schemas/VariableProperties' + createdAt: + format: date-time + type: string + description: + type: string + id: + readOnly: true + type: string + labels: + $ref: '#/components/schemas/Labels' + links: + properties: + labels: + format: uri + type: string + org: + format: uri + type: string + self: + format: uri + type: string + readOnly: true + type: object + name: + type: string + orgID: + type: string + selected: + items: + type: string + type: array + sort_order: + type: integer + updatedAt: + format: date-time + type: string + required: + - name + - orgID + - arguments + type: object + VariableAssignment: + description: Represents the declaration of a variable + properties: + id: + $ref: '#/components/schemas/Identifier' + init: + $ref: '#/components/schemas/Expression' + type: + $ref: '#/components/schemas/NodeType' + type: object + VariableProperties: + oneOf: + - $ref: '#/components/schemas/QueryVariableProperties' + - $ref: '#/components/schemas/ConstantVariableProperties' + - $ref: '#/components/schemas/MapVariableProperties' + type: object + Variables: + example: + variables: + - arguments: + type: constant + values: + - howdy + - hello + - hi + - yo + - oy + id: '1221432' + name: ':ok:' + selected: + - hello + - arguments: + type: map + values: + a: fdjaklfdjkldsfjlkjdsa + b: dfaksjfkljekfajekdljfas + c: fdjksajfdkfeawfeea + id: '1221432' + name: ':ok:' + selected: + - c + - arguments: + language: flux + query: 'from(bucket: "foo") |> showMeasurements()' + type: query + id: '1221432' + name: ':ok:' + selected: + - host + properties: + variables: + items: + $ref: '#/components/schemas/Variable' + type: array + type: object + View: + properties: + id: + readOnly: true + type: string + links: + properties: + self: + type: string + readOnly: true + type: object + name: + type: string + properties: + $ref: '#/components/schemas/ViewProperties' + required: + - name + - properties + ViewProperties: + oneOf: + - $ref: '#/components/schemas/LinePlusSingleStatProperties' + - $ref: '#/components/schemas/XYViewProperties' + - $ref: '#/components/schemas/SingleStatViewProperties' + - $ref: '#/components/schemas/HistogramViewProperties' + - $ref: '#/components/schemas/GaugeViewProperties' + - $ref: '#/components/schemas/TableViewProperties' + - $ref: '#/components/schemas/SimpleTableViewProperties' + - $ref: '#/components/schemas/MarkdownViewProperties' + - $ref: '#/components/schemas/CheckViewProperties' + - $ref: '#/components/schemas/ScatterViewProperties' + - $ref: '#/components/schemas/HeatmapViewProperties' + - $ref: '#/components/schemas/MosaicViewProperties' + - $ref: '#/components/schemas/BandViewProperties' + - $ref: '#/components/schemas/GeoViewProperties' + Views: + properties: + links: + properties: + self: + type: string + type: object + views: + items: + $ref: '#/components/schemas/View' + type: array + type: object + WritePrecision: + enum: + - ms + - s + - us + - ns + type: string + XYGeom: + enum: + - line + - step + - stacked + - bar + - monotoneX + - stepBefore + - stepAfter + type: string + XYViewProperties: + properties: + adaptiveZoomHide: + type: boolean + axes: + $ref: '#/components/schemas/Axes' + colorMapping: + $ref: '#/components/schemas/ColorMapping' + description: An object that contains information about the color mapping + colors: + description: Colors define color encoding of data into a visualization + items: + $ref: '#/components/schemas/DashboardColor' + type: array + generateXAxisTicks: + items: + type: string + type: array + generateYAxisTicks: + items: + type: string + type: array + geom: + $ref: '#/components/schemas/XYGeom' + hoverDimension: + enum: + - auto + - x + - 'y' + - xy + type: string + legendColorizeRows: + type: boolean + legendHide: + type: boolean + legendOpacity: + format: float + type: number + legendOrientationThreshold: + type: integer + note: + type: string + position: + enum: + - overlaid + - stacked + type: string + queries: + items: + $ref: '#/components/schemas/DashboardQuery' + type: array + shadeBelow: + type: boolean + shape: + enum: + - chronograf-v2 + type: string + showNoteWhenEmpty: + description: If true, will display note when empty + type: boolean + staticLegend: + $ref: '#/components/schemas/StaticLegend' + timeFormat: + type: string + type: + enum: + - xy + type: string + xColumn: + type: string + xTickStart: + format: float + type: number + xTickStep: + format: float + type: number + xTotalTicks: + type: integer + yColumn: + type: string + yTickStart: + format: float + type: number + yTickStep: + format: float + type: number + yTotalTicks: + type: integer + required: + - type + - geom + - queries + - shape + - axes + - colors + - note + - showNoteWhenEmpty + - position + type: object + securitySchemes: + BasicAuthentication: + description: | + ### Basic authentication scheme + + Use the HTTP Basic authentication scheme for InfluxDB `/api/v2` API operations that support it: + + ### Syntax + + `Authorization: Basic BASE64_ENCODED_CREDENTIALS` + + To construct the `BASE64_ENCODED_CREDENTIALS`, combine the username and + the password with a colon (`USERNAME:PASSWORD`), and then encode the + resulting string in [base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64). + Many HTTP clients encode the credentials for you before sending the + request. + + _**Warning**: Base64-encoding can easily be reversed to obtain the original + username and password. It is used to keep the data intact and does not provide + security. You should always use HTTPS when authenticating or sending a request with + sensitive information._ + + ### Examples + + In the examples, replace the following: + + - **`EMAIL_ADDRESS`**: InfluxDB Cloud username (the email address the user signed up with) + - **`PASSWORD`**: InfluxDB Cloud [API token](/influxdb/cloud/reference/glossary/#token) + - **`INFLUX_URL`**: your InfluxDB Cloud URL + + #### Encode credentials with cURL + + The following example shows how to use cURL to send an API request that uses Basic authentication. + With the `--user` option, cURL encodes the credentials and passes them + in the `Authorization: Basic` header. + + ```sh + curl --get "INFLUX_URL/api/v2/signin" + --user "EMAIL_ADDRESS":"PASSWORD" + ``` + + #### Encode credentials with Flux + + The Flux [`http.basicAuth()` function](https://docs.influxdata.com/flux/v0.x/stdlib/http/basicauth/) returns a Base64-encoded + basic authentication header using a specified username and password combination. + + #### Encode credentials with JavaScript + + The following example shows how to use the JavaScript `btoa()` function + to create a Base64-encoded string: + + ```js + btoa('EMAIL_ADDRESS:PASSWORD') + ``` + + The output is the following: + + ```js + 'VVNFUk5BTUU6UEFTU1dPUkQ=' + ``` + + Once you have the Base64-encoded credentials, you can pass them in the + `Authorization` header--for example: + + ```sh + curl --get "INFLUX_URL/api/v2/signin" + --header "Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ=" + ``` + + To learn more about HTTP authentication, see + [Mozilla Developer Network (MDN) Web Docs, HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication)._ + scheme: basic + type: http + 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. + The word `Token` is case-sensitive. + + ### Syntax + + `Authorization: Token INFLUX_API_TOKEN` + + ### Example + + #### Use Token authentication with cURL + + The following example shows how to use cURL to send an API request that uses Token authentication: + + ```sh + curl --request GET "INFLUX_URL/api/v2/buckets" \ + --header "Authorization: Token INFLUX_API_TOKEN" + ``` + + Replace the following: + + - *`INFLUX_URL`*: your InfluxDB Cloud URL + - *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/cloud/reference/glossary/#token) + + ### Related endpoints + + - [`/authorizations` endpoints](#tag/Authorizations-(API-tokens)) + + ### Related guides + + - [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 IOx API Service + version: Cloud 2.x + description: | + The InfluxDB HTTP 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). + license: + name: MIT + url: https://opensource.org/licenses/MIT +openapi: 3.0.0 +paths: + /api/v2: + get: + description: | + Retrieves all the top level routes for the InfluxDB API. + + #### Limitations + + - Only returns top level routes--for example, the response contains + `"tasks":"/api/v2/tasks"`, and doesn't contain resource-specific routes + for tasks (`/api/v2/tasks/TASK_ID/...`). + operationId: GetRoutes + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Routes' + description: | + Success. + The response body contains key-value pairs with the resource name and + top-level route. + summary: List all top level routes + tags: + - Routes + - System information endpoints + /api/v2/authorizations: + get: + description: | + Lists authorizations. + + To limit which authorizations are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all authorizations. + + #### InfluxDB Cloud + + - InfluxDB Cloud doesn't expose [API token](/influxdb/cloud/reference/glossary/#token) + values in `GET /api/v2/authorizations` responses; + returns `token: redacted` for all authorizations. + + #### Required permissions + + To retrieve an authorization, the request must use an API token that has the + following permissions: + + - `read-authorizations` + - `read-user` for the user that the authorization is scoped to + + #### Related guides + + - [View tokens](/influxdb/cloud/security/tokens/view-tokens/) + operationId: GetAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + A user ID. + 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 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 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 the specified [organization](/influxdb/cloud/reference/glossary/#organization). + in: query + name: org + schema: + type: string + - description: | + An API [token](/influxdb/cloud/reference/glossary/#token) value. + Specifies an authorization by its `token` property value + and returns the authorization. + + #### InfluxDB OSS + + - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, + applies other parameters, and then returns the result. + + #### Limitations + + - The parameter is non-repeatable. If you specify more than one, + only the first one is used. If a resource with the specified + property value doesn't exist, then the response body contains an empty list. + in: query + name: token + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorizations' + description: | + Success. The response body contains a list of authorizations. + + If the response body is missing authorizations that you expect, check that the API + token used in the request has `read-user` permission for the users (`userID` property value) + in those authorizations. + + #### InfluxDB OSS + + - **Warning**: The response body contains authorizations with their + [API token](/influxdb/cloud/reference/glossary/#token) values in clear text. + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + '400': + $ref: '#/components/responses/GeneralServerError' + description: Invalid request + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error + summary: List authorizations + tags: + - Authorizations (API tokens) + - Security and access endpoints + post: + 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. + The API token is the authorization's `token` property value. + + To follow best practices for secure API token generation and retrieval, + InfluxDB enforces access restrictions on API tokens. + + - InfluxDB allows access to the API token value immediately after the authorization is created. + - You canโ€™t change access (read/write) permissions for an API token after itโ€™s created. + - Tokens stop working when the user who created the token is deleted. + + We recommend the following for managing your tokens: + + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. + + #### Required permissions + + - `write-authorizations` + - `write-user` for the user that the authorization is scoped to + + #### Related guides + + - [Create a token](/influxdb/cloud/security/tokens/create-token/) + operationId: PostAuthorizations + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + examples: + AuthorizationPostRequest: + $ref: '#/components/examples/AuthorizationPostRequest' + AuthorizationWithResourcePostRequest: + $ref: '#/components/examples/AuthorizationWithResourcePostRequest' + AuthorizationWithUserPostRequest: + $ref: '#/components/examples/AuthorizationWithUserPostRequest' + schema: + $ref: '#/components/schemas/AuthorizationPostRequest' + description: The authorization to create. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: | + Success. The authorization is created. The response body contains the + authorization. + '400': + $ref: '#/components/responses/GeneralServerError' + description: Invalid request + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error + summary: Create an authorization + tags: + - Authorizations (API tokens) + - Security and access endpoints + /api/v2/authorizations/{authID}: + delete: + description: | + Deletes an authorization. + + Use the endpoint to delete an API token. + + If you want to disable an API token instead of delete it, + [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). + operationId: DeleteAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: An authorization ID. Specifies the authorization to delete. + in: path + name: authID + required: true + schema: + type: string + responses: + '204': + description: Success. The authorization is deleted. + '400': + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error + summary: Delete an authorization + tags: + - Authorizations (API tokens) + - Security and access endpoints + get: + description: | + Retrieves an authorization. + + Use this endpoint to retrieve information about an API token, including + the token's permissions and the user that the token is scoped to. + + #### InfluxDB OSS + + - InfluxDB OSS returns + [API token](/influxdb/cloud/reference/glossary/#token) values in authorizations. + - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, + InfluxDB OSS returns authorizations for all organizations in the instance. + + #### Related guides + + - [View tokens](/influxdb/cloud/security/tokens/view-tokens/) + externalDocs: + description: View tokens + url: https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/ + operationId: GetAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: An authorization ID. Specifies the authorization to retrieve. + in: path + name: authID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Success. The response body contains the authorization. + '400': + content: + application/json: + examples: + notFound: + summary: | + The specified resource ID is invalid. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested authorization doesn't exist. + value: + code: not found + message: authorization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error + summary: Retrieve an authorization + tags: + - Authorizations (API tokens) + - Security and access endpoints + patch: + description: | + Updates an authorization. + + Use this endpoint to set an API token's status to be _active_ or _inactive_. + InfluxDB rejects requests that use inactive API tokens. + operationId: PatchAuthorizationsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: An authorization ID. Specifies the authorization to update. + in: path + name: authID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationUpdateRequest' + description: In the request body, provide the authorization properties to update. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Authorization' + description: Success. The response body contains the updated authorization. + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error + summary: Update an API token to be active or inactive + tags: + - Authorizations (API tokens) + - Security and access endpoints + /api/v2/buckets: + get: + description: | + Lists [buckets](/influxdb/cloud/reference/glossary/#bucket). + + InfluxDB retrieves buckets owned by the + [organization](/influxdb/cloud/reference/glossary/#organization) + associated with the authorization + ([API token](/influxdb/cloud/reference/glossary/#token)). + To limit which buckets are returned, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all buckets up to the + default `limit`. + + #### InfluxDB OSS + + - If you use an _[operator token](/influxdb/cloud/security/tokens/#operator-token)_ + to authenticate your request, InfluxDB retrieves resources for _all + organizations_ in the instance. + To retrieve resources for only a specific organization, use the + `org` parameter or the `orgID` parameter to specify the organization. + + #### Required permissions + + | Action | Permission required | + |:--------------------------|:--------------------| + | Retrieve _user buckets_ | `read-buckets` | + | Retrieve [_system buckets_](/influxdb/cloud/reference/internals/system-buckets/) | `read-orgs` | + + #### Related Guides + + - [Manage buckets](/influxdb/cloud/organizations/buckets/) + operationId: GetBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/After' + - description: | + An organization name. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Lists buckets for the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Lists buckets for the specified organization. + in: query + name: org + schema: + type: string + - description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Lists buckets for the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Lists buckets for the specified organization. + in: query + name: orgID + schema: + type: string + - description: | + A bucket name. + Only returns buckets with the specified name. + in: query + name: name + schema: + type: string + - description: | + A bucket ID. + Only returns the bucket with the specified ID. + in: query + name: id + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + buckets: + - createdAt: '2022-03-15T17:22:33.72617939Z' + description: System bucket for monitoring logs + id: 77ca9dace40a9bfc + labels: [] + links: + labels: /api/v2/buckets/77ca9dace40a9bfc/labels + members: /api/v2/buckets/77ca9dace40a9bfc/members + org: /api/v2/orgs/INFLUX_ORG_ID + owners: /api/v2/buckets/77ca9dace40a9bfc/owners + self: /api/v2/buckets/77ca9dace40a9bfc + write: /api/v2/write?org=ORG_ID&bucket=77ca9dace40a9bfc + name: _monitoring + orgID: INFLUX_ORG_ID + retentionRules: + - everySeconds: 604800 + type: expire + schemaType: implicit + 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 + schema: + $ref: '#/components/schemas/Buckets' + description: | + Success. + The response body contains a list of `buckets`. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List buckets + tags: + - Buckets + x-codeSamples: + - label: 'cURL: filter buckets by name' + lang: Shell + 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: | + Creates a [bucket](/influxdb/cloud/reference/glossary/#bucket) + and returns the bucket resource. + 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 or writing to more than 20 buckets at a time can adversely affect + performance. + + #### Limitations + + - InfluxDB Cloud Free Plan allows users to create up to two buckets. + Exceeding the bucket quota will result in an HTTP `403` status code. + For additional information regarding InfluxDB Cloud offerings, see + [InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). + + #### Related Guides + + - [Create a bucket](/influxdb/cloud/organizations/buckets/create-bucket/) + - [Create bucket CLI reference](/influxdb/cloud/reference/cli/influx/bucket/create) + operationId: PostBuckets + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostBucketRequest' + description: The bucket to create. + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-08-03T23:04:41.073704121Z' + description: A bucket holding air sensor data + id: 37407e232b3911d8 + labels: [] + links: + labels: /api/v2/buckets/37407e232b3911d8/labels + members: /api/v2/buckets/37407e232b3911d8/members + org: /api/v2/orgs/INFLUX_ORG_ID + owners: /api/v2/buckets/37407e232b3911d8/owners + self: /api/v2/buckets/37407e232b3911d8 + write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 + name: air_sensor + orgID: INFLUX_ORG_ID + retentionRules: + - everySeconds: 2592000 + type: expire + schemaType: implicit + type: user + updatedAt: '2022-08-03T23:04:41.073704228Z' + schema: + $ref: '#/components/schemas/Bucket' + description: | + Success. + The bucket is created. + '400': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '403': + content: + application/json: + examples: + quotaExceeded: + summary: Bucket quota exceeded + value: + code: forbidden + message: creating bucket would exceed quota + schema: + $ref: '#/components/schemas/Error' + description: | + Forbidden. + The bucket quota is exceeded. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: forbidden + type: string + '422': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Unprocessable Entity. + The request body failed validation. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a bucket + tags: + - Buckets + x-codeSamples: + - label: 'cURL: create a bucket with retention period' + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/buckets \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "air_sensor", + "description": "A bucket holding air sensor data", + "orgID": "INFLUX_ORG_ID", + "retentionRules": [ + { + "type": "expire", + "everySeconds": 2592000, + } + ] + }' + - label: cURL + lang: Shell + source: '' + /api/v2/buckets/{bucketID}: + delete: + description: | + Deletes a bucket and all associated records. + + #### InfluxDB Cloud + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. Returns an HTTP `204` status code if queued; _error_ otherwise. + 3. Handles the delete asynchronously. + + #### InfluxDB OSS + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Limitations + + - Only one bucket can be deleted per request. + + #### Related Guides + + - [Delete a bucket](/influxdb/cloud/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) + operationId: DeleteBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + Bucket ID. + The ID of the bucket to delete. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + + #### InfluxDB Cloud + - The bucket is queued for deletion. + + #### InfluxDB OSS + - The bucket is deleted. + '400': + content: + application/json: + examples: + invalidID: + summary: | + Invalid ID. + value: + code: invalid + message: id must have a length of 16 bytes + schema: + $ref: '#/components/schemas/Error' + description: | + Bad Request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested bucket was not found. + value: + code: not found + message: bucket not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + Bucket not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a bucket + tags: + - Buckets + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header 'Accept: application/json' + get: + description: | + Retrieves a bucket. + + Use this endpoint to retrieve information for a specific bucket. + operationId: GetBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the bucket to retrieve. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-08-03T23:04:41.073704121Z' + description: bucket for air sensor data + id: 37407e232b3911d8 + labels: [] + links: + labels: /api/v2/buckets/37407e232b3911d8/labels + members: /api/v2/buckets/37407e232b3911d8/members + org: /api/v2/orgs/INFLUX_ORG_ID + owners: /api/v2/buckets/37407e232b3911d8/owners + self: /api/v2/buckets/37407e232b3911d8 + write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 + name: air-sensor + orgID: bea7ea952287f70d + retentionRules: + - everySeconds: 2592000 + type: expire + schemaType: implicit + type: user + updatedAt: '2022-08-03T23:04:41.073704228Z' + schema: + $ref: '#/components/schemas/Bucket' + description: | + Success. + The response body contains the bucket information. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested bucket wasn't found. + value: + code: not found + message: bucket not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + Bucket not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a bucket + tags: + - Buckets + patch: + description: | + Updates a bucket. + + Use this endpoint to update properties + (`name`, `description`, and `retentionRules`) of a bucket. + + #### InfluxDB Cloud + + - Requires the `retentionRules` property in the request body. If you don't + provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. + + #### InfluxDB OSS + + - Doesn't require `retentionRules`. + + #### Related Guides + + - [Update a bucket](/influxdb/cloud/organizations/buckets/update-bucket/) + operationId: PatchBucketsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchBucketRequest' + description: The bucket update to apply. + required: true + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-08-03T23:04:41.073704121Z' + description: bucket holding air sensor data + id: 37407e232b3911d8 + labels: [] + links: + labels: /api/v2/buckets/37407e232b3911d8/labels + members: /api/v2/buckets/37407e232b3911d8/members + org: /api/v2/orgs/INFLUX_ORG_ID + owners: /api/v2/buckets/37407e232b3911d8/owners + self: /api/v2/buckets/37407e232b3911d8 + write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 + name: air_sensor + orgID: INFLUX_ORG_ID + retentionRules: + - everySeconds: 2592000 + type: expire + schemaType: implicit + type: user + updatedAt: '2022-08-07T22:49:49.422962913Z' + schema: + $ref: '#/components/schemas/Bucket' + description: An updated bucket + '400': + content: + application/json: + examples: + invalidJSONStringValue: + 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' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad Request. + '401': + $ref: '#/components/responses/AuthorizationError' + '403': + content: + application/json: + examples: + invalidRetention: + summary: | + The retention policy provided exceeds the max retention for the + organization. + value: + code: forbidden + message: provided retention exceeds orgs maximum retention duration + schema: + $ref: '#/components/schemas/Error' + description: | + Forbidden. + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested bucket wasn't found. + value: + code: not found + message: bucket not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + Bucket not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a bucket + tags: + - Buckets + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "air_sensor", + "description": "bucket holding air sensor data", + "retentionRules": [ + { + "type": "expire", + "everySeconds": 2592000 + } + ] + }' + /api/v2/buckets/{bucketID}/labels: + get: + description: | + Lists all labels for a bucket. + + Labels are objects that contain `labelID`, `name`, `description`, and `color` + key-value pairs. They may be used for grouping and filtering InfluxDB + resources. + Labels are also capable of grouping across different resources--for example, + you can apply a label named `air_sensor` to a bucket and a task to quickly + organize resources. + + #### Related guides + + - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - [Manage labels in the InfluxDB UI](/influxdb/cloud/visualize-data/labels/) + operationId: GetBucketsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the bucket to retrieve labels for. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + labels: + - id: 09cbd068e7ebb000 + name: production_buckets + orgID: INFLUX_ORG_ID + links: + self: /api/v2/labels + schema: + $ref: '#/components/schemas/LabelsResponse' + description: | + Success. + The response body contains a list of all labels 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: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a bucket + tags: + - Buckets + post: + description: | + Adds a label to a bucket and returns the new label information. + + Labels are objects that contain `labelID`, `name`, `description`, and `color` + key-value pairs. They may be used for grouping and filtering across one or + more kinds of **resources**--for example, you can apply a label named + `air_sensor` to a bucket and a task to quickly organize resources. + + #### Limitations + + - Before adding a label to a bucket, you must create the label if you + haven't already. To create a label with the InfluxDB API, send a `POST` + request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). + + #### Related guides + + - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. + - [Manage labels in the InfluxDB UI](/influxdb/cloud/visualize-data/labels/) + operationId: PostBucketsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + Bucket ID. + The ID of the bucket to label. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: An object that contains a _`labelID`_ to add to the bucket. + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + label: + id: 09cbd068e7ebb000 + name: production_buckets + orgID: INFLUX_ORG_ID + links: + self: /api/v2/labels + schema: + $ref: '#/components/schemas/LabelResponse' + description: | + Success. + The response body contains the label information. + '400': + $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The `labelID` is missing from the request body. + value: + code: invalid + message: label id is required + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '422': + content: + application/json: + examples: + conflictingResource: + summary: | + Label already exists on the resource. + value: + code: conflict + message: Cannot add label, label already exists on resource + schema: + $ref: '#/components/schemas/Error' + description: | + Unprocessable entity. + Label already exists on the resource. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a bucket + tags: + - Buckets + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "labelID": "09cbd068e7ebb000" + }' + /api/v2/buckets/{bucketID}/labels/{labelID}: + delete: + operationId: DeleteBucketsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The bucket ID. + in: path + name: bucketID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Bucket not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/members: + get: + description: | + Lists all users for a bucket. + + InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have + permission to access InfluxDB. + + [Members](/influxdb/cloud/reference/glossary/#member) are users in + an organization with access to the specified resource. + + Use this endpoint to retrieve all users with access to a bucket. + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + - [Manage members](/influxdb/cloud/organizations/members/) + operationId: GetBucketsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the bucket to retrieve users for. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + links: + self: /api/v2/buckets/37407e232b3911d8/members + users: + - id: 791df274afd48a83 + links: + self: /api/v2/users/791df274afd48a83 + name: example_user_1 + role: member + status: active + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active + schema: + $ref: '#/components/schemas/ResourceMembers' + description: | + Success. + The response body contains a list of all users 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: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a bucket + tags: + - Buckets + post: + description: | + Add a user to a bucket and return the new user information. + + InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have + permission to access InfluxDB. + + [Members](/influxdb/cloud/reference/glossary/#member) are users in + an organization. + + Use this endpoint to give a user member privileges to a bucket. + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + - [Manage members](/influxdb/cloud/organizations/members/) + operationId: PostBucketsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the bucket to retrieve users for. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: A user to add as a member to the bucket. + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: member + status: active + schema: + $ref: '#/components/schemas/ResourceMember' + description: | + Success. + The response body contains the user information. + '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: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a bucket + tags: + - Buckets + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + } + /api/v2/buckets/{bucketID}/members/{userID}: + delete: + description: | + Removes a member from a bucket. + + Use this endpoint to remove a user's member privileges from a bucket. This + removes the user's `read` and `write` permissions for the bucket. + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + - [Manage members](/influxdb/cloud/organizations/members/) + operationId: DeleteBucketsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the user to remove. + in: path + name: userID + required: true + schema: + type: string + - description: | + The ID of the bucket to remove a user from. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + The user is no longer a member of the bucket. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/owners: + get: + description: | + Lists all [owners](/influxdb/cloud/reference/glossary/#owner) + of a bucket. + + Bucket owners have permission to delete buckets and remove user and member + permissions from the bucket. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `read-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a + list of owners for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations-(API-tokens)) + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + operationId: GetBucketsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the bucket to retrieve owners for. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '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: | + 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: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a bucket + 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-(API-tokens)) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + *`INFLUX_ORG_ID`* is the ID of the organization that you want to add + an owner for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations-(API-tokens)) + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + operationId: PostBucketsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the bucket to add an owner for. + in: path + name: bucketID + required: true + schema: + type: string + 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: A user to add as an owner for the bucket. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + 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: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + 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-(API-tokens)) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner + from. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations-(API-tokens)) + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + operationId: DeleteBucketsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: | + The ID of the bucket to remove an owner from. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + The user is no longer an owner of the bucket. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a bucket + tags: + - Buckets + /api/v2/buckets/{bucketID}/schema/measurements: + get: + description: | + Lists _explicit_ + [schemas](/influxdb/cloud/reference/glossary/#schema) + (`"schemaType": "explicit"`) for a bucket. + + _Explicit_ schemas are used to enforce column names, tags, fields, and data + types for your data. + + By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`) + that conforms to your data. + + #### Related guides + + - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/) + operationId: getMeasurementSchemas + parameters: + - description: | + An organization name. + Specifies the organization that owns the schema. + in: query + name: org + schema: + type: string + - description: | + An organization ID. + Specifies the organization that owns the schema. + in: query + name: orgID + schema: + type: string + - description: | + A measurement name. + Only returns measurement schemas with the specified name. + in: query + name: name + schema: + type: string + - description: | + A bucket ID. + Lists measurement schemas for the specified bucket. + in: path + name: bucketID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementSchemaList' + description: A list of measurement schemas returning summary information. + headers: + ETag: + description: The current version of the bucket schema + schema: + type: string + '400': + content: + application/json: + examples: + invalidSchemaType: + summary: Invalid schema type. + value: + code: invalid + message: bucket schemaType must be explicit + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + summary: List measurement schemas of a bucket + tags: + - Bucket Schemas + post: + description: | + Creates an _explict_ measurement [schema](/influxdb/cloud/reference/glossary/#schema) + for a bucket. + + _Explicit_ schemas are used to enforce column names, tags, fields, and data + types for your data. + + By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`) + that conforms to your data. + + Use this endpoint to create schemas that prevent non-conforming write requests. + + #### Limitations + + - Buckets must be created with the "explict" `schemaType` in order to use + schemas. + + #### Related guides + + - [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). + - [Create a bucket with an explicit schema](/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) + operationId: createMeasurementSchema + parameters: + - description: | + An organization name. + Specifies the organization that owns the schema. + in: query + name: org + schema: + type: string + - description: | + An organization ID. + Specifies the organization that owns the schema. + in: query + name: orgID + schema: + type: string + - description: | + A bucket ID. + Adds a schema for the specified bucket. + in: path + name: bucketID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementSchemaCreateRequest' + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementSchema' + description: The current version of the measurement schema. + headers: + ETag: + description: The current version of the measurement schema + schema: + type: string + '400': + content: + 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. + summary: Invalid name + value: + code: invalid + message: name is invalid + duplicateColumnNamesExample: + 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. + 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. + 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. + summary: Missing timestamp + value: + code: invalid + message: Timestamp column is required + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + summary: Create a measurement schema for a bucket + tags: + - Bucket Schemas + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "temperature", + "column": [ + { + "type": "tag", + "name": "location" + }, + { + "type": "field", + "name": "value", + "dataType": "float" + }, + { + "type": "timestamp", + "name": "time" + } + ] + }' + summary: Bucket schemas + /api/v2/buckets/{bucketID}/schema/measurements/{measurementID}: + get: + description: | + Retrieves an explicit measurement [schema](/influxdb/cloud/reference/glossary/#schema). + operationId: getMeasurementSchema + parameters: + - description: | + Organization name. + Specifies the organization that owns the schema. + in: query + name: org + schema: + type: string + - description: | + Organization ID. + Specifies the organization that owns the schema. + in: query + name: orgID + schema: + type: string + - description: | + A bucket ID. + Retrieves schemas for the specified bucket. + in: path + name: bucketID + required: true + schema: + type: string + - description: | + The measurement schema ID. + Specifies the measurement schema to retrieve. + in: path + name: measurementID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementSchema' + description: Schema definition for a single measurement + headers: + ETag: + description: The current version of the measurement schema + schema: + type: string + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + summary: Retrieve a measurement schema + tags: + - Bucket Schemas + patch: + description: | + Updates a measurement [schema](/influxdb/cloud/reference/glossary/#schema). + + Use this endpoint to update the fields (`name`, `type`, and `dataType`) of a + measurement schema. + + #### Limitations + + - You can't update the `name` of a measurement. + + #### Related guides + + - [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). + - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/). + operationId: updateMeasurementSchema + parameters: + - description: | + An organization name. + Specifies the organization that owns the schema. + in: query + name: org + schema: + type: string + - description: | + An organization ID. + Specifies the organization that owns the schema. + in: query + name: orgID + schema: + type: string + - description: | + A bucket ID. + Specifies the bucket to retrieve schemas for. + in: path + name: bucketID + required: true + schema: + type: string + - description: | + A measurement schema ID. + Retrieves the specified measurement schema. + in: path + name: measurementID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementSchemaUpdateRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementSchema' + description: | + Success. + The response body contains the measurement schema. + '400': + content: + application/json: + examples: + missingColumnsExample: + description: The error returned when the request body does not contain all the columns from the source. + summary: Deleted columns + value: + code: invalid + message: Unable to delete columns from schema + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + summary: Update a measurement schema + tags: + - Bucket Schemas + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request PATCH "INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "column": [ + { + "type": "tag", + "name": "location" + }, + { + "type": "field", + "name": "value", + "dataType": "float" + }, + { + "type": "timestamp", + "name": "time" + } + ] + }' + summary: Bucket Schema + /api/v2/checks: {} + /api/v2/checks/{checkID}: {} + /api/v2/checks/{checkID}/labels: {} + /api/v2/checks/{checkID}/labels/{labelID}: {} + /api/v2/checks/{checkID}/query: {} + /api/v2/dashboards: {} + /api/v2/dashboards/{dashboardID}: {} + /api/v2/dashboards/{dashboardID}/cells: {} + /api/v2/dashboards/{dashboardID}/cells/{cellID}: {} + /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: {} + /api/v2/dashboards/{dashboardID}/labels: {} + /api/v2/dashboards/{dashboardID}/labels/{labelID}: {} + /api/v2/dashboards/{dashboardID}/members: {} + /api/v2/dashboards/{dashboardID}/members/{userID}: {} + /api/v2/dashboards/{dashboardID}/owners: {} + /api/v2/dashboards/{dashboardID}/owners/{userID}: {} + /api/v2/dbrps: + get: + description: | + Lists database retention policy (DBRP) mappings. + + #### Related guide + + - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) + operationId: GetDBRPs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + An organization ID. + Only returns DBRP mappings for the specified organization. + in: query + name: orgID + schema: + type: string + - description: | + An organization name. + Only returns DBRP mappings for the specified organization. + in: query + name: org + schema: + type: string + - description: | + A DBPR mapping ID. + Only returns the specified DBRP mapping. + in: query + name: id + schema: + type: string + - description: | + A bucket ID. + Only returns DBRP mappings that belong to the specified bucket. + in: query + name: bucketID + schema: + type: string + - description: Specifies filtering on default + in: query + name: default + schema: + type: boolean + - description: | + A database. + Only returns DBRP mappings that belong to the 1.x database. + in: query + name: db + schema: + type: string + - description: | + A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). + Specifies the 1.x retention policy to filter on. + in: query + name: rp + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + content: + - bucketID: 4d4d9d5b61dee751 + database: example_database_1 + default: true + id: 0a3cbb5dd526a000 + orgID: bea7ea952287f70d + retention_policy: autogen + - bucketID: 4d4d9d5b61dee751 + database: example_database_2 + default: false + id: 0a3cbcde20e38000 + orgID: bea7ea952287f70d + retention_policy: example_retention_policy + schema: + $ref: '#/components/schemas/DBRPs' + description: Success. The response body contains a list of database retention policy mappings. + '400': + content: + application/json: + examples: + invalidRequest: + description: | + The query parameters contain invalid values. + value: + code: invalid + message: invalid ID + schema: + $ref: '#/components/schemas/Error' + description: Bad request. The request has one or more invalid parameters. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List database retention policy mappings + tags: + - DBRPs + post: + description: | + Creates a database retention policy (DBRP) mapping and returns the mapping. + + Use this endpoint to add InfluxDB 1.x API compatibility to your + InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a + DBRP mapping in order to query and write using the InfluxDB 1.x API. + object. + + #### Related guide + + - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) + operationId: PostDBRP + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPCreate' + description: | + The database retention policy mapping to add. + + Note that _`retention_policy`_ is a required parameter in the request body. + The value of _`retention_policy`_ can be any arbitrary `string` name or + value, with the default value commonly set as `autogen`. + The value of _`retention_policy`_ isn't a [retention_policy](/influxdb/cloud/reference/glossary/#retention-policy-rp) + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + bucketID: 4d4d9d5b61dee751 + database: example_database + default: true + id: 0a3cbb5dd526a000 + orgID: bea7ea952287f70d + retention_policy: autogen + schema: + $ref: '#/components/schemas/DBRP' + description: Created. The response body contains the database retention policy mapping. + '400': + content: + application/json: + examples: + invalidRequest: + description: | + The query parameters contain invalid values. + value: + code: invalid + message: invalid ID + schema: + $ref: '#/components/schemas/Error' + description: Bad request. The mapping in the request has one or more invalid IDs. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a database retention policy mapping + tags: + - DBRPs + x-codeSamples: + - label: 'cURL: create a database retention policy mapping' + lang: Shell + source: | + curl --request POST \ + "http://localhost:8086/api/v2/dbrp/" \ + --header 'Content-type: application/json' \ + --header "Authorization: Token INFLUXDB_TOKEN" \ + --data-binary @- << EOF + { \ + "bucketID": "INFLUXDB_BUCKET_ID", \ + "orgID": "INFLUXDB_ORG_ID", \ + "database": "database_name", \ + "default": true, \ + "retention_policy": "example_retention_policy_name" \ + } + EOF + /api/v2/dbrps/{dbrpID}: + delete: + description: | + Deletes the specified database retention policy (DBRP) mapping. + + #### Related guide + + - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) + operationId: DeleteDBRPID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + An organization ID. + Specifies the organization that owns the DBRP mapping. + in: query + name: orgID + schema: + type: string + - description: | + An organization name. + Specifies the organization that owns the DBRP mapping. + in: query + name: org + schema: + type: string + - description: | + A DBRP mapping ID. + Only returns the specified DBRP mapping. + in: path + name: dbrpID + required: true + schema: + type: string + responses: + '204': + description: Success. The delete is accepted. + '400': + content: + application/json: + examples: + invalidRequest: + description: | + The query parameters contain invalid values. + value: + code: invalid + message: invalid ID + schema: + $ref: '#/components/schemas/Error' + description: Bad Request. Query parameters contain invalid values. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a database retention policy + tags: + - DBRPs + get: + description: | + Retrieves the specified retention policy (DBRP) mapping. + + #### Related guide + + - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) + operationId: GetDBRPsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + An organization ID. + Specifies the organization that owns the DBRP mapping. + in: query + name: orgID + schema: + type: string + - description: | + An organization name. + Specifies the organization that owns the DBRP mapping. + in: query + name: org + schema: + type: string + - description: | + A DBRP mapping ID. + Specifies the DBRP mapping. + in: path + name: dbrpID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + content: + bucketID: 4d4d9d5b61dee751 + database: example_database_1 + default: true + id: 0a3cbb5dd526a000 + orgID: bea7ea952287f70d + retention_policy: autogen + schema: + $ref: '#/components/schemas/DBRPGet' + description: Success. The response body contains the DBRP mapping. + '400': + content: + application/json: + examples: + invalidRequest: + description: | + The query parameters contain invalid values. + value: + code: invalid + message: invalid ID + schema: + $ref: '#/components/schemas/Error' + description: Bad Request. Query parameters contain invalid values. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a database retention policy mapping + tags: + - DBRPs + patch: + operationId: PatchDBRPID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + An organization ID. + Specifies the organization that owns the DBRP mapping. + in: query + name: orgID + schema: + type: string + - description: | + An organization name. + Specifies the organization that owns the DBRP mapping. + in: query + name: org + schema: + type: string + - description: | + A DBRP mapping ID. + Specifies the DBRP mapping. + in: path + name: dbrpID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DBRPUpdate' + description: | + Updates the database retention policy (DBRP) mapping and returns the mapping. + + Use this endpoint to modify the _retention policy_ (`retention_policy` property) of a DBRP mapping. + + #### Related guide + + - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) + required: true + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + content: + bucketID: 4d4d9d5b61dee751 + database: example_database + default: false + id: 0a3cbb5dd526a000 + orgID: bea7ea952287f70d + retention_policy: example_retention_policy + schema: + $ref: '#/components/schemas/DBRPGet' + description: An updated mapping + '400': + content: + application/json: + examples: + invalidRequest: + description: | + The query parameters contain invalid values. + value: + code: invalid + message: invalid ID + schema: + $ref: '#/components/schemas/Error' + description: Bad Request. Query parameters contain invalid values. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a database retention policy mapping + tags: + - DBRPs + x-codeSamples: + - label: 'cURL: Update a DBRP mapping' + lang: Shell + source: | + curl --request PATCH \ + "http://localhost:8086/api/v2/dbrp/DBRP_ID" \ + --header 'Content-type: application/json' \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --data-binary @- << EOF + { + "default": true, + "retention_policy": "example_retention_policy_name" + } + EOF + /api/v2/delete: + post: + description: | + Deletes data from a bucket. + + Use this endpoint to delete points from a bucket in a specified time range. + + #### InfluxDB Cloud + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. + 3. Handles the delete asynchronously and reaches eventual consistency. + + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, + wait for a success response (HTTP `2xx` status code) before you send the next request. + + Because writes and deletes are asynchronous, your change might not yet be readable + when you receive the response. + + #### InfluxDB OSS + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Required permissions + + - `write-buckets` or `write-bucket BUCKET_ID`. + + *`BUCKET_ID`* is the ID of the destination bucket. + + #### Rate limits (with InfluxDB Cloud) + + `write` rate limits apply. + For more information, see [limits and adjustable quotas](/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/) + and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). + operationId: PostDelete + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Deletes data from the bucket in the organization + associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. + - Deletes data from the bucket in the specified organization. + - If you pass both `orgID` and `org`, they must both be valid. + in: query + name: org + schema: + description: The organization name or ID. + type: string + - description: | + A bucket name or ID. + Specifies the bucket to delete data from. + If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. + in: query + name: bucket + schema: + description: The bucket name or ID. + type: string + - description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Deletes data from the bucket in the organization + associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. + - Deletes data from the bucket in the specified organization. + - If you pass both `orgID` and `org`, they must both be valid. + in: query + name: orgID + schema: + description: The organization ID. + type: string + - description: | + A bucket ID. + Specifies the bucket to delete data from. + If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. + in: query + name: bucketID + schema: + description: The bucket ID. + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeletePredicateRequest' + description: | + Time range parameters and an optional **delete predicate expression**. + + To select points to delete within the specified time range, pass a + **delete predicate expression** in the `predicate` property of the request body. + If you don't pass a `predicate`, InfluxDB deletes all data with timestamps + in the specified time range. + + #### Related guides + + - [Delete data](/influxdb/cloud/write-data/delete-data/) + - Learn how to use [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). + required: true + responses: + '204': + description: | + Success. + + #### InfluxDB Cloud + + - Validated and queued the request. + - Handles the delete asynchronously - the deletion might not have completed yet. + + An HTTP `2xx` status code acknowledges that the write or delete is queued. + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, + wait for a response before you send the next request. + + Because writes are asynchronous, data might not yet be written + when you receive the response. + + #### InfluxDB OSS + + - Deleted the data. + '400': + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Delete data + tags: + - Data I/O endpoints + - Delete + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --header 'Content-Type: application/json' \ + --data '{ + "start": "2020-03-01T00:00:00Z", + "stop": "2020-11-14T00:00:00Z", + "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")" + }' + /api/v2/flags: {} + /api/v2/labels: {} + /api/v2/labels/{labelID}: {} + /api/v2/maps/mapToken: + get: + operationId: getMapboxToken + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Token' + description: Temporary token for Mapbox. + '401': + $ref: '#/components/responses/ServerError' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/ServerError' + summary: Get a mapbox token + /api/v2/me: {} + /api/v2/me/password: {} + /api/v2/notificationEndpoints: {} + /api/v2/notificationEndpoints/{endpointID}: {} + /api/v2/notificationEndpoints/{endpointID}/labels: {} + /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: {} + /api/v2/notificationRules: {} + /api/v2/notificationRules/{ruleID}: {} + /api/v2/notificationRules/{ruleID}/labels: {} + /api/v2/notificationRules/{ruleID}/labels/{labelID}: {} + /api/v2/notificationRules/{ruleID}/query: {} + /api/v2/orgs: + get: + description: | + Lists [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. + + #### Related guides + + - [View organizations](/influxdb/cloud/organizations/view-orgs/) + operationId: GetOrgs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/Offset' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Descending' + - description: | + An organization name. + Only returns the specified organization. + in: query + name: org + schema: + type: string + - description: | + An organization ID. + Only returns the specified organization. + in: query + name: orgID + schema: + type: string + - description: | + A user ID. + Only returns organizations where the specified user is a member or owner. + in: query + name: userID + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs + orgs: + - createdAt: '2022-07-17T23:00:30.778487Z' + description: Example InfluxDB organization + id: INFLUX_ORG_ID + links: + buckets: /api/v2/buckets?org=INFLUX_ORG + dashboards: /api/v2/dashboards?org=INFLUX_ORG + labels: /api/v2/orgs/INFLUX_ORG_ID/labels + logs: /api/v2/orgs/INFLUX_ORG_ID/logs + members: /api/v2/orgs/INFLUX_ORG_ID/members + owners: /api/v2/orgs/INFLUX_ORG_ID/owners + secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets + self: /api/v2/orgs/INFLUX_ORG_ID + tasks: /api/v2/tasks?org=InfluxData + name: INFLUX_ORG + updatedAt: '2022-07-17T23:00:30.778487Z' + schema: + $ref: '#/components/schemas/Organizations' + description: Success. The response body contains a list of organizations. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: List organizations + tags: + - Organizations + - Security and access endpoints + post: + 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: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostOrganizationRequest' + description: The organization to create. + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-08-24T23:05:52.881317Z' + description: '' + id: INFLUX_ORG_ID + links: + buckets: /api/v2/buckets?org=INFLUX_ORG + dashboards: /api/v2/dashboards?org=INFLUX_ORG + labels: /api/v2/orgs/INFLUX_ORG_ID/labels + logs: /api/v2/orgs/INFLUX_ORG_ID/logs + members: /api/v2/orgs/INFLUX_ORG_ID/members + owners: /api/v2/orgs/INFLUX_ORG_ID/owners + secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets + self: /api/v2/orgs/INFLUX_ORG_ID + tasks: /api/v2/tasks?org=INFLUX_ORG + name: INFLUX_ORG + updatedAt: '2022-08-24T23:05:52.881318Z' + schema: + $ref: '#/components/schemas/Organization' + description: Created. The response body contains the organization information. + '400': + $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The `name` field is missing from the request body. + value: + code: invalid + message: org name is empty + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create an organization + tags: + - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/orgs \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "INFLUX_ORG", + "description: "Example InfluxDB organization" + }' + /api/v2/orgs/{orgID}: + delete: + description: | + Deletes an organization. + + Deleting an organization from InfluxDB Cloud can't be undone. + Once deleted, all data associated with the organization is removed. + + #### InfluxDB Cloud + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. Returns an HTTP `204` status code if queued; _error_ otherwise. + 3. Handles the delete asynchronously. + + #### InfluxDB OSS + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Limitations + + - Only one organization can be deleted per request. + + #### Related guides + + - [Delete organizations](/influxdb/cloud/organizations/delete-orgs/) + operationId: DeleteOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the organization to delete. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + + #### InfluxDB Cloud + - The organization is queued for deletion. + + #### InfluxDB OSS + - The organization is deleted. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested organization was not found. + value: + code: not found + message: org not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + InfluxDB can't find the organization. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete an organization + tags: + - Organizations + get: + description: | + Retrieves an organization. + + Use this endpoint to retrieve information for a specific organization. + + #### Related guides + + - [View organizations](/influxdb/cloud/organizations/view-orgs/) + operationId: GetOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the organization to retrieve. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: | + Success. + The response body contains the organization information. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested organization wasn't found. + value: + code: not found + message: organization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + Organization not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve an organization + tags: + - Organizations + - Security and access endpoints + patch: + description: | + Updates an organization. + + Use this endpoint to update properties + (`name`, `description`) of an organization. + + Updating an organizationโ€™s name affects all resources that reference the + organization by name, including the following: + + - Queries + - Dashboards + - Tasks + - Telegraf configurations + - Templates + + If you change an organization name, be sure to update the organization name + in these resources as well. + + #### Related Guides + + - [Update an organization](/influxdb/cloud/organizations/update-org/) + operationId: PatchOrgsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the organization to update. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PatchOrganizationRequest' + description: The organization update to apply. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + description: Success. The response body contains the updated organization. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update an organization + tags: + - Organizations + /api/v2/orgs/{orgID}/limits: + get: + operationId: GetOrgLimitsID + parameters: + - description: The ID of the organization. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + description: These are org limits similar to those configured in/by quartz. + properties: + limits: + $ref: '#/components/schemas/Limit' + links: + $ref: '#/components/schemas/Links' + type: object + description: Limits defined for the organization. + default: + $ref: '#/components/responses/GeneralServerError' + description: unexpected error + summary: Retrieve limits for an organization + tags: + - Limits + /api/v2/orgs/{orgID}/members: + get: + description: | + Lists 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-(API-tokens)) to assign user permissions. + + #### Limitations + + - Member permissions are separate from API token permissions. + - Member permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `read-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve + members for. + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + - [Manage members](/influxdb/cloud/organizations/members/) + operationId: GetOrgsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the organization to retrieve users for. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs/055aa4783aa38398/members + users: + - id: 791df274afd48a83 + links: + self: /api/v2/users/791df274afd48a83 + name: example_user_1 + role: member + status: active + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active + schema: + $ref: '#/components/schemas/ResourceMembers' + description: | + Success. + The response body contains a list of all users within the organization. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested organization wasn't found. + value: + code: not found + message: 404 page not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + InfluxDB can't find the organization. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all members of an organization + tags: + - Organizations + - Security and access endpoints + post: + 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-(API-tokens)) to assign user permissions. + + #### Limitations + + - Member permissions are separate from API token permissions. + - Member permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to. + + #### Related guides + + - [Manage users](/influxdb/cloud/users/) + - [Manage members](/influxdb/cloud/organizations/members/) + operationId: PostOrgsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the organization. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: | + The user to add to the organization. + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: member + status: active + schema: + $ref: '#/components/schemas/ResourceMember' + description: | + Success. + The response body contains the user information. + '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: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to an organization + tags: + - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + }' + /api/v2/orgs/{orgID}/members/{userID}: + delete: + description: | + Removes a member from an organization. + + Use this endpoint to remove a user's member privileges for an organization. + Removing member privileges removes the user's `read` and `write` permissions + from the organization. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + #### Limitations + + - Member permissions are separate from API token permissions. + - Member permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an + owner from. + + #### Related guides + + - [Manage members](/influxdb/cloud/organizations/members/) + operationId: DeleteOrgsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the user to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The ID of the organization to remove a user from. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + The user is no longer a member of the organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from an organization + tags: + - Organizations + - Security and access endpoints + /api/v2/orgs/{orgID}/owners: + get: + description: | + Lists all owners of an organization. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + #### Required permissions + + - `read-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a + list of owners from. + operationId: GetOrgsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the organization to list owners for. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs/055aa4783aa38398/owners + users: + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active + schema: + $ref: '#/components/schemas/ResourceOwners' + description: A list of organization owners + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Organization not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of an organization + tags: + - Organizations + - Security and access endpoints + post: + description: | + Adds an owner to an organization. + + Use this endpoint to assign the organization `owner` role to a user. + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. + + #### Related endpoints + + - [Authorizations](#tag/Authorizations-(API-tokens)) + operationId: PostOrgsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the organization that you want to add an owner for. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: owner + status: active + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: The user to add as an owner of the organization. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: | + Success. The user is an owner of the organization. + The response body contains the owner with role and user detail. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to an organization + tags: + - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + }' + /api/v2/orgs/{orgID}/owners/{userID}: + delete: + description: | + Removes an [owner](/influxdb/cloud/reference/glossary/#owner) from + the organization. + + Organization owners have permission to delete organizations and remove user and member + permissions from the organization. + + #### InfluxDB Cloud + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + #### Limitations + + - Owner permissions are separate from API token permissions. + - Owner permissions are used in the context of the InfluxDB UI. + + #### Required permissions + + - `write-orgs INFLUX_ORG_ID` + + *`INFLUX_ORG_ID`* is the ID of the organization that you want to + remove an owner from. + + #### Related endpoints + - [Authorizations](#tag/Authorizations-(API-tokens)) + operationId: DeleteOrgsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the user to remove. + in: path + name: userID + required: true + schema: + type: string + - description: | + The ID of the organization to remove an owner from. + in: path + name: orgID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + The user is no longer an owner of the organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from an organization + tags: + - Organizations + - Security and access endpoints + /api/v2/orgs/{orgID}/secrets: + get: + operationId: GetOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SecretKeysResponse' + description: A list of all secret keys + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all secret keys for an organization + tags: + - Secrets + - Security and access endpoints + patch: + operationId: PatchOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Secrets' + description: Secret key value pairs to update/add + required: true + responses: + '204': + description: Keys successfully patched + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update secrets in an organization + tags: + - Secrets + /api/v2/orgs/{orgID}/secrets/{secretID}: + delete: + operationId: DeleteOrgsIDSecretsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + - description: The secret ID. + in: path + name: secretID + required: true + schema: + type: string + responses: + '204': + description: Keys successfully deleted + default: + $ref: '#/components/responses/GeneralServerError' + description: Unexpected error + summary: Delete a secret from an organization + tags: + - Secrets + - Security and access endpoints + /api/v2/orgs/{orgID}/secrets/delete: + post: + deprecated: true + operationId: PostOrgsIDSecrets + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID. + in: path + name: orgID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SecretKeys' + description: Secret key to delete + required: true + responses: + '204': + description: Keys successfully patched + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete secrets from an organization + tags: + - Secrets + - Security and access endpoints + /api/v2/orgs/{orgID}/usage: + get: + operationId: GetOrgUsageID + parameters: + - description: The ID of the organization. + in: path + name: orgID + required: true + schema: + type: string + - description: | + Earliest time to include in results. + 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: | + Latest time to include in results. + For more information about timestamps, see [Manipulate timestamps with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). + in: query + name: stop + required: false + schema: + format: unix timestamp + type: integer + - description: return raw usage data + in: query + name: raw + required: false + schema: + default: false + type: boolean + responses: + '200': + 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 + type: string + description: Usage data + headers: + Content-Encoding: + 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. + enum: + - gzip + - identity + type: string + default: + $ref: '#/components/responses/GeneralServerError' + description: unexpected error + summary: Retrieve usage for an organization + tags: + - Usage + /ping: {} + /api/v2/query: + post: + description: | + Retrieves data from buckets. + + Use this endpoint to send a Flux query request and retrieve data from a bucket. + + #### Rate limits (with InfluxDB Cloud) + + `read` rate limits apply. + For more information, see [limits and adjustable quotas](/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/) + operationId: PostQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - 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. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + enum: + - application/json + - application/vnd.flux + type: string + - description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + in: query + name: org + schema: + type: string + - description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Queries the bucket in the organization associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or `orgID` parameter. + - Queries the bucket in the specified organization. + in: query + name: orgID + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + application/vnd.flux: + example: | + from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement") + schema: + type: string + description: Flux query or specification to execute + responses: + '200': + content: + application/csv: + example: | + result,table,_start,_stop,_time,region,host,_value + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 + mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 + schema: + 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. + schema: + default: identity + description: | + The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. + enum: + - gzip + - identity + type: string + Trace-Id: + description: The trace ID, if generated, of the request. + schema: + description: Trace ID of a request. + type: string + '400': + content: + application/json: + examples: + orgNotFound: + summary: Organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '429': + description: | + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit](/influxdb/cloud/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + format: int32 + type: integer + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Query data + tags: + - Data I/O endpoints + - Query + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ + --header 'Content-Type: application/vnd.flux' \ + --header 'Accept: application/csv \ + --header 'Authorization: Token INFLUX_API_TOKEN' \ + --data 'from(bucket: "example-bucket") + |> range(start: -5m) + |> filter(fn: (r) => r._measurement == "example-measurement")' + /api/v2/query/analyze: + post: + description: | + Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax + errors and returns the list of errors. + + In the following sample query, `from()` is missing the property key. + + ```json + { "query": "from(: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + ``` + + If you pass this in a request to the `/api/v2/analyze` endpoint, + InfluxDB returns an `errors` list that contains an error object for the missing key. + + #### Limitations + + - The endpoint doesn't validate values in the query--for example: + + - The following sample query has correct syntax, but contains an incorrect `from()` property key: + + ```json + { "query": "from(foo: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + ``` + + If you pass this in a request to the `/api/v2/analyze` endpoint, + InfluxDB returns an empty `errors` list. + operationId: PostQueryAnalyze + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + description: Flux query to analyze + responses: + '200': + content: + application/json: + examples: + missingQueryPropertyKey: + description: | + Returns an error object if the Flux query is missing a property key. + + The following sample query is missing the _`bucket`_ property key: + + ```json + { + "query": "from(: \"iot_center\")\ + ... + } + ``` + summary: Missing property key error + value: + errors: + - character: 0 + column: 6 + line: 1 + message: missing property key + schema: + $ref: '#/components/schemas/AnalyzeQueryResponse' + description: | + Success. + The response body contains the list of `errors`. + If the query syntax is valid, the endpoint returns an empty `errors` list. + '400': + content: + application/json: + examples: + invalidJSONStringValue: + description: If the request body contains invalid JSON, returns `invalid` and problem detail. + summary: Invalid JSON + value: + code: invalid + message: 'invalid json: invalid character ''\'''' looking for beginning of value' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the problem. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: invalid + type: string + default: + content: + application/json: + examples: + emptyJSONObject: + description: | + If the request body contains an empty JSON object, returns `internal error`. + summary: Empty JSON object in request body + value: + code: internal error + message: An internal error has occurred - check server logs + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + headers: + X-Influx-Error: + description: A string that describes the problem. + schema: + type: string + X-Influx-Reference: + description: The numeric reference code for the error type. + schema: + type: integer + X-Platform-Error-Code: + description: The reason for the error. + schema: + example: internal error + type: string + summary: Analyze a Flux query + tags: + - Query + x-codeSamples: + - label: 'cURL: Analyze a Flux query' + lang: Shell + source: | + curl -v --request POST \ + "http://localhost:8086/api/v2/query/analyze" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header 'Content-type: application/json' \ + --header 'Accept: application/json' \ + --data-binary @- << EOF + { "query": "from(bucket: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")", + "type": "flux" + } + EOF + /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) + for the query. + + Use this endpoint for deep query analysis such as debugging unexpected query + results. + + A Flux query AST provides a semantic, tree-like representation with contextual + information about the query. The AST illustrates how the query is distributed + into different components for execution. + + #### Limitations + + - The endpoint doesn't validate values in the query--for example: + + The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: + + ```js + from(foo: "iot_center") + |> range(start: -90d) + |> filter(fn: (r) => r._measurement == "environment") + ``` + + The following sample JSON shows how to pass the query in the request body: + + ```js + from(foo: "iot_center") + |> range(start: -90d) + |> filter(fn: (r) => r._measurement == "environment") + ``` + + The following code sample shows how to pass the query as JSON in the request body: + + ```json + { "query": "from(foo: \"iot_center\")\ + |> range(start: -90d)\ + |> filter(fn: (r) => r._measurement == \"environment\")" + } + ``` + + Passing this to `/api/v2/query/ast` will return a successful response + with a generated AST. + operationId: PostQueryAst + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LanguageRequest' + description: The Flux query to analyze. + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + ast: + files: + - body: + - expression: + argument: + argument: + arguments: + - location: + end: + column: 25 + line: 1 + source: 'bucket: "example-bucket"' + start: + column: 6 + line: 1 + properties: + - key: + location: + end: + column: 12 + line: 1 + source: bucket + start: + column: 6 + line: 1 + name: bucket + type: Identifier + location: + end: + column: 25 + line: 1 + source: 'bucket: "example-bucket"' + start: + column: 6 + line: 1 + type: Property + value: + location: + end: + column: 25 + line: 1 + source: '"example-bucket"' + start: + column: 14 + line: 1 + type: StringLiteral + value: example-bucket + type: ObjectExpression + callee: + location: + end: + column: 5 + line: 1 + source: from + start: + column: 1 + line: 1 + name: from + type: Identifier + location: + end: + column: 26 + line: 1 + source: 'from(bucket: "example-bucket")' + start: + column: 1 + line: 1 + type: CallExpression + call: + arguments: + - location: + end: + column: 46 + line: 1 + source: 'start: -5m' + start: + column: 36 + line: 1 + properties: + - key: + location: + end: + column: 41 + line: 1 + source: start + start: + column: 36 + line: 1 + name: start + type: Identifier + location: + end: + column: 46 + line: 1 + source: 'start: -5m' + start: + column: 36 + line: 1 + type: Property + value: + argument: + location: + end: + column: 46 + line: 1 + source: 5m + start: + column: 44 + line: 1 + type: DurationLiteral + values: + - magnitude: 5 + unit: m + location: + end: + column: 46 + line: 1 + source: '-5m' + start: + column: 43 + line: 1 + operator: '-' + type: UnaryExpression + type: ObjectExpression + callee: + location: + end: + column: 35 + line: 1 + source: range + start: + column: 30 + line: 1 + name: range + type: Identifier + location: + end: + column: 47 + line: 1 + source: 'range(start: -5m)' + start: + column: 30 + line: 1 + type: CallExpression + location: + end: + column: 47 + line: 1 + source: 'from(bucket: "example-bucket") |> range(start: -5m)' + start: + column: 1 + line: 1 + type: PipeExpression + call: + arguments: + - location: + end: + column: 108 + line: 1 + source: 'fn: (r) => r._measurement == "example-measurement"' + start: + column: 58 + line: 1 + properties: + - key: + location: + end: + column: 60 + line: 1 + source: fn + start: + column: 58 + line: 1 + name: fn + type: Identifier + location: + end: + column: 108 + line: 1 + source: 'fn: (r) => r._measurement == "example-measurement"' + start: + column: 58 + line: 1 + type: Property + value: + body: + left: + location: + end: + column: 83 + line: 1 + source: r._measurement + start: + column: 69 + line: 1 + object: + location: + end: + column: 70 + line: 1 + source: r + start: + column: 69 + line: 1 + name: r + type: Identifier + property: + location: + end: + column: 83 + line: 1 + source: _measurement + start: + column: 71 + line: 1 + name: _measurement + type: Identifier + type: MemberExpression + location: + end: + column: 108 + line: 1 + source: r._measurement == "example-measurement" + start: + column: 69 + line: 1 + operator: '==' + right: + location: + end: + column: 108 + line: 1 + source: '"example-measurement"' + start: + column: 87 + line: 1 + type: StringLiteral + value: example-measurement + type: BinaryExpression + location: + end: + column: 108 + line: 1 + source: (r) => r._measurement == "example-measurement" + start: + column: 62 + line: 1 + params: + - key: + location: + end: + column: 64 + line: 1 + source: r + start: + column: 63 + line: 1 + name: r + type: Identifier + location: + end: + column: 64 + line: 1 + source: r + start: + column: 63 + line: 1 + type: Property + value: null + type: FunctionExpression + type: ObjectExpression + callee: + location: + end: + column: 57 + line: 1 + source: filter + start: + column: 51 + line: 1 + name: filter + type: Identifier + location: + end: + column: 109 + line: 1 + source: 'filter(fn: (r) => r._measurement == "example-measurement")' + start: + column: 51 + line: 1 + type: CallExpression + location: + end: + column: 109 + line: 1 + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' + start: + column: 1 + line: 1 + type: PipeExpression + location: + end: + column: 109 + line: 1 + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' + start: + column: 1 + line: 1 + type: ExpressionStatement + imports: null + location: + end: + column: 109 + line: 1 + source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' + start: + column: 1 + line: 1 + metadata: parser-type=rust + package: null + type: File + package: main + type: Package + schema: + $ref: '#/components/schemas/ASTResponse' + description: | + Success. + The response body contains an Abstract Syntax Tree (AST) of the Flux query. + '400': + content: + application/json: + examples: + invalidASTValue: + description: | + If the request body contains a missing property key in `from()`, + returns `invalid` and problem detail. + summary: Invalid AST + value: + code: invalid + message: 'invalid AST: loc 1:6-1:19: missing property key' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + InfluxDB is unable to parse the request. + The response body contains detail about the problem. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: invalid + type: string + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error. + summary: Generate a query Abstract Syntax Tree (AST) + tags: + - Query + x-codeSamples: + - label: 'cURL: Analyze and generate AST for the query' + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/query/ast" \ + --header 'Content-Type: application/json' \ + --header 'Accept: application/json' \ + --header "Authorization: Token INFLUX_TOKEN" \ + --data-binary @- << EOL + { + "query": "from(bucket: \"INFLUX_BUCKET_NAME\")\ + |> range(start: -5m)\ + |> filter(fn: (r) => r._measurement == \"example-measurement\")" + } + EOL + /api/v2/query/suggestions: + get: + description: | + Lists Flux query suggestions. Each suggestion contains a + [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) + name and parameters. + + Use this endpoint to retrieve a list of Flux query suggestions used in the + InfluxDB Flux Query Builder. + + #### Limitations + + - When writing a query, avoid using `_functionName()` helper functions + exposed by this endpoint. Helper function names have an underscore (`_`) + prefix and aren't meant to be used directly in queries--for example: + + - To sort on a column and keep the top n records, use the + `top(n, columns=["_value"], tables=<-)` function instead of the `_sortLimit` + helper function. `top` uses `_sortLimit`. + + #### Related Guides + + - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) + operationId: GetQuerySuggestions + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + funcs: + - name: _fillEmpty + params: + createEmpty: bool + tables: stream + - name: _highestOrLowest + params: + _sortLimit: function + column: invalid + groupColumns: array + 'n': invalid + reducer: function + tables: stream + - name: _hourSelection + params: + location: object + start: int + stop: int + tables: stream + timeColumn: string + - name: _sortLimit + params: + columns: array + desc: bool + 'n': int + tables: stream + - name: _window + params: + createEmpty: bool + every: duration + location: object + offset: duration + period: duration + startColumn: string + stopColumn: string + tables: stream + timeColumn: string + - name: aggregateWindow + params: + column: invalid + createEmpty: bool + every: duration + fn: function + location: object + offset: duration + period: duration + tables: stream + timeDst: string + timeSrc: string + - name: bool + params: + v: invalid + - name: bottom + params: + columns: array + 'n': int + tables: stream + - name: buckets + params: + host: string + org: string + orgID: string + token: string + - name: bytes + params: + v: invalid + - name: cardinality + params: + bucket: string + bucketID: string + host: string + org: string + orgID: string + predicate: function + start: invalid + stop: invalid + token: string + - name: chandeMomentumOscillator + params: + columns: array + 'n': int + tables: stream + - name: columns + params: + column: string + tables: stream + - name: contains + params: + set: array + value: invalid + - name: count + params: + column: string + tables: stream + - name: cov + params: + 'on': array + pearsonr: bool + x: invalid + 'y': invalid + - name: covariance + params: + columns: array + pearsonr: bool + tables: stream + valueDst: string + - name: cumulativeSum + params: + columns: array + tables: stream + - name: derivative + params: + columns: array + initialZero: bool + nonNegative: bool + tables: stream + timeColumn: string + unit: duration + - name: die + params: + msg: string + - name: difference + params: + columns: array + initialZero: bool + keepFirst: bool + nonNegative: bool + tables: stream + - name: display + params: + v: invalid + - name: distinct + params: + column: string + tables: stream + - name: doubleEMA + params: + 'n': int + tables: stream + - name: drop + params: + columns: array + fn: function + tables: stream + - name: duplicate + params: + as: string + column: string + tables: stream + - name: duration + params: + v: invalid + - name: elapsed + params: + columnName: string + tables: stream + timeColumn: string + unit: duration + - name: exponentialMovingAverage + params: + 'n': int + tables: stream + - name: fill + params: + column: string + tables: stream + usePrevious: bool + value: invalid + - name: filter + params: + fn: function + onEmpty: string + tables: stream + - name: findColumn + params: + column: string + fn: function + tables: stream + - name: findRecord + params: + fn: function + idx: int + tables: stream + - name: first + params: + column: string + tables: stream + - name: float + params: + v: invalid + - name: from + params: + bucket: string + bucketID: string + host: string + org: string + orgID: string + token: string + - name: getColumn + params: + column: string + - name: getRecord + params: + idx: int + - name: group + params: + columns: array + mode: string + tables: stream + - name: highestAverage + params: + column: string + groupColumns: array + 'n': int + tables: stream + - name: highestCurrent + params: + column: string + groupColumns: array + 'n': int + tables: stream + - name: highestMax + params: + column: string + groupColumns: array + 'n': int + tables: stream + - name: histogram + params: + bins: array + column: string + countColumn: string + normalize: bool + tables: stream + upperBoundColumn: string + - name: histogramQuantile + params: + countColumn: string + minValue: float + quantile: float + tables: stream + upperBoundColumn: string + valueColumn: string + - name: holtWinters + params: + column: string + interval: duration + 'n': int + seasonality: int + tables: stream + timeColumn: string + withFit: bool + - name: hourSelection + params: + location: object + start: int + stop: int + tables: stream + timeColumn: string + - name: increase + params: + columns: array + tables: stream + - name: int + params: + v: invalid + - name: integral + params: + column: string + interpolate: string + tables: stream + timeColumn: string + unit: duration + - name: join + params: + method: string + 'on': array + tables: invalid + - name: kaufmansAMA + params: + column: string + 'n': int + tables: stream + - name: kaufmansER + params: + 'n': int + tables: stream + - name: keep + params: + columns: array + fn: function + tables: stream + - name: keyValues + params: + keyColumns: array + tables: stream + - name: keys + params: + column: string + tables: stream + - name: last + params: + column: string + tables: stream + - name: length + params: + arr: array + - name: limit + params: + 'n': int + offset: int + tables: stream + - name: linearBins + params: + count: int + infinity: bool + start: float + width: float + - name: logarithmicBins + params: + count: int + factor: float + infinity: bool + start: float + - name: lowestAverage + params: + column: string + groupColumns: array + 'n': int + tables: stream + - name: lowestCurrent + params: + column: string + groupColumns: array + 'n': int + tables: stream + - name: lowestMin + params: + column: string + groupColumns: array + 'n': int + tables: stream + - name: map + params: + fn: function + mergeKey: bool + tables: stream + - name: max + params: + column: string + tables: stream + - name: mean + params: + column: string + tables: stream + - name: median + params: + column: string + compression: float + method: string + tables: stream + - name: min + params: + column: string + tables: stream + - name: mode + params: + column: string + tables: stream + - name: movingAverage + params: + 'n': int + tables: stream + - name: now + params: {} + - name: pearsonr + params: + 'on': array + x: invalid + 'y': invalid + - name: pivot + params: + columnKey: array + rowKey: array + tables: stream + valueColumn: string + - name: quantile + params: + column: string + compression: float + method: string + q: float + tables: stream + - name: range + params: + start: invalid + stop: invalid + tables: stream + - name: reduce + params: + fn: function + identity: invalid + tables: stream + - name: relativeStrengthIndex + params: + columns: array + 'n': int + tables: stream + - name: rename + params: + columns: invalid + fn: function + tables: stream + - name: sample + params: + column: string + 'n': int + pos: int + tables: stream + - name: set + params: + key: string + tables: stream + value: string + - name: skew + params: + column: string + tables: stream + - name: sort + params: + columns: array + desc: bool + tables: stream + - name: spread + params: + column: string + tables: stream + - name: stateCount + params: + column: string + fn: function + tables: stream + - name: stateDuration + params: + column: string + fn: function + tables: stream + timeColumn: string + unit: duration + - name: stateTracking + params: + countColumn: string + durationColumn: string + durationUnit: duration + fn: function + tables: stream + timeColumn: string + - name: stddev + params: + column: string + mode: string + tables: stream + - name: string + params: + v: invalid + - name: sum + params: + column: string + tables: stream + - name: tableFind + params: + fn: function + tables: stream + - name: tail + params: + 'n': int + offset: int + tables: stream + - name: time + params: + v: invalid + - name: timeShift + params: + columns: array + duration: duration + tables: stream + - name: timeWeightedAvg + params: + tables: stream + unit: duration + - name: timedMovingAverage + params: + column: string + every: duration + period: duration + tables: stream + - name: to + params: + bucket: string + bucketID: string + fieldFn: function + host: string + measurementColumn: string + org: string + orgID: string + tables: stream + tagColumns: array + timeColumn: string + token: string + - name: toBool + params: + tables: stream + - name: toFloat + params: + tables: stream + - name: toInt + params: + tables: stream + - name: toString + params: + tables: stream + - name: toTime + params: + tables: stream + - name: toUInt + params: + tables: stream + - name: today + params: {} + - name: top + params: + columns: array + 'n': int + tables: stream + - name: tripleEMA + params: + 'n': int + tables: stream + - name: tripleExponentialDerivative + params: + 'n': int + tables: stream + - name: truncateTimeColumn + params: + tables: stream + timeColumn: invalid + unit: duration + - name: uint + params: + v: invalid + - name: union + params: + tables: array + - name: unique + params: + column: string + tables: stream + - name: wideTo + params: + bucket: string + bucketID: string + host: string + org: string + orgID: string + tables: stream + token: string + - name: window + params: + createEmpty: bool + every: duration + location: object + offset: duration + period: duration + startColumn: string + stopColumn: string + tables: stream + timeColumn: string + - name: yield + params: + name: string + tables: stream + schema: + $ref: '#/components/schemas/FluxSuggestions' + description: | + Success. + 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`. + summary: Invalid URL + value: | + Moved Permanently + schema: + properties: + body: + description: Response message with URL of requested resource. + readOnly: true + type: string + description: | + Moved Permanently. + InfluxData has moved the URL of the endpoint. + Use `/api/v2/query/suggestions` (without a trailing slash). + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error. + summary: List Flux query suggestions + tags: + - Query + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request GET "INFLUX_URL/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 + requested function. + + Use this endpoint to pass a branching suggestion (a Flux function name) and + retrieve the parameters of the requested function. + + #### Limitations + + - Use `/api/v2/query/suggestions/{name}` (without a trailing slash). + `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a + HTTP `301 Moved Permanently` status. + + - The function `name` must exist and must be spelled correctly. + + #### Related Guides + + - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) + operationId: GetQuerySuggestionsName + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + A [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name. + in: path + name: name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + name: sum + params: + column: string + tables: stream + schema: + $ref: '#/components/schemas/FluxSuggestion' + description: | + Success. + The response body contains the function name and parameters. + '500': + content: + application/json: + examples: + internalError: + description: | + The requested function doesn't exist. + summary: Invalid function + value: + code: internal error + message: An internal error has occurred + schema: + $ref: '#/components/schemas/Error' + description: | + Internal server error. + The value passed for _`name`_ may have been misspelled. + summary: Retrieve a query suggestion for a branching suggestion + tags: + - Query + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request GET "INFLUX_URL/api/v2/query/suggestions/sum/" \ + --header "Accept: application/json" \ + --header "Authorization: Token INFLUX_API_TOKEN" + /api/v2/resources: + get: + operationId: GetResources + parameters: + - $ref: '#/components/parameters/TraceSpan' + responses: + '200': + content: + application/json: + schema: + items: + type: string + type: array + description: All resources targets + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: List all known resources + tags: + - Resources + - System information endpoints + /api/v2/scripts: + get: + description: | + Lists [scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). + + #### Related guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: GetScripts + parameters: + - description: | + The offset for pagination. + The number of records to skip. + + For more information about pagination parameters, see [Pagination](/influxdb/cloud-iox/api/#tag/Pagination). + in: query + name: offset + required: false + schema: + minimum: 0 + type: integer + - description: | + The maximum number of scripts to return. Default is `100`. + in: query + name: limit + required: false + schema: + default: 100 + maximum: 500 + minimum: 0 + type: integer + - description: The script name. Lists scripts with the specified name. + in: query + name: name + required: false + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + scripts: + - createdAt: '2022-07-17T23:49:45.731237Z' + description: find the last point from Sample Bucket + id: 09afa3b220fe4000 + language: flux + name: getLastPointFromSampleBucket + orgID: bea7ea952287f70d + 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 + id: 09afa23ff13e4000 + language: flux + name: getLastPoint + orgID: bea7ea952287f70d + script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' + updatedAt: '2022-07-17T23:43:26.660308Z' + schema: + $ref: '#/components/schemas/Scripts' + description: | + Success. + The response body contains the list of scripts. + '400': + content: + application/json: + examples: + invalidSyntaxError: + summary: Query parameter contains invalid syntax. + value: + code: 3 + details: [] + 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': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error. + summary: List scripts + tags: + - Data I/O endpoints + - Invokable Scripts + x-codeSamples: + - label: 'cURL: retrieves the first 100 scripts.' + lang: Shell + source: | + curl --request GET "INFLUX_URL/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/) + and returns the script. + + #### Related guides + + - [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: + application/json: + schema: + $ref: '#/components/schemas/ScriptCreateRequest' + description: The script to create. + required: true + responses: + '201': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-07-17T23:43:26.660308Z' + description: getLastPoint finds the last point in a bucket + id: 09afa23ff13e4000 + language: flux + name: getLastPoint + orgID: bea7ea952287f70d + script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' + updatedAt: '2022-07-17T23:43:26.660308Z' + schema: + $ref: '#/components/schemas/Script' + description: | + Success. + The response body contains the script and its metadata. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '422': + content: + application/json: + examples: + uniquenessError: + description: | + A script with the same `name` exists. + value: + code: conflict + message: uniqueness violation + schema: + $ref: '#/components/schemas/Error' + description: | + Unprocessable entity. + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error. + summary: Create a script + tags: + - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "INFLUX_URL/api/v2/scripts" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "getLastPoint", + "description": "getLastPoint finds the last point in a bucket", + "orgID": "INFLUX_ORG_ID", + "script": "from(bucket: INFLUX_BUCKET) |> range(start: -7d) |> limit(n:1)", + "language": "flux" + }' + /api/v2/scripts/{scriptID}: + delete: + description: | + Deletes a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records. + + #### Limitations + + - You can delete only one script per request. + - If the script ID you provide doesn't exist for the organization, InfluxDB + responds with an HTTP `204` status code. + + #### Related Guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: DeleteScriptsID + parameters: + - description: | + A script ID. + Deletes the specified script. + in: path + name: scriptID + required: true + schema: + type: string + responses: + '204': + description: | + Success. + The script is queued for deletion. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/ServerError' + description: Unexpected error + summary: Delete a script + tags: + - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl -X 'DELETE' \ + "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header 'Accept: application/json' + get: + description: | + Retrieves a [script](/influxdb/cloud/api-guide/api-invokable-scripts/). + + #### Related Guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: GetScriptsID + parameters: + - description: | + A script ID. + Retrieves the specified script. + in: path + name: scriptID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-07-17T23:49:45.731237Z' + description: getLastPoint finds the last point in a bucket + id: 09afa3b220fe4000 + language: flux + name: getLastPoint + orgID: bea7ea952287f70d + script: 'from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)' + updatedAt: '2022-07-17T23:49:45.731237Z' + schema: + $ref: '#/components/schemas/Script' + description: Success. The response body contains the script. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested script was not found. + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/ServerError' + description: Internal server error. + summary: Retrieve a script + tags: + - Data I/O endpoints + - Invokable Scripts + patch: + description: | + Updates an invokable script. + + Use this endpoint to modify values for script properties (`description` and `script`). + + To update a script, pass an object that contains the updated key-value pairs. + + #### Limitations + + - If you send an empty request body, the script will neither update nor + store an empty script, but InfluxDB will respond with an HTTP `200` status + code. + + #### Related Guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: PatchScriptsID + parameters: + - description: | + A script ID. + Updates the specified script. + in: path + name: scriptID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScriptUpdateRequest' + description: | + An object that contains the updated script properties to apply. + required: true + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + createdAt: '2022-07-17T23:49:45.731237Z' + description: get last point from new bucket + id: 09afa3b220fe4000 + language: flux + name: getLastPoint + orgID: bea7ea952287f70d + script: 'from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)' + updatedAt: '2022-07-19T22:27:23.185436Z' + schema: + $ref: '#/components/schemas/Script' + description: Success. The response body contains the updated script. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested script wasn't found. + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/ServerError' + description: Internal server error + summary: Update a script + tags: + - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl -X 'PATCH' \ + "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header "Accept: application/json" + --header "Content-Type: application/json" + --data '{ + "description": "get last point from new bucket", + "script": "from(bucket: updatedBucket) |> range(start: -7d) |> limit(n:1)", "language": "flux" + }' + /api/v2/scripts/{scriptID}/invoke: + post: + 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 the _`mybucket`_ parameter: + + ```json + { + "params": { + "mybucket": "air_sensor" + } + } + ``` + + #### Related guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: PostScriptsIDInvoke + parameters: + - description: | + A script ID. + Runs the specified script. + in: path + name: scriptID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ScriptInvocationParams' + responses: + '200': + content: + text/csv: + examples: + successResponse: + 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' + description: | + Success. + The response body contains the result of the script execution. + '400': + content: + application/json: + examples: + invalidParameters: + summary: The parameters passed to the script are invalid. + value: + code: invalid + message: invalid parameters provided + schema: + $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: | + The reason for the error. + schema: + example: invalid + type: string + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + bucketNotFound: + description: InfluxDB can't find the requested bucket. + summary: | + Bucket not found + value: + code: not found + message: 'failed to initialize execute state: could not find bucket "test-bucket"' + scriptNotFound: + description: InfluxDB can't find the requested script. + summary: | + Script not found + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: not found + type: string + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error. + summary: Invoke a script + tags: + - Data I/O endpoints + - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "INFLUX_URL/api/v2/scripts/SCRIPT_ID/invoke" \ + --header "Authorization: Token INFLUX_TOKEN" \ + --header 'Accept: application/csv' \ + --header 'Content-Type: application/json' \ + --data '{ + "params": { + "mybucket": "air_sensor" + } + }' + /api/v2/scripts/{scriptID}/params: + get: + description: | + Analyzes a script and determines required parameters. + Find all `params` keys referenced in a script and return a list + of keys. If it is possible to determine the type of the value + from the context then the type is also returned -- for example: + + The following sample script contains a _`mybucket`_ parameter : + + ```json + "script": "from(bucket: params.mybucket) + |> range(start: -7d) + |> limit(n:1)" + ``` + + Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params` + returns the following: + + ```json + { + "params": { + "mybucket": "string" + } + } + ``` + + The type name returned for a parameter will be one of: + + - `any` + - `bool` + - `duration` + - `float` + - `int` + - `string` + - `time` + - `uint` + + The type name `any` is used when the type of a parameter cannot + be determined from the context, or the type is determined to + be a structured type such as an array or record. + + #### Related guides + + - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) + operationId: GetScriptsIDParams + parameters: + - description: | + A script ID. + The script to analyze for params. + in: path + name: scriptID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + successResponse: + value: + params: + mybucket: string + schema: + $ref: '#/components/schemas/Params' + description: | + Success. + The response body contains the parameters found, along with their types. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + scriptNotFound: + description: InfluxDB can't find the requested script. + summary: | + Script not found + value: + code: not found + message: script "09afa3b220fe400" not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + headers: + X-Platform-Error-Code: + description: | + The reason for the error. + schema: + example: not found + type: string + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error. + summary: Find script parameters. + tags: + - Invokable Scripts + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \ + --header "Authorization: Token INFLUX_TOKEN" + /api/v2/setup: {} + /api/v2/setup/user: {} + /api/v2/signin: {} + /api/v2/signout: {} + /api/v2/stacks: + get: + description: | + Lists installed InfluxDB stacks. + + To limit stacks in the response, pass query parameters in your request. + If no query parameters are passed, InfluxDB returns all installed stacks + for the organization. + + #### Related guides + + - [View InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/). + operationId: ListStacks + parameters: + - description: | + An organization ID. + Only returns stacks owned by the specified [organization](/influxdb/cloud/reference/glossary/#organization). + + #### InfluxDB Cloud + + - Doesn't require this parameter; + InfluxDB only returns resources allowed by the API token. + in: query + name: orgID + required: true + schema: + type: string + - description: | + A stack name. + Finds stack `events` with this name and returns the stacks. + + Repeatable. + To filter for more than one stack name, + repeat this parameter with each name--for example: + + - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` + examples: + findStackByName: + summary: Find stacks with the event name + value: project-stack-0 + in: query + name: name + schema: + type: string + - description: | + A stack ID. + Only returns the specified stack. + + Repeatable. + To filter for more than one stack ID, + repeat this parameter with each ID--for example: + + - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` + examples: + findStackByID: + summary: Find a stack with the ID + value: 09bd87cd33be3000 + in: query + name: stackID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + properties: + stacks: + items: + $ref: '#/components/schemas/Stack' + type: array + type: object + description: Success. The response body contains the list of stacks. + '400': + content: + application/json: + examples: + orgIdMissing: + summary: The orgID query parameter is missing + value: + code: invalid + message: 'organization id[""] is invalid: id must have a length of 16 bytes' + orgProvidedNotFound: + summary: The org or orgID passed doesn't own the token passed in the header + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB OSS + + - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List installed stacks + tags: + - Templates + post: + description: | + Creates or initializes a stack. + + Use this endpoint to _manually_ initialize a new stack with the following + optional information: + + - Stack name + - Stack description + - URLs for template manifest files + + To automatically create a stack when applying templates, + use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). + + #### Required permissions + + - `write` permission for the organization + + #### Related guides + + - [Initialize an InfluxDB stack](/influxdb/cloud/influxdb-templates/stacks/init/). + - [Use InfluxDB templates](/influxdb/cloud/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). + operationId: CreateStack + requestBody: + content: + application/json: + schema: + properties: + description: + type: string + name: + type: string + orgID: + type: string + urls: + items: + type: string + type: array + title: PostStackRequest + type: object + description: The stack to create. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Success. Returns the newly created stack. + '401': + $ref: '#/components/responses/AuthorizationError' + '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: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a stack + tags: + - Templates + /api/v2/stacks/{stack_id}: + delete: + operationId: DeleteStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + - description: The identifier of the organization. + in: query + name: orgID + required: true + schema: + type: string + responses: + '204': + description: The stack and its associated resources were deleted. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a stack and associated resources + tags: + - Templates + get: + operationId: ReadStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a stack + tags: + - Templates + patch: + operationId: UpdateStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + properties: + additionalResources: + items: + properties: + kind: + type: string + resourceID: + type: string + templateMetaName: + type: string + required: + - kind + - resourceID + type: object + type: array + description: + nullable: true + type: string + name: + nullable: true + type: string + templateURLs: + items: + type: string + nullable: true + type: array + title: PatchStackRequest + type: object + description: The stack to update. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the updated stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a stack + tags: + - Templates + /api/v2/stacks/{stack_id}/uninstall: + post: + operationId: UninstallStack + parameters: + - description: The identifier of the stack. + in: path + name: stack_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Stack' + description: Returns the uninstalled stack. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Uninstall a stack + tags: + - Templates + /api/v2/tasks: + get: + 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`. + operationId: GetTasks + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + 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: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Only returns tasks created after the specified task. + in: query + name: after + schema: + type: string + - description: | + A [user](/influxdb/cloud/reference/glossary/#user) ID. + Only returns tasks owned by the specified user. + in: query + name: user + schema: + type: string + - description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) name. + Only returns tasks owned by the specified organization. + in: query + name: org + schema: + type: string + - description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) ID. + Only returns tasks owned by the specified organization. + in: query + name: orgID + schema: + type: string + - 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: + enum: + - active + - inactive + type: string + - 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. + examples: + all: + summary: Return all tasks, without pagination. + value: '-1' + minPaginated: + summary: Return a maximum of 50 tasks. + value: '50' + in: query + name: limit + schema: + default: 100 + maximum: 500 + minimum: -1 + type: integer + - description: The number of records to skip. + in: query + name: offset + required: false + schema: + default: 0 + minimum: 0 + type: integer + - description: | + The sort field. Only `name` is supported. + Specifies the field used to sort records in the list. + in: query + name: sortBy + required: false + schema: + enum: + - name + type: string + - 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 + schema: + default: '' + enum: + - basic + - system + type: string + - description: | + A [script](#tag/Invokable-Scripts) ID. + Only returns tasks that use the specified invokable script. + in: query + name: scriptID + schema: + type: string + responses: + '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: | + Success. + The response body contains the list of tasks. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: List all tasks + tags: + - Data I/O endpoints + - Tasks + x-codeSamples: + - label: 'cURL: all tasks, basic output' + lang: Shell + source: | + curl INFLUX_URL/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/reference/glossary/#task) and returns the task. + + Use this endpoint to create a scheduled task that runs a Flux script. + + #### InfluxDB Cloud + + - You can use either `flux` or `scriptID` to provide the task script. + + - `flux`: a string of "raw" Flux that contains task options and the script--for example: + + ```json + { + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + from(bucket: \"telegraf\") + |> range(start: -1h) + |> filter(fn: (r) => (r._measurement == \"cpu\")) + |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + |> aggregateWindow(every: 1h, fn: max) + |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + "status": "active", + "description": "This task downsamples CPU data every hour" + } + ``` + + - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) + for the task to run. + To pass task options when using `scriptID`, pass the options as + properties in the request body--for example: + + ```json + { + "name": "CPU Total 1 Hour New", + "description": "This task downsamples CPU data every hour", + "every": "1h", + "scriptID": "SCRIPT_ID", + "scriptParameters": + { + "rangeStart": "-1h", + "bucket": "telegraf", + "filterField": "cpu-total" + } + } + ``` + + #### Limitations: + + - You can't use `flux` and `scriptID` for the same task. + + #### Related guides + + - [Get started with tasks](/influxdb/cloud/process-data/get-started/) + - [Create a task](/influxdb/cloud/process-data/manage-tasks/create-task/) + - [Common tasks](/influxdb/cloud/process-data/common-tasks/) + - [Task configuration options](/influxdb/cloud/process-data/task-options/) + operationId: PostTasks + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskCreateRequest' + description: The task to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Success. The response body contains a `tasks` list with the new task. + '400': + content: + application/json: + examples: + fluxAndScriptError: + summary: The request body can't contain both flux and scriptID + value: + code: invalid + message: 'failed to decode request: can not provide both scriptID and flux' + missingFluxError: + summary: The request body requires either a flux parameter or scriptID parameter + value: + code: invalid + message: 'failed to decode request: flux required' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + #### InfluxDB Cloud + + - Returns this error if the task doesn't contain one of _`flux`_ or _`scriptID`_. + - Returns this error if the task contains _`flux`_ _and_ _`scriptID`_. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a task + tags: + - Data I/O endpoints + - Tasks + x-codeSamples: + - label: 'cURL: create a Flux script task' + lang: Shell + source: | + curl INFLUX_URL/api/v2/tasks \ + --header "Content-type: application/json" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --data-binary @- << EOF + { + "orgID": "INFLUX_ORG_ID", + "description": "IoT Center 30d environment average.", + "flux": "option task = {name: \"iot-center-task-1\", every: 30m}\ + from(bucket: \"iot_center\")\ + |> range(start: -30d)\ + |> filter(fn: (r) => r._measurement == \"environment\")\ + |> aggregateWindow(every: 1h, fn: mean)" + } + EOF + - label: 'cURL: create a Flux script reference task' + lang: Shell + source: | + curl INFLUX_URL/api/v2/tasks \ + --header "Content-type: application/json" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --data-binary @- << EOF + { + "orgID": "INFLUX_ORG_ID", + "description": "IoT Center 30d environment average.", + "scriptID": "085138a111448000", + "scriptParameters": + { + "rangeStart": "-30d", + "bucket": "air_sensor", + "filterField": "temperature", + "groupColumn": "_time" + } + } + EOF + /api/v2/tasks/{taskID}: + delete: + description: | + Deletes 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. + + If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID). + operationId: DeleteTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: A [task](/influxdb/cloud/reference/glossary/#task) ID. Specifies the task to delete. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Success. The task and task runs are deleted. Scheduled runs are canceled. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Delete a task + tags: + - Tasks + get: + description: | + Retrieves a [task](/influxdb/cloud/reference/glossary/#task). + operationId: GetTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to retrieve. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Success. The response body contains the task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Retrieve a task + tags: + - Data I/O endpoints + - Tasks + patch: + 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. + + To update a task, pass an object that contains the updated key-value pairs. + To activate or inactivate a task, set the `status` property. + _`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task. + + #### InfluxDB Cloud + + - Use either `flux` or `scriptID` to provide the task script. + + - `flux`: a string of "raw" Flux that contains task options and the script--for example: + + ```json + { + "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\ + from(bucket: \"telegraf\") + |> range(start: -1h) + |> filter(fn: (r) => (r._measurement == \"cpu\")) + |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\")) + |> filter(fn: (r) => (r.cpu == \"cpu-total\")) + |> aggregateWindow(every: 1h, fn: max) + |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")", + "status": "active", + "description": "This task downsamples CPU data every hour" + } + ``` + + - `scriptID`: the ID of an [invokable script](#tag/Invokable-Scripts) + for the task to run. + To pass task options when using `scriptID`, pass the options as + properties in the request body--for example: + + ```json + { + "name": "CPU Total 1 Hour New", + "description": "This task downsamples CPU data every hour", + "every": "1h", + "scriptID": "SCRIPT_ID", + "scriptParameters": + { + "rangeStart": "-1h", + "bucket": "telegraf", + "filterField": "cpu-total" + } + } + ``` + + #### Limitations: + + - You can't use `flux` and `scriptID` for the same task. + operationId: PatchTasksID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to update. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TaskUpdateRequest' + description: An task update to apply. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + description: Success. The response body contains the updated task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Update a task + tags: + - Tasks + /api/v2/tasks/{taskID}/labels: + get: + description: | + Retrieves a list of all labels for a task. + + Labels may be used for grouping and filtering tasks. + operationId: GetTasksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to retrieve labels for. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: Success. The response body contains a list of all labels for the task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: List labels for a task + tags: + - Tasks + post: + description: | + Adds a label to a task. + + Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI. + operationId: PostTasksIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to label. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: An object that contains a _`labelID`_ to add to the task. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: Success. The response body contains a list of all labels for the task. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Add a label to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/labels/{labelID}: + delete: + description: | + Deletes a label from a task. + operationId: DeleteTasksIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to delete the label from. + in: path + name: taskID + required: true + schema: + type: string + - description: The ID of the label to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Success. The label is deleted. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Delete a label from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/logs: + get: + description: | + Retrieves a list of all logs for a [task](/influxdb/cloud/reference/glossary/#task). + + When an InfluxDB task runs, a โ€œrunโ€ record is created in the taskโ€™s history. + Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt. + + Use this endpoint to retrieve only the log events for a task, + without additional task metadata. + operationId: GetTasksIDLogs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + taskFailure: + summary: Events for a failed task run. + value: + events: + - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' + runID: 09a946fc3167d000 + time: '2022-07-13T07:06:54.198167Z' + - message: Completed(failed) + runID: 09a946fc3167d000 + time: '2022-07-13T07:07:13.104037Z' + - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' + runID: 09a946fc3167d000 + time: '2022-07-13T08:24:37.115323Z' + taskSuccess: + summary: Events for 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)"' + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' + schema: + $ref: '#/components/schemas/Logs' + description: | + Success. The response body contains an `events` list with logs for the task. + Each log event `message` contains detail about the event. + If a task run fails, InfluxDB logs an event with the reason for the failure. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Retrieve all logs for a task + tags: + - Tasks + /api/v2/tasks/{taskID}/members: + get: + deprecated: true + description: | + **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + Lists all users that have the `member` role for the specified [task](/influxdb/cloud/reference/glossary/#task). + operationId: GetTasksIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: | + Success. The response body contains a list of `users` that have + the `member` role for a task. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all task members + tags: + - Tasks + post: + deprecated: true + description: | + **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + Adds a user to members of a task and returns the member. + operationId: PostTasksIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: A user to add as a member of the task. + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Created. The user is added to task members. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a task + tags: + - Tasks + /api/v2/tasks/{taskID}/members/{userID}: + delete: + deprecated: true + description: | + **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + Removes a member from a [task](/influxdb/cloud/reference/glossary/#task). + operationId: DeleteTasksIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/owners: + get: + deprecated: true + description: | + **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + Retrieves all users that have owner permission for a task. + operationId: GetTasksIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to retrieve owners for. + in: path + name: taskID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: | + Success. + The response contains a list of `users` that have the `owner` role for the task. + + If the task has no owners, the response contains an empty `users` array. + '401': + $ref: '#/components/responses/AuthorizationError' + '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: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a task + tags: + - Tasks + post: + deprecated: true + description: | + **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + + Assigns a task `owner` role to a user. + + Use this endpoint to create a _resource owner_ for the task. + A _resource owner_ is a user with `role: owner` for a specific resource. + operationId: PostTasksIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: A user to add as an owner of the task. + required: true + responses: + '201': + content: + application/json: + examples: + createdOwner: + summary: User has the owner role for the resource + value: + id: 0772396d1f411000 + links: + logs: /api/v2/users/0772396d1f411000/logs + self: /api/v2/users/0772396d1f411000 + name: USER_NAME + role: owner + status: active + schema: + $ref: '#/components/schemas/ResourceOwner' + description: | + Created. The task `owner` role is assigned to the user. + The response body contains the resource owner with + role and user detail. + '401': + $ref: '#/components/responses/AuthorizationError' + '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: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner for a task + tags: + - Tasks + /api/v2/tasks/{taskID}/owners/{userID}: + delete: + deprecated: true + description: | + **Deprecated**: Tasks don't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. + operationId: DeleteTasksIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The task ID. + in: path + name: taskID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a task + tags: + - Tasks + /api/v2/tasks/{taskID}/runs: + get: + 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`. + operationId: GetTasksIDRuns + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The ID of the task to get runs for. + Only returns runs for this task. + in: path + name: taskID + required: true + schema: + type: string + - description: A task run ID. Only returns runs created after this run. + in: query + name: after + schema: + type: string + - description: | + Limits the number of task runs returned. Default is `100`. + in: query + name: limit + schema: + default: 100 + maximum: 500 + minimum: 1 + type: integer + - 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)). + Only returns runs scheduled before this time. + in: query + name: beforeTime + schema: + format: date-time + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Runs' + description: Success. The response body contains the list of task runs. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: List runs for a task + tags: + - Tasks + post: + description: | + Schedules a task run to start immediately, ignoring scheduled runs. + + Use this endpoint to manually start a task run. + Scheduled runs will continue to run as scheduled. + This may result in concurrently running tasks. + + To _retry_ a previous run (and avoid creating a new run), + use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). + operationId: PostTasksIDRuns + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: path + name: taskID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RunManually' + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + description: Success. The run is scheduled to start. + '401': + $ref: '#/components/responses/AuthorizationError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Start a task run, overriding the schedule + tags: + - Data I/O endpoints + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}: + delete: + description: | + Cancels a running [task](/influxdb/cloud/reference/glossary/#task). + + Use this endpoint with InfluxDB OSS to cancel a running task. + + #### InfluxDB Cloud + + - Doesn't support this operation. + operationId: DeleteTasksIDRunsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to cancel. + in: path + name: taskID + required: true + schema: + type: string + - description: The ID of the task run to cancel. + in: path + name: runID + required: true + schema: + type: string + responses: + '204': + description: | + Success. The `DELETE` is accepted and the run will be cancelled. + + #### InfluxDB Cloud + + - Doesn't support this operation. + - Doesn't return this status. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '405': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: | + Method not allowed. + + #### InfluxDB Cloud + + - Always returns this error; doesn't support cancelling tasks. + + #### InfluxDB OSS + + - Doesn't return this error. + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Cancel a running task + tags: + - Tasks + get: + description: | + Retrieves a specific run for a [task](/influxdb/cloud/reference/glossary/#task). + + Use this endpoint to retrieve detail and logs for a specific task run. + operationId: GetTasksIDRunsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to retrieve runs for. + in: path + name: taskID + required: true + schema: + type: string + - description: The ID of the run to retrieve. + in: path + name: runID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + runSuccess: + summary: A successful task run. + value: + finishedAt: '2022-07-18T14:46:07.308254Z' + id: 09b070dadaa7d000 + links: + logs: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs + retry: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry + self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 + task: /api/v2/tasks/0996e56b2f378000 + log: + - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' + requestedAt: '2022-07-18T14:46:06Z' + scheduledFor: '2022-07-18T14:46:06Z' + startedAt: '2022-07-18T14:46:07.16222Z' + status: success + taskID: 0996e56b2f378000 + schema: + $ref: '#/components/schemas/Run' + description: Success. The response body contains the task run. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Retrieve a run for a task. + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}/logs: + get: + description: | + Retrieves all logs for a task run. + A log is a list of run events with `runID`, `time`, and `message` properties. + + Use this endpoint to help analyze task performance and troubleshoot failed task runs. + operationId: GetTasksIDRunsIDLogs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the task to get logs for. + in: path + name: taskID + required: true + schema: + type: string + - description: The ID of the run to get logs for. + in: path + name: runID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + examples: + taskFailure: + summary: Events for a failed task. + value: + events: + - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' + runID: 09a946fc3167d000 + time: '2022-07-13T07:06:54.198167Z' + - message: Completed(failed) + runID: 09a946fc3167d000 + time: '2022-07-13T07:07:13.104037Z' + - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' + runID: 09a946fc3167d000 + time: '2022-07-13T08:24:37.115323Z' + taskSuccess: + summary: Events for 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)"' + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.101231Z' + - message: Completed(success) + runID: 09b070dadaa7d000 + time: '2022-07-18T14:46:07.242859Z' + schema: + $ref: '#/components/schemas/Logs' + description: | + 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. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Retrieve all logs for a run + tags: + - Tasks + /api/v2/tasks/{taskID}/runs/{runID}/retry: + post: + 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: | + A [task](/influxdb/cloud/reference/glossary/#task) ID. + Specifies the task to retry. + in: path + name: taskID + required: true + schema: + type: string + - 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 + schema: + type: string + requestBody: + content: + application/json; charset=utf-8: + schema: + type: object + responses: + '200': + content: + application/json: + examples: + retryTaskRun: + summary: A task run scheduled to retry + value: + id: 09d60ffe08738000 + links: + logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs + retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry + self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 + task: /api/v2/tasks/09a776832f381000 + requestedAt: '2022-08-16T20:05:11.84145Z' + scheduledFor: '2022-08-15T00:00:00Z' + status: scheduled + taskID: 09a776832f381000 + schema: + $ref: '#/components/schemas/Run' + description: Success. The response body contains the queued run. + '400': + content: + application/json: + examples: + inactiveTask: + summary: Can't retry an inactive task + value: + code: invalid + message: 'failed to retry run: inactive task' + schema: + $ref: '#/components/schemas/Error' + description: | + Bad request. + The response body contains detail about the error. + + InfluxDB may return this error for the following reasons: + + - The task has `status: inactive`. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' + default: + $ref: '#/components/responses/GeneralServerError' + summary: Retry a task run + tags: + - Tasks + /api/v2/telegraf/plugins: {} + /api/v2/telegrafs: + get: + operationId: GetTelegrafs + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The organization ID the Telegraf config belongs to. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegrafs' + description: A list of Telegraf configurations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all Telegraf configurations + tags: + - Telegrafs + post: + operationId: PostTelegrafs + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafPluginRequest' + description: Telegraf configuration to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + description: Telegraf configuration created + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Create a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}: + delete: + operationId: DeleteTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a Telegraf configuration + tags: + - Telegrafs + get: + operationId: GetTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + - in: header + name: Accept + required: false + schema: + default: application/toml + enum: + - application/toml + - application/json + - application/octet-stream + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + application/octet-stream: + example: |- + [agent] + interval = "10s" + schema: + type: string + application/toml: + example: |- + [agent] + interval = "10s" + schema: + type: string + description: Telegraf configuration details + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Retrieve a Telegraf configuration + tags: + - Telegrafs + put: + operationId: PutTelegrafsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TelegrafPluginRequest' + description: Telegraf configuration update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Telegraf' + description: An updated Telegraf configurations + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Update a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/labels: + get: + operationId: GetTelegrafsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a Telegraf config + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The label added to the Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/labels/{labelID}: + delete: + operationId: DeleteTelegrafsIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + - description: The label ID. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Telegraf config not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/members: + get: + operationId: GetTelegrafsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMembers' + description: A list of Telegraf config members + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all users with member privileges for a Telegraf config + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDMembers + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as member + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceMember' + description: Member added to Telegraf config + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a member to a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/members/{userID}: + delete: + operationId: DeleteTelegrafsIDMembersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the member to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Member removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove a member from a Telegraf config + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/owners: + get: + operationId: GetTelegrafsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwners' + description: Returns Telegraf configuration owners as a ResourceOwners list + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all owners of a Telegraf configuration + tags: + - Telegrafs + post: + operationId: PostTelegrafsIDOwners + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The Telegraf configuration ID. + in: path + name: telegrafID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AddResourceMemberRequestBody' + description: User to add as owner + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceOwner' + description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add an owner to a Telegraf configuration + tags: + - Telegrafs + /api/v2/telegrafs/{telegrafID}/owners/{userID}: + delete: + operationId: DeleteTelegrafsIDOwnersID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The ID of the owner to remove. + in: path + name: userID + required: true + schema: + type: string + - description: The Telegraf config ID. + in: path + name: telegrafID + required: true + schema: + type: string + responses: + '204': + description: Owner removed + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Remove an owner from a Telegraf config + tags: + - Telegrafs + /api/v2/templates/apply: + post: + description: | + Applies a template to + 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. + 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. + To provide custom values for environment references, pass the _`envRefs`_ + property in the request body. + For more information and examples, see how to + [define environment references](/influxdb/cloud/influxdb-templates/use/#define-environment-references). + + - Some templates may contain queries that use + [secrets](/influxdb/cloud/security/secrets/). + To provide custom secret values, pass the _`secrets`_ property + in the request body. + Don't expose secret values in templates. + For more information, see [how to pass secrets when installing a template](/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template). + + #### Required permissions + + - `write` permissions for resource types in the template. + + #### Rate limits (with InfluxDB Cloud) + + - Adjustable service quotas apply. + For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). + + #### Related guides + + - [Use templates](/influxdb/cloud/influxdb-templates/use/) + - [Stacks](/influxdb/cloud/influxdb-templates/stacks/) + operationId: ApplyTemplate + requestBody: + content: + application/json: + examples: + skipKindAction: + summary: Skip all bucket and task resources in the provided templates + value: + actions: + - action: skipKind + properties: + kind: Bucket + - action: skipKind + properties: + kind: Task + orgID: INFLUX_ORG_ID + templates: + - contents: + - '[object Object]': null + skipResourceAction: + summary: Skip specific resources in the provided templates + value: + actions: + - action: skipResource + properties: + kind: Label + resourceTemplateName: foo-001 + - action: skipResource + properties: + kind: Bucket + resourceTemplateName: bar-020 + - action: skipResource + properties: + kind: Bucket + resourceTemplateName: baz-500 + orgID: INFLUX_ORG_ID + templates: + - contents: + - apiVersion: influxdata.com/v2alpha1 + kind: Bucket + metadata: + name: baz-500 + templateObjectEnvRefs: + summary: envRefs for template objects + value: + envRefs: + docker-bucket: MY_DOCKER_BUCKET + docker-spec-1: MY_DOCKER_SPEC + linux-cpu-label: MY_CPU_LABEL + orgID: INFLUX_ORG_ID + templates: + - contents: + - apiVersion: influxdata.com/v2alpha1 + kind: Label + metadata: + name: + envRef: + key: linux-cpu-label + spec: + color: '#326BBA' + name: inputs.cpu + - contents: + - apiVersion: influxdata.com/v2alpha1 + kind: Bucket + metadata: + name: + envRef: + key: docker-bucket + schema: + $ref: '#/components/schemas/TemplateApply' + application/x-jsonnet: + schema: + $ref: '#/components/schemas/TemplateApply' + text/yml: + schema: + $ref: '#/components/schemas/TemplateApply' + description: | + Parameters for applying templates. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateSummary' + description: | + Success. + The template dry run succeeded. + The response body contains a resource diff of changes that the + template would have made if installed. + No resources were created or updated. + The diff and summary won't contain IDs for resources + that didn't exist at the time of the dry run. + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/TemplateSummary' + description: | + Success. + The template applied successfully. + The response body contains the stack ID, a diff, and a summary. + The diff compares the initial state to the state after the template installation. + The summary contains newly created resources. + '422': + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/TemplateSummary' + - properties: + code: + type: string + message: + type: string + required: + - message + - code + type: object + description: | + Unprocessable entity. + + + The error may indicate one of the following problems: + + - The template failed validation. + - You passed a parameter combination that InfluxDB doesn't support. + '500': + content: + application/json: + examples: + createExceedsQuota: + summary: 'InfluxDB Cloud: Creating resource would exceed quota.' + value: + code: internal error + message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\"" + schema: + $ref: '#/components/schemas/Error' + description: | + Internal server error. + + #### InfluxDB Cloud + + - Returns this error if creating one of the template + resources (bucket, dashboard, task, user) exceeds your planโ€™s + adjustable service quotas. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Apply or dry-run a template + tags: + - Templates + x-codeSamples: + - label: 'cURL: Dry run with a remote template' + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/templates/apply" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --data @- << EOF + { + "dryRun": true, + "orgID": "INFLUX_ORG_ID", + "remotes": [ + { + "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml" + } + ] + } + EOF + - label: 'cURL: Apply with secret values' + lang: Shell + source: | + curl "http://localhost:8086/api/v2/templates/apply" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --data @- << EOF | jq . + { + "orgID": "INFLUX_ORG_ID", + "secrets": { + "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL" + }, + "remotes": [ + { + "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml" + } + ] + } + EOF + - label: 'cURL: Apply template objects with environment references' + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/templates/apply" \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --data @- << EOF + { "orgID": "INFLUX_ORG_ID", + "envRefs": { + "linux-cpu-label": "MY_CPU_LABEL", + "docker-bucket": "MY_DOCKER_BUCKET", + "docker-spec-1": "MY_DOCKER_SPEC" + }, + "templates": [ + { "contents": [{ + "apiVersion": "influxdata.com/v2alpha1", + "kind": "Label", + "metadata": { + "name": { + "envRef": { + "key": "linux-cpu-label" + } + } + }, + "spec": { + "color": "#326BBA", + "name": "inputs.cpu" + } + }] + }, + "templates": [ + { "contents": [{ + "apiVersion": "influxdata.com/v2alpha1", + "kind": "Label", + "metadata": { + "name": { + "envRef": { + "key": "linux-cpu-label" + } + } + }, + "spec": { + "color": "#326BBA", + "name": "inputs.cpu" + } + }] + }, + { "contents": [{ + "apiVersion": "influxdata.com/v2alpha1", + "kind": "Bucket", + "metadata": { + "name": { + "envRef": { + "key": "docker-bucket" + } + } + } + }] + } + ] + } + EOF + /api/v2/templates/export: + post: + operationId: ExportTemplate + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/TemplateExportByID' + - $ref: '#/components/schemas/TemplateExportByName' + description: Export resources as an InfluxDB template. + required: false + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Template' + application/x-yaml: + schema: + $ref: '#/components/schemas/Template' + description: The template was created successfully. Returns the newly created template. + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Export a new template + tags: + - Templates + /api/v2/users: {} + /api/v2/users/{userID}: {} + /api/v2/users/{userID}/password: {} + /api/v2/variables: + get: + operationId: GetVariables + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The name of the organization. + in: query + name: org + schema: + type: string + - description: The organization ID. + in: query + name: orgID + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variables' + description: A list of variables for an organization. + '400': + $ref: '#/components/responses/GeneralServerError' + description: Invalid request + default: + $ref: '#/components/responses/GeneralServerError' + description: Internal server error + summary: List all variables + tags: + - Variables + post: + operationId: PostVariables + parameters: + - $ref: '#/components/parameters/TraceSpan' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable to create + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable created + default: + $ref: '#/components/responses/GeneralServerError' + description: Internal server error + summary: Create a variable + tags: + - Variables + /api/v2/variables/{variableID}: + delete: + operationId: DeleteVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '204': + description: Variable deleted + default: + $ref: '#/components/responses/GeneralServerError' + description: Internal server error + summary: Delete a variable + tags: + - Variables + get: + operationId: GetVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable found + '404': + $ref: '#/components/responses/GeneralServerError' + description: Variable not found + default: + $ref: '#/components/responses/GeneralServerError' + description: Internal server error + summary: Retrieve a variable + tags: + - Variables + patch: + operationId: PatchVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable update to apply + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable updated + default: + $ref: '#/components/responses/GeneralServerError' + description: Internal server error + summary: Update a variable + tags: + - Variables + put: + operationId: PutVariablesID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable to replace + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Variable' + description: Variable updated + default: + $ref: '#/components/responses/GeneralServerError' + description: Internal server error + summary: Replace a variable + tags: + - Variables + /api/v2/variables/{variableID}/labels: + get: + operationId: GetVariablesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelsResponse' + description: A list of all labels for a variable + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: List all labels for a variable + tags: + - Variables + post: + operationId: PostVariablesIDLabels + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LabelMapping' + description: Label to add + required: true + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/LabelResponse' + description: The newly added label + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Add a label to a variable + tags: + - Variables + /api/v2/variables/{variableID}/labels/{labelID}: + delete: + operationId: DeleteVariablesIDLabelsID + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The variable ID. + in: path + name: variableID + required: true + schema: + type: string + - description: The label ID to delete. + in: path + name: labelID + required: true + schema: + type: string + responses: + '204': + description: Delete has been accepted + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Variable not found + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error + summary: Delete a label from a variable + tags: + - Variables + /api/v2/write: + post: + description: | + Writes data to a bucket. + + Use this endpoint to send data in [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) format to InfluxDB. + + #### InfluxDB Cloud + + - Does the following when you send a write request: + + 1. Validates the request and queues the write. + 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. + 3. Handles the delete asynchronously and reaches eventual consistency. + + To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, + wait for a success response (HTTP `2xx` status code) before you send the next request. + + Because writes and deletes are asynchronous, your change might not yet be readable + when you receive the response. + + #### InfluxDB OSS + + - Validates the request and handles the write synchronously. + - If all points were written successfully, responds with HTTP `2xx` status code; + otherwise, returns the first line that failed. + + #### Required permissions + + - `write-buckets` or `write-bucket BUCKET_ID`. + + *`BUCKET_ID`* is the ID of the destination bucket. + + #### Rate limits (with InfluxDB Cloud) + + `write` rate limits apply. + For more information, see [limits and adjustable quotas](/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/) + operationId: PostWrite + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: | + The compression applied to the line protocol in the request payload. + To send a GZIP payload, pass `Content-Encoding: gzip` header. + in: header + name: Content-Encoding + schema: + default: identity + description: | + Content coding. + Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. + enum: + - gzip + - identity + type: string + - description: | + The format of the data in the request body. + 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. + enum: + - text/plain + - text/plain; charset=utf-8 + type: string + - description: | + The size of the entity-body, in bytes, sent to InfluxDB. + If the length is greater than the `max body` configuration option, + the server responds with status code `413`. + in: header + name: Content-Length + schema: + description: The length in decimal number of octets. + type: integer + - description: | + The content type that the client can understand. + Writes only return a response body if they fail--for example, + due to a formatting problem or quota limit. + + #### InfluxDB Cloud + + - Returns only `application/json` for format and limit errors. + - Returns only `text/html` for some quota limit errors. + + #### InfluxDB OSS + + - Returns only `application/json` for format and limit errors. + + #### Related guides + + - [Troubleshoot issues writing data](/influxdb/cloud/write-data/troubleshoot/) + in: header + name: Accept + schema: + default: application/json + description: Error content type. + enum: + - application/json + type: string + - description: | + An organization name or ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Writes data to the bucket in the organization + associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. + - If you pass both `orgID` and `org`, they must both be valid. + - Writes data to the bucket in the specified organization. + in: query + name: org + required: true + schema: + description: The organization name or ID. + type: string + - description: | + An organization ID. + + #### InfluxDB Cloud + + - Doesn't use the `org` parameter or `orgID` parameter. + - Writes data to the bucket in the organization + associated with the authorization (API token). + + #### InfluxDB OSS + + - Requires either the `org` parameter or the `orgID` parameter. + - If you pass both `orgID` and `org`, they must both be valid. + - Writes data to the bucket in the specified organization. + in: query + name: orgID + schema: + type: string + - description: | + A bucket name or ID. + InfluxDB writes all points in the batch to the specified bucket. + in: query + name: bucket + required: true + schema: + description: The bucket name or ID. + type: string + - description: The precision for unix timestamps in the line protocol batch. + in: query + name: precision + schema: + $ref: '#/components/schemas/WritePrecision' + requestBody: + content: + 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 + schema: + format: byte + type: string + description: | + In the request body, provide data in [line protocol format](/influxdb/cloud/reference/syntax/line-protocol/). + + To send compressed data, do the following: + + 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. + 2. In your request, send the compressed data and the + `Content-Encoding: gzip` header. + + #### Related guides + + - [Best practices for optimizing writes](/influxdb/cloud/write-data/best-practices/optimize-writes/) + required: true + responses: + '204': + description: | + Success. + + #### InfluxDB Cloud + + - Validated and queued the request. + - Handles the write asynchronously - the write might not have completed yet. + + #### InfluxDB OSS + + - Successfully wrote all points in the batch. + + #### Related guides + + - [How to check for write errors](/influxdb/cloud/write-data/troubleshoot/) + '400': + content: + application/json: + examples: + measurementSchemaFieldTypeConflict: + summary: (Cloud) field type conflict thrown by an explicit bucket schema + value: + code: invalid + message: 'partial write error (2 written): unable to parse ''air_sensor,service=S1,sensor=L1 temperature="90.5",humidity=70.0 1632850122'': schema: field type for field "temperature" not permitted by schema; got String but expected Float' + orgNotFound: + summary: (OSS) organization not found + value: + code: invalid + message: 'failed to decode request body: organization not found' + schema: + $ref: '#/components/schemas/LineProtocolError' + description: | + Bad request. The response body contains detail about the error. + + InfluxDB returns this error if the line protocol data in the request is malformed. + The response body contains the first malformed line in the data, and indicates what was expected. + For partial writes, the number of points written and the number of points rejected are also included. + For more information, check the `rejected_points` measurement in your `_monitoring` bucket. + + #### InfluxDB Cloud + + - Returns this error for bucket schema conflicts. + + #### InfluxDB OSS + + - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '413': + content: + application/json: + examples: + dataExceedsSizeLimitOSS: + summary: InfluxDB OSS response + value: | + {"code":"request too large","message":"unable to read data: points batch is too large"} + schema: + $ref: '#/components/schemas/LineProtocolLengthError' + text/html: + examples: + dataExceedsSizeLimit: + summary: InfluxDB Cloud response + value: | + + 413 Request Entity Too Large + +

413 Request Entity Too Large

+
+
nginx
+ + + schema: + type: string + description: | + The request payload is too large. + InfluxDB rejected the batch and did not write any data. + + #### InfluxDB Cloud: + + - Returns this error if the payload exceeds the 50MB size limit. + - Returns `Content-Type: text/html` for this error. + + #### InfluxDB OSS: + + - Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. + - Returns `Content-Type: application/json` for this error. + '429': + description: | + Too many requests. + + #### InfluxDB Cloud + + - Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits). + - For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. + - For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header. + + Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. + Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. + + #### InfluxDB OSS + + - Doesn't return this error. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + format: int32 + type: integer + '500': + $ref: '#/components/responses/InternalServerError' + '503': + description: | + Service unavailable. + + - Returns this error if + the server is temporarily unavailable to accept writes. + - Returns a `Retry-After` header that describes when to try the write again. + headers: + Retry-After: + description: Non-negative decimal integer indicating seconds to wait before retrying the request. + schema: + format: int32 + type: integer + default: + $ref: '#/components/responses/GeneralServerError' + summary: Write data + tags: + - Data I/O endpoints + - Write + /legacy/authorizations: + servers: + - url: /private + /legacy/authorizations/{authID}: + servers: + - url: /private + /legacy/authorizations/{authID}/password: + servers: + - url: /private + /query: + get: + description: Queries InfluxDB using InfluxQL. + operationId: GetLegacyQuery + parameters: + - $ref: '#/components/parameters/TraceSpan' + - in: header + name: Accept + schema: + default: application/json + description: | + Media type that the client can understand. + + **Note**: With `application/csv`, query results include [**unix timestamps**](/influxdb/cloud-iox/reference/glossary/#unix-timestamp) instead of [RFC3339 timestamps](/influxdb/cloud-iox/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. + in: header + name: Accept-Encoding + schema: + default: identity + description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. + enum: + - gzip + - identity + type: string + - in: header + name: Content-Type + schema: + enum: + - application/json + type: string + - description: The InfluxDB 1.x username to authenticate the request. + in: query + name: u + schema: + type: string + - description: The InfluxDB 1.x password to authenticate the request. + in: query + name: p + schema: + type: string + - description: | + The database to query data from. + This is mapped to an InfluxDB [bucket](/influxdb/cloud-iox/reference/glossary/#bucket). + For more information, see [Database and retention policy mapping](/influxdb/cloud-iox/api/influxdb-1x/dbrp/). + in: query + name: db + required: true + schema: + type: string + - description: | + The retention policy to query data from. + This is mapped to an InfluxDB [bucket](/influxdb/cloud-iox/reference/glossary/#bucket). + For more information, see [Database and retention policy mapping](/influxdb/cloud-iox/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 (`;`). + in: query + name: q + required: true + schema: + type: string + - description: | + A unix timestamp precision. + Formats timestamps as [unix (epoch) timestamps](/influxdb/cloud-iox/reference/glossary/#unix-timestamp) the specified precision + instead of [RFC3339 timestamps](/influxdb/cloud-iox/reference/glossary/#rfc3339-timestamp) with nanosecond precision. + in: query + name: epoch + schema: + enum: + - ns + - u + - ยต + - ms + - s + - m + - h + type: string + responses: + '200': + content: + application/csv: + schema: + $ref: '#/components/schemas/InfluxqlCsvResponse' + application/json: + schema: + $ref: '#/components/schemas/InfluxqlJsonResponse' + application/x-msgpack: + schema: + format: binary + type: string + text/csv: + schema: + $ref: '#/components/schemas/InfluxqlCsvResponse' + description: Query results + headers: + Content-Encoding: + description: Lists encodings (usually compression algorithms) that have been applied to the response payload. + schema: + default: identity + description: | + The content coding: + - `gzip`: compressed data + - `identity`: unmodified, uncompressed data. + enum: + - gzip + - identity + type: string + Trace-Id: + description: The trace ID, if generated, of the request. + schema: + description: Trace ID of a request. + type: string + '429': + description: | + #### InfluxDB Cloud: + - returns this error if a **read** or **write** request exceeds your + plan's [adjustable service quotas](/influxdb/cloud-iox/account-management/limits/#adjustable-service-quotas) + or if a **delete** request exceeds the maximum + [global limit](/influxdb/cloud-iox/account-management/limits/#global-limits) + - returns `Retry-After` header that describes when to try the write again. + + #### InfluxDB OSS: + - doesn't return this error. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + format: int32 + type: integer + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Error processing query + summary: Query with the 1.x compatibility API + tags: + - Legacy Query + /write: + post: + operationId: PostLegacyWrite + parameters: + - $ref: '#/components/parameters/TraceSpan' + - description: The InfluxDB 1.x username to authenticate the request. + in: query + name: u + schema: + type: string + - description: The InfluxDB 1.x password to authenticate the request. + in: query + name: p + schema: + type: string + - 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 + schema: + type: string + - description: Retention policy name. + in: query + name: rp + schema: + type: string + - description: Write precision. + in: query + name: precision + schema: + type: string + - 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. + enum: + - gzip + - identity + type: string + requestBody: + content: + text/plain: + schema: + type: string + description: Line protocol body + required: true + responses: + '204': + 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. + '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. + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: No token was sent and they are required. + '413': + content: + 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. + '429': + 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. + 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. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + format: int32 + type: integer + default: + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Internal server error + summary: Write time series data into InfluxDB in a V1-compatible format + tags: + - Legacy Write +security: + - TokenAuthentication: [] +servers: + - url: / +tags: + - 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) + + name: Authentication + x-traitTag: true + - description: | + Create and manage authorizations (API tokens). + + An _authorization_ contains a list of `read` and `write` + permissions for organization resources and provides an API token for authentication. + An authorization belongs to an organization and only contains permissions for that organization. + + We recommend the following for managing your tokens: + + - Create a generic user to create and manage tokens for writing data. + - Store your tokens in a secure password vault for future access. + + ### User sessions with authorizations + + Optionally, when creating an authorization, you can scope it to a specific user. + If the user signs in with username and password, creating a _user session_, + the session carries the permissions granted by all the user's authorizations. + For more information, see [how to assign a token to a specific user](/influxdb/cloud/security/tokens/create-token/). + To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). + + ### Related endpoints + + - [Signin](#tag/Signin) + - [Signout](#tag/Signout) + + ### Related guides + + - [Authorize API requests](/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 (API tokens) + - name: Bucket Schemas + - 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), + 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/) + name: Buckets + - name: Cells + - name: Checks + - description: | + To specify resources, some InfluxDB API endpoints require parameters or + properties in the request--for example, + writing to a `bucket` resource in an `org` (_organization_ resource). + + ### Common parameters + + | Query parameter | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `bucket` | string | The bucket name or ID ([find your bucket](/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: Config + - name: Dashboards + - name: Data I/O endpoints + - description: | + The InfluxDB 1.x data model includes [databases](/influxdb/v1.8/concepts/glossary/#database) + and [retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). + InfluxDB 2.x replaces databases and retention policies with buckets. + To support InfluxDB 1.x query and write patterns in InfluxDB 2.x, + databases and retention policies are mapped to buckets using the + database and retention policy (DBRP) mapping service. + The DBRP mapping service uses the database and retention policy + specified in 1.x compatibility API requests to route operations to a bucket. + + ### Related guides + + - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) + name: DBRPs + - description: | + Delete data from an InfluxDB bucket. + name: Delete + - description: | + InfluxDB `/api/v2` API endpoints use standard HTTP request and response headers. + The following table shows common headers used by many InfluxDB API endpoints. + Some endpoints may use other headers that perform functions more specific to those endpoints--for example, + the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body. + + | Header | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `Accept` | string | The content type that the client can understand. | + | `Authorization` | string | The authorization scheme and credential. | + | `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. | + | `Content-Type` | string | The format of the data in the request body. | + name: Headers + x-traitTag: true + - description: | + Store, manage, and execute scripts in InfluxDB. + A script stores your custom Flux script and provides an invokable + endpoint that accepts runtime parameters. + In a script, you can specify custom runtime parameters + (`params`)--for example, `params.myparameter`. + Once you create a script, InfluxDB generates an + [`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke) + for your organization. + You can run the script from API requests and tasks, defining parameter + values for each run. + When the script runs, InfluxDB replaces `params` references in the + script with the runtime parameter values you define. + + Use the `/api/v2/scripts` endpoints to create and manage scripts. + See related guides to learn how to define parameters and execute scripts. + + ### Related guides + + - [Invoke custom scripts](/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 + - name: Legacy Query + - name: Legacy Write + - name: Limits + - name: NotificationEndpoints + - name: NotificationRules + - 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 + - description: | + Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results: + + | Query parameter | Value type | Description | + |:------------------------ |:--------------------- |:-------------------------------------------| + | `limit` | integer | The maximum number of records to return (after other parameters are applied). | + | `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). | + | `after` | string (resource ID) | Only returns resources created after the specified resource. | + + ### Limitations + + - For specific endpoint parameters and examples, see the endpoint definition. + - If you specify an `offset` parameter value greater than the total number of records, + then InfluxDB returns an empty list in the response + (given `offset` skips the specified number of records). + + The following example passes `offset=50` to skip the first 50 results, + but the user only has 10 buckets: + + ```sh + curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \ + --header "Authorization: Token INFLUX_API_TOKEN" + ``` + + The response contains the following: + + ```json + { + "links": { + "prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID", + "self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID" + }, + "buckets": [] + } + ``` + name: Pagination + x-traitTag: true + - 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. + + [**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: | + InfluxDB `/api/v2` API endpoints use standard HTTP status codes for success and failure responses. + The response body may include additional details. + For details about a specific operation's response, + see **Responses** and **Response Samples** for that operation. + + API operations may return the following HTTP status codes: + + |  Code  | Status | Description | + |:-----------:|:------------------------ |:--------------------- | + | `200` | Success | | + | `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. | + | `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems:
  • 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. | + name: Response codes + x-traitTag: true + - name: Routes + - name: Rules + - name: Secrets + - name: Security and access endpoints + - name: Setup + - name: Signin + - name: Signout + - description: "The following table shows the most common operations that the InfluxDB `/api/v2` API supports.\nSome resources may support other operations that perform functions more specific to those resources.\nFor example, you can use the `PATCH /api/v2/scripts` endpoint to update properties of a script\nresource.\n\n| Operation | |\n|:----------|:-----------------------------------------------------------------------|\n| Write | Writes (`POST`) data to a bucket. |\n| Run | Executes (`POST`) a query or script and returns the result. |\n| List |\tRetrieves (`GET`) a list of zero or more resources. |\n| Create |\tCreates (`POST`) a new resource and returns the resource. |\n| Update |\tModifies (`PUT`) an existing resource to reflect data in your request. |\n| Delete |\tRemoves (`DELETE`) a specific resource. |\n" + name: Supported operations + x-traitTag: true + - name: System information endpoints + - description: | + Process and analyze your data with [tasks](/influxdb/cloud/reference/glossary/#task) + in the InfluxDB task engine. + Use the `/api/v2/tasks` endpoints to schedule and manage tasks, retry task runs, and retrieve run logs. + + To configure a task, provide the script and the schedule to run the task. + For examples, see how to create a task with the [`POST /api/v2/tasks` endpoint](#operation/PostTasks). + + + + ### Properties + + A `task` object contains information about an InfluxDB task resource. + + The following table defines the properties that appear in this object: + + + + ### Related guides + + - [Get started with tasks](/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: | + Export and apply InfluxDB **templates**. + Manage **stacks** of templated InfluxDB resources. + + InfluxDB templates are prepackaged configurations for resources. + Use InfluxDB templates to configure a fresh instance of InfluxDB, + back up your dashboard configuration, or share your configuration. + + Use the `/api/v2/templates` endpoints to export templates and apply templates. + + **InfluxDB stacks** are stateful InfluxDB templates that let you + add, update, and remove installed template resources over time, avoid duplicating + resources when applying the same or similar templates more than once, and + apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud. + + Use the `/api/v2/stacks` endpoints to manage installed template resources. + + ### Related guides + + - [InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/) + - [InfluxDB templates](/influxdb/cloud/influxdb-templates/) + name: Templates + - name: Usage + - description: | + Retrieve specific users. + + InfluxDB Cloud lets you invite and collaborate with multiple users in your organization. + To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI); + you can't use the InfluxDB API to manage users in InfluxDB Cloud. + Once a user is added to your organization, you can use the + `GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to + view specific members. + + ### User sessions with authorizations + + Optionally, you can scope an authorization (and its API token) to a user. + If a user signs in with username and password, creating a _user session_, + the session carries the permissions granted by all the user's authorizations. + To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin). + + ### Related guides + + - [Manage users](/influxdb/cloud/organizations/users/) + name: Users + - name: Variables + - name: Views + - description: | + Write time series data to [buckets](/influxdb/cloud/reference/glossary/#bucket). + name: Write +x-tagGroups: + - name: Using the InfluxDB HTTP API + tags: + - Quick start + - Authentication + - Supported operations + - Headers + - Pagination + - Response codes + - Data I/O endpoints + - Security and access endpoints + - System information endpoints + - name: All endpoints + tags: + - Authorizations (API tokens) + - Bucket Schemas + - Buckets + - Delete + - DBRPs + - Invokable Scripts + - Legacy Query + - Legacy Write + - Limits + - Organizations + - Query + - Resources + - Routes + - Secrets + - Tasks + - Telegrafs + - Templates + - Usage + - Variables + - Write diff --git a/api-docs/cloud-iox/swaggerV1Compat.yml b/api-docs/cloud-iox/swaggerV1Compat.yml new file mode 100644 index 000000000..07def9efd --- /dev/null +++ b/api-docs/cloud-iox/swaggerV1Compat.yml @@ -0,0 +1,432 @@ +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/). + + This documentation is generated from the + [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml). + license: + name: MIT + url: https://opensource.org/licenses/MIT +servers: + - url: / +paths: + /write: + post: + operationId: PostWriteV1 + tags: + - Write + summary: Write time series data into InfluxDB in a V1-compatible format + requestBody: + description: Line protocol body + required: true + content: + text/plain: + schema: + type: string + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/AuthUserV1' + - $ref: '#/components/parameters/AuthPassV1' + - in: query + name: db + schema: + type: string + required: true + description: Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy. + - in: query + name: rp + schema: + type: string + description: Retention policy name. + - in: query + name: precision + schema: + type: string + 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. + schema: + type: string + 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. + '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. + 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. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '403': + description: No token was sent and they are required. + content: + application/json: + 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. + 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. + headers: + Retry-After: + 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. + headers: + Retry-After: + description: A non-negative decimal integer indicating the seconds to delay after the response is received. + schema: + type: integer + format: int32 + default: + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /query: + post: + operationId: PostQueryV1 + tags: + - Query + summary: Query InfluxDB in a V1 compatible format + requestBody: + description: InfluxQL query to execute. + content: + text/plain: + schema: + type: string + parameters: + - $ref: '#/components/parameters/TraceSpan' + - $ref: '#/components/parameters/AuthUserV1' + - $ref: '#/components/parameters/AuthPassV1' + - in: header + 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. + default: application/json + enum: + - application/json + - application/csv + - text/csv + - 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. + schema: + type: string + description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. + default: identity + enum: + - gzip + - identity + - in: header + name: Content-Type + schema: + type: string + enum: + - application/vnd.influxql + - in: query + name: db + schema: + type: string + required: true + description: Bucket to query. + - in: query + name: rp + schema: + type: string + description: Retention policy name. + - in: query + name: q + description: Defines the influxql query to run. + schema: + type: string + responses: + '200': + 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 + schema: + type: string + 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. + schema: + type: string + description: Specifies the request's trace ID. + content: + application/csv: + schema: + $ref: '#/components/schemas/InfluxQLCSVResponse' + text/csv: + schema: + $ref: '#/components/schemas/InfluxQLCSVResponse' + application/json: + schema: + $ref: '#/components/schemas/InfluxQLResponse' + application/x-msgpack: + schema: + type: string + format: binary + '429': + 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. + schema: + type: integer + format: int32 + default: + description: Error processing query + content: + application/json: + schema: + $ref: '#/components/schemas/Error' +components: + parameters: + TraceSpan: + in: header + name: Zap-Trace-Span + description: OpenTracing span context + example: + trace_id: '1' + span_id: '1' + baggage: + key: value + required: false + schema: + type: string + AuthUserV1: + in: query + name: u + required: false + schema: + type: string + description: Username. + AuthPassV1: + in: query + name: p + required: false + schema: + type: string + description: User token. + schemas: + InfluxQLResponse: + properties: + results: + type: array + oneOf: + - required: + - statement_id + - error + - required: + - statement_id + - series + items: + type: object + properties: + statement_id: + type: integer + error: + type: string + series: + type: array + items: + type: object + properties: + name: + type: string + tags: + type: object + additionalProperties: + type: string + partial: + type: boolean + columns: + type: array + items: + type: string + values: + type: array + items: + type: array + 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 + Error: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - internal error + - not found + - conflict + - invalid + - unprocessable entity + - empty value + - unavailable + - forbidden + - too many requests + - unauthorized + - method not allowed + message: + readOnly: true + description: Message is a human-readable message. + type: string + required: + - code + - message + LineProtocolError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - internal error + - not found + - conflict + - invalid + - empty value + - unavailable + message: + readOnly: true + description: Message is a human-readable message. + type: string + op: + readOnly: true + 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. + type: string + line: + readOnly: true + description: First line within sent body containing malformed data + type: integer + format: int32 + required: + - code + - message + - op + - err + LineProtocolLengthError: + properties: + code: + description: Code is the machine-readable error code. + readOnly: true + type: string + enum: + - invalid + message: + readOnly: true + description: Message is a human-readable message. + type: string + maxLength: + readOnly: true + description: Max length in bytes for a body of line-protocol. + type: integer + format: int32 + required: + - code + - message + - maxLength + securitySchemes: + TokenAuthentication: + type: apiKey + name: Authorization + in: header + description: | + Use the [Token authentication](#section/Authentication/TokenAuthentication) + scheme to authenticate to the InfluxDB API. + + + In your API requests, send an `Authorization` header. + For the header value, provide the word `Token` followed by a space and an InfluxDB API token. + The word `Token` is case-sensitive. + + + ### Syntax + + `Authorization: Token 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). + - [Manage API tokens](/influxdb/cloud/security/tokens/). + 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): + + + 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. + + + 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: | + 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) + + + x-traitTag: true + - name: Query + - name: Write +x-tagGroups: [] diff --git a/api-docs/cloud/content/tag-groups.yml b/api-docs/cloud/content/tag-groups.yml new file mode 100644 index 000000000..62cc43226 --- /dev/null +++ b/api-docs/cloud/content/tag-groups.yml @@ -0,0 +1,13 @@ +- name: Using the InfluxDB HTTP API + tags: + - Quick start + - Authentication + - Supported operations + - Headers + - Pagination + - Response codes + - Data I/O endpoints + - Security and access endpoints + - System information endpoints +- name: All endpoints + tags: [] diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 83da9e2c3..cc5a75aa3 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -38,7 +38,7 @@ components: summary: A task with Flux value: description: This task contains Flux that configures the task schedule and downsamples CPU data every hour. - flux: "option task = {name: \"CPU Total 1 Hour New\", every: 1h}from(bucket: \"telegraf\")|> range(start: -1h)|> filter(fn: (r) => (r._measurement == \"cpu\"))|> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))|> filter(fn: (r) => (r.cpu == \"cpu-total\"))|> aggregateWindow(every: 1h, fn: max)|> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")" + 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 TaskWithScriptRequest: description: | @@ -1473,6 +1473,7 @@ components: description: code is the machine-readable error code. enum: - internal error + - not implemented - not found - conflict - invalid @@ -1505,6 +1506,7 @@ components: description: code is the machine-readable error code. enum: - internal error + - not implemented - not found - conflict - invalid @@ -2500,6 +2502,13 @@ components: - concurrentWriteRequests - cardinality type: object + stack: + properties: + enabled: + type: boolean + required: + - enabled + type: object task: properties: maxTasks: @@ -2507,6 +2516,16 @@ components: required: - maxTasks type: object + timeout: + properties: + queryUnconditionalTimeoutSeconds: + type: integer + queryidleWriteTimeoutSeconds: + type: integer + required: + - queryUnconditionalTimeoutSeconds + - queryidleWriteTimeoutSeconds + type: object required: - rate - bucket @@ -4765,7 +4784,7 @@ components: authorizationID: description: | An authorization ID. - Identifies the authorization used when the task communicates with the query engine. + Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the [`GET /api/v2/authorizations` endpoint](#operation/GetAuthorizations) to @@ -4776,16 +4795,24 @@ components: readOnly: true type: string cron: - $ref: '#/components/schemas/TaskCron' + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. + type: string description: - $ref: '#/components/schemas/TaskDescription' + description: A description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: The interval ([duration literal](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. + format: duration + type: string flux: - $ref: '#/components/schemas/TaskFlux' - id: description: | - The resource ID that InfluxDB uses to uniquely identify the task. + The Flux script that the task executes. + + #### Limitations + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + format: flux + type: string + id: readOnly: true type: string labels: @@ -4829,26 +4856,56 @@ components: readOnly: true type: object name: - $ref: '#/components/schemas/TaskName' + description: The name of the task. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. + format: duration + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) name. + Specifies the organization that owns the task. + type: string orgID: - $ref: '#/components/schemas/TaskOrgID' + description: | + An [organization](/influxdb/cloud/reference/glossary/#organization) ID. + Specifies the organization that owns the task. + type: string ownerID: description: | - A user ID. - Identifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the task. + A [user](/influxdb/cloud/reference/glossary/#user) ID. + Specifies the owner of the task. - To find a user ID, use the + To find a user ID, you can use the [`GET /api/v2/users` endpoint](#operation/GetUsers) to list users. type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + description: | + A script ID. + Specifies the [invokable script](#tag/Invokable-Scripts) that the task executes. + + #### Limitations + + - If you use the `scriptID` property, you can't use the `flux` property. + + #### Related guides + + - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script) + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + description: | + Key-value pairs for `params` in the script. + Defines the invocation parameter values passed to the script specified by `scriptID`. + When running the task, InfluxDB executes the script with the parameters + you provide. + + #### Limitations + + - To use `scriptParameters`, you must provide a `scriptID`. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. + type: object status: $ref: '#/components/schemas/TaskStatusType' updatedAt: @@ -4863,92 +4920,57 @@ components: TaskCreateRequest: properties: cron: - $ref: '#/components/schemas/TaskCron' + description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time. + type: string description: - $ref: '#/components/schemas/TaskDescription' + description: The description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: | + The interval ([duration literal](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals))) at which the task runs. + `every` also determines when the task first runs, depending on the specified time. + type: string flux: - $ref: '#/components/schemas/TaskFlux' + description: | + The Flux script that the task runs. + + #### Limitations + + - If you use the `flux` property, you can't use the `scriptID` and `scriptParameters` properties. + type: string name: - $ref: '#/components/schemas/TaskName' + description: The name of the task + type: string offset: - $ref: '#/components/schemas/TaskOffset' + description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. + format: duration + type: string org: - $ref: '#/components/schemas/TaskOrg' + description: The name of the organization that owns the task. + type: string orgID: - $ref: '#/components/schemas/TaskOrgID' + description: The ID of the organization that owns the task. + type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + description: | + The ID of the script that the task runs. + + #### Limitations + + - If you use the `scriptID` property, you can't use the `flux` property. + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + description: | + The parameter key-value pairs passed to the script (referenced by `scriptID`) during the task run. + + #### Limitations + + - `scriptParameters` requires `scriptID`. + - If you use the `scriptID` and `scriptParameters` properties, you can't use the `flux` property. + type: object status: $ref: '#/components/schemas/TaskStatusType' type: object - TaskCron: - description: A [Cron expression](https://en.wikipedia.org/wiki/Cron#Overview) that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions. - format: cron - type: string - TaskDescription: - description: A description of the task. - type: string - TaskEvery: - description: The interval ([duration literal](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time. - format: duration - type: string - TaskFlux: - description: | - Flux with [task configuration options](/influxdb/cloud/process-data/task-options/) - and the script for the task to run. - - #### Related guides - - - [Task configuration options](/influxdb/cloud/process-data/task-options/) - format: Flux - type: string - TaskName: - description: The name of the task. - type: string - TaskOffset: - description: A [duration](https://docs.influxdata.com/flux/v0.x/spec/lexical-elements/#duration-literals) to delay execution of the task after the scheduled time has elapsed. `0` removes the offset. - format: duration - type: string - TaskOrg: - description: | - An organization name. - Identifies the [organization](/influxdb/cloud/reference/glossary/#organization) that owns the task. - type: string - TaskOrgID: - description: | - An organization ID. - Identifies the [organization](/influxdb/cloud/reference/glossary/#organization) that owns the task. - type: string - TaskScriptID: - description: | - A script ID. - Identifies the [invokable script](#tag/Invokable-Scripts) that the task runs. - - #### Related guides - - - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). - type: string - TaskScriptParameters: - description: | - Key-value pairs for `params` in the script. - Defines the invocation parameter values passed to the [invokable script](#tag/Invokable-Scripts) specified - by the `scriptID` property. - When running the task, InfluxDB executes the script with the parameters - you provide. - - #### Limitations - - - To use the `scriptParameters` property, you must also set the `scriptID` property - for the task. - - #### Related guides - - - [Create a task that references a script](/influxdb/cloud/process-data/manage-tasks/create-task/#create-a-task-that-references-a-script). - type: object TaskStatusType: description: | `inactive` cancels scheduled runs and prevents manual runs of the task. @@ -4959,21 +4981,29 @@ components: TaskUpdateRequest: properties: cron: - $ref: '#/components/schemas/TaskCron' + description: Update the 'cron' option in the flux script. + type: string description: - $ref: '#/components/schemas/TaskDescription' + description: Update the description of the task. + type: string every: - $ref: '#/components/schemas/TaskEvery' + description: Update the 'every' option in the flux script. + type: string flux: - $ref: '#/components/schemas/TaskFlux' + description: Update the Flux script that the task runs. + type: string name: - $ref: '#/components/schemas/TaskName' + description: Update the 'name' option in the flux script. + type: string offset: - $ref: '#/components/schemas/TaskOffset' + description: Update the 'offset' option in the flux script. + type: string scriptID: - $ref: '#/components/schemas/TaskScriptID' + description: Update the 'scriptID' of the task. + type: string scriptParameters: - $ref: '#/components/schemas/TaskScriptParameters' + description: Update the 'scriptParameters' of the task. + type: object status: $ref: '#/components/schemas/TaskStatusType' type: object @@ -6706,3877 +6736,43 @@ info: url: https://opensource.org/licenses/MIT openapi: 3.0.0 paths: - /api/v2: - get: - description: | - Retrieves all the top level routes for the InfluxDB API. - - #### Limitations - - - Only returns top level routes--for example, the response contains - `"tasks":"/api/v2/tasks"`, and doesn't contain resource-specific routes - for tasks (`/api/v2/tasks/TASK_ID/...`). - operationId: GetRoutes - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Routes' - description: | - Success. - The response body contains key-value pairs with the resource name and - top-level route. - summary: List all top level routes - tags: - - Routes - - System information endpoints - /api/v2/authorizations: - get: - description: | - Lists authorizations. - - To limit which authorizations are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all authorizations. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token](/influxdb/cloud/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - To retrieve an authorization, the request must use an API token that has the - following permissions: - - - `read-authorizations` - - `read-user` for the user that the authorization is scoped to - - #### Related guides - - - [View tokens](/influxdb/cloud/security/tokens/view-tokens/) - operationId: GetAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - 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 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 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 the specified [organization](/influxdb/cloud/reference/glossary/#organization). - in: query - name: org - schema: - type: string - - description: | - An API [token](/influxdb/cloud/reference/glossary/#token) value. - Specifies an authorization by its `token` property value - and returns the authorization. - - #### InfluxDB OSS - - - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, - applies other parameters, and then returns the result. - - #### Limitations - - - The parameter is non-repeatable. If you specify more than one, - only the first one is used. If a resource with the specified - property value doesn't exist, then the response body contains an empty list. - in: query - name: token - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - description: | - Success. The response body contains a list of authorizations. - - If the response body is missing authorizations that you expect, check that the API - token used in the request has `read-user` permission for the users (`userID` property value) - in those authorizations. - - #### InfluxDB OSS - - - **Warning**: The response body contains authorizations with their - [API token](/influxdb/cloud/reference/glossary/#token) values in clear text. - - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: List authorizations - tags: - - Authorizations (API tokens) - - Security and access endpoints - post: - 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. - The API token is the authorization's `token` property value. - - To follow best practices for secure API token generation and retrieval, - InfluxDB enforces access restrictions on API tokens. - - - InfluxDB allows access to the API token value immediately after the authorization is created. - - You canโ€™t change access (read/write) permissions for an API token after itโ€™s created. - - Tokens stop working when the user who created the token is deleted. - - We recommend the following for managing your tokens: - - - Create a generic user to create and manage tokens for writing data. - - Store your tokens in a secure password vault for future access. - - #### Required permissions - - - `write-authorizations` - - `write-user` for the user that the authorization is scoped to - - #### Related guides - - - [Create a token](/influxdb/cloud/security/tokens/create-token/) - operationId: PostAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - description: The authorization to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: | - Success. The authorization is created. The response body contains the - authorization. - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Create an authorization - tags: - - Authorizations (API tokens) - - Security and access endpoints - /api/v2/authorizations/{authID}: - delete: - description: | - Deletes an authorization. - - Use the endpoint to delete an API token. - - If you want to disable an API token instead of delete it, - [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). - operationId: DeleteAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to delete. - in: path - name: authID - required: true - schema: - type: string - responses: - '204': - description: Success. The authorization is deleted. - '400': - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Delete an authorization - tags: - - Authorizations (API tokens) - - Security and access endpoints - get: - description: | - Retrieves an authorization. - - Use this endpoint to retrieve information about an API token, including - the token's permissions and the user that the token is scoped to. - - #### InfluxDB OSS - - - InfluxDB OSS returns - [API token](/influxdb/cloud/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - - #### Related guides - - - [View tokens](/influxdb/cloud/security/tokens/view-tokens/) - externalDocs: - description: View tokens - url: https://docs.influxdata.com/influxdb/cloud/security/tokens/view-tokens/ - operationId: GetAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to retrieve. - in: path - name: authID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the authorization. - '400': - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Retrieve an authorization - tags: - - Authorizations (API tokens) - - Security and access endpoints - patch: - description: | - Updates an authorization. - - Use this endpoint to set an API token's status to be _active_ or _inactive_. - InfluxDB rejects requests that use inactive API tokens. - operationId: PatchAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: In the request body, provide the authorization properties to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the updated authorization. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Update an API token to be active or inactive - tags: - - Authorizations (API tokens) - - Security and access endpoints - /api/v2/buckets: - get: - description: | - Lists [buckets](/influxdb/cloud/reference/glossary/#bucket). - - InfluxDB retrieves buckets owned by the - [organization](/influxdb/cloud/reference/glossary/#organization) - associated with the authorization - ([API token](/influxdb/cloud/reference/glossary/#token)). - To limit which buckets are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all buckets up to the - default `limit`. - - #### InfluxDB OSS - - - If you use an _[operator token](/influxdb/cloud/security/tokens/#operator-token)_ - to authenticate your request, InfluxDB retrieves resources for _all - organizations_ in the instance. - To retrieve resources for only a specific organization, use the - `org` parameter or the `orgID` parameter to specify the organization. - - #### Required permissions - - | Action | Permission required | - |:--------------------------|:--------------------| - | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](/influxdb/cloud/reference/internals/system-buckets/) | `read-orgs` | - - #### Related Guides - - - [Manage buckets](/influxdb/cloud/organizations/buckets/) - operationId: GetBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/After' - - description: | - An organization name. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Lists buckets for the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Lists buckets for the specified organization. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Lists buckets for the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Lists buckets for the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A bucket name. - Only returns buckets with the specified name. - in: query - name: name - schema: - type: string - - description: | - A bucket ID. - Only returns the bucket with the specified ID. - in: query - name: id - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - buckets: - - createdAt: '2022-03-15T17:22:33.72617939Z' - description: System bucket for monitoring logs - id: 77ca9dace40a9bfc - labels: [] - links: - labels: /api/v2/buckets/77ca9dace40a9bfc/labels - members: /api/v2/buckets/77ca9dace40a9bfc/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/77ca9dace40a9bfc/owners - self: /api/v2/buckets/77ca9dace40a9bfc - write: /api/v2/write?org=ORG_ID&bucket=77ca9dace40a9bfc - name: _monitoring - orgID: INFLUX_ORG_ID - retentionRules: - - everySeconds: 604800 - type: expire - schemaType: implicit - 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 - schema: - $ref: '#/components/schemas/Buckets' - description: | - Success. - The response body contains a list of `buckets`. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List buckets - tags: - - Buckets - x-codeSamples: - - label: 'cURL: filter buckets by name' - lang: Shell - 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: | - Creates a [bucket](/influxdb/cloud/reference/glossary/#bucket) - and returns the bucket resource. - 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 or writing to more than 20 buckets at a time can adversely affect - performance. - - #### Limitations - - - InfluxDB Cloud Free Plan allows users to create up to two buckets. - Exceeding the bucket quota will result in an HTTP `403` status code. - For additional information regarding InfluxDB Cloud offerings, see - [InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). - - #### Related Guides - - - [Create a bucket](/influxdb/cloud/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](/influxdb/cloud/reference/cli/influx/bucket/create) - operationId: PostBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostBucketRequest' - description: The bucket to create. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-03T23:04:41.073704121Z' - description: A bucket holding air sensor data - id: 37407e232b3911d8 - labels: [] - links: - labels: /api/v2/buckets/37407e232b3911d8/labels - members: /api/v2/buckets/37407e232b3911d8/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/37407e232b3911d8/owners - self: /api/v2/buckets/37407e232b3911d8 - write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 - name: air_sensor - orgID: INFLUX_ORG_ID - retentionRules: - - everySeconds: 2592000 - type: expire - schemaType: implicit - type: user - updatedAt: '2022-08-03T23:04:41.073704228Z' - schema: - $ref: '#/components/schemas/Bucket' - description: | - Success. - The bucket is created. - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '403': - content: - application/json: - examples: - quotaExceeded: - summary: Bucket quota exceeded - value: - code: forbidden - message: creating bucket would exceed quota - schema: - $ref: '#/components/schemas/Error' - description: | - Forbidden. - The bucket quota is exceeded. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: forbidden - type: string - '422': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable Entity. - The request body failed validation. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a bucket - tags: - - Buckets - x-codeSamples: - - label: 'cURL: create a bucket with retention period' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/buckets \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "air_sensor", - "description": "A bucket holding air sensor data", - "orgID": "INFLUX_ORG_ID", - "retentionRules": [ - { - "type": "expire", - "everySeconds": 2592000, - } - ] - }' - - label: cURL - lang: Shell - source: '' - /api/v2/buckets/{bucketID}: - delete: - description: | - Deletes a bucket and all associated records. - - #### InfluxDB Cloud - - - Does the following when you send a delete request: - - 1. Validates the request and queues the delete. - 2. Returns an HTTP `204` status code if queued; _error_ otherwise. - 3. Handles the delete asynchronously. - - #### InfluxDB OSS - - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - - #### Limitations - - - Only one bucket can be deleted per request. - - #### Related Guides - - - [Delete a bucket](/influxdb/cloud/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) - operationId: DeleteBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - Bucket ID. - The ID of the bucket to delete. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - The bucket is queued for deletion. - - #### InfluxDB OSS - - The bucket is deleted. - '400': - content: - application/json: - examples: - invalidID: - summary: | - Invalid ID. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad Request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested bucket was not found. - value: - code: not found - message: bucket not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Bucket not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header 'Accept: application/json' - get: - description: | - Retrieves a bucket. - - Use this endpoint to retrieve information for a specific bucket. - operationId: GetBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-03T23:04:41.073704121Z' - description: bucket for air sensor data - id: 37407e232b3911d8 - labels: [] - links: - labels: /api/v2/buckets/37407e232b3911d8/labels - members: /api/v2/buckets/37407e232b3911d8/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/37407e232b3911d8/owners - self: /api/v2/buckets/37407e232b3911d8 - write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 - name: air-sensor - orgID: bea7ea952287f70d - retentionRules: - - everySeconds: 2592000 - type: expire - schemaType: implicit - type: user - updatedAt: '2022-08-03T23:04:41.073704228Z' - schema: - $ref: '#/components/schemas/Bucket' - description: | - Success. - The response body contains the bucket information. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested bucket wasn't found. - value: - code: not found - message: bucket not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Bucket not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a bucket - tags: - - Buckets - patch: - description: | - Updates a bucket. - - Use this endpoint to update properties - (`name`, `description`, and `retentionRules`) of a bucket. - - #### InfluxDB Cloud - - - Requires the `retentionRules` property in the request body. If you don't - provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. - - #### InfluxDB OSS - - - Doesn't require `retentionRules`. - - #### Related Guides - - - [Update a bucket](/influxdb/cloud/organizations/buckets/update-bucket/) - operationId: PatchBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchBucketRequest' - description: The bucket update to apply. - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-03T23:04:41.073704121Z' - description: bucket holding air sensor data - id: 37407e232b3911d8 - labels: [] - links: - labels: /api/v2/buckets/37407e232b3911d8/labels - members: /api/v2/buckets/37407e232b3911d8/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/37407e232b3911d8/owners - self: /api/v2/buckets/37407e232b3911d8 - write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 - name: air_sensor - orgID: INFLUX_ORG_ID - retentionRules: - - everySeconds: 2592000 - type: expire - schemaType: implicit - type: user - updatedAt: '2022-08-07T22:49:49.422962913Z' - schema: - $ref: '#/components/schemas/Bucket' - description: An updated bucket - '400': - content: - application/json: - examples: - invalidJSONStringValue: - 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' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad Request. - '401': - $ref: '#/components/responses/AuthorizationError' - '403': - content: - application/json: - examples: - invalidRetention: - summary: | - The retention policy provided exceeds the max retention for the - organization. - value: - code: forbidden - message: provided retention exceeds orgs maximum retention duration - schema: - $ref: '#/components/schemas/Error' - description: | - Forbidden. - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested bucket wasn't found. - value: - code: not found - message: bucket not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Bucket not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "air_sensor", - "description": "bucket holding air sensor data", - "retentionRules": [ - { - "type": "expire", - "everySeconds": 2592000 - } - ] - }' - /api/v2/buckets/{bucketID}/labels: - get: - description: | - Lists all labels for a bucket. - - Labels are objects that contain `labelID`, `name`, `description`, and `color` - key-value pairs. They may be used for grouping and filtering InfluxDB - resources. - Labels are also capable of grouping across different resources--for example, - you can apply a label named `air_sensor` to a bucket and a task to quickly - organize resources. - - #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - - [Manage labels in the InfluxDB UI](/influxdb/cloud/visualize-data/labels/) - operationId: GetBucketsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve labels for. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - labels: - - id: 09cbd068e7ebb000 - name: production_buckets - orgID: INFLUX_ORG_ID - links: - self: /api/v2/labels - schema: - $ref: '#/components/schemas/LabelsResponse' - description: | - Success. - The response body contains a list of all labels 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a bucket - tags: - - Buckets - post: - description: | - Adds a label to a bucket and returns the new label information. - - Labels are objects that contain `labelID`, `name`, `description`, and `color` - key-value pairs. They may be used for grouping and filtering across one or - more kinds of **resources**--for example, you can apply a label named - `air_sensor` to a bucket and a task to quickly organize resources. - - #### Limitations - - - Before adding a label to a bucket, you must create the label if you - haven't already. To create a label with the InfluxDB API, send a `POST` - request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). - - #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - - [Manage labels in the InfluxDB UI](/influxdb/cloud/visualize-data/labels/) - operationId: PostBucketsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - Bucket ID. - The ID of the bucket to label. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: An object that contains a _`labelID`_ to add to the bucket. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - label: - id: 09cbd068e7ebb000 - name: production_buckets - orgID: INFLUX_ORG_ID - links: - self: /api/v2/labels - schema: - $ref: '#/components/schemas/LabelResponse' - description: | - Success. - The response body contains the label information. - '400': - $ref: '#/components/responses/BadRequestError' - examples: - invalidRequest: - summary: The `labelID` is missing from the request body. - value: - code: invalid - message: label id is required - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '422': - content: - application/json: - examples: - conflictingResource: - summary: | - Label already exists on the resource. - value: - code: conflict - message: Cannot add label, label already exists on resource - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - Label already exists on the resource. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "labelID": "09cbd068e7ebb000" - }' - /api/v2/buckets/{bucketID}/labels/{labelID}: - delete: - operationId: DeleteBucketsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Bucket not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/members: - get: - description: | - Lists all users for a bucket. - - InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have - permission to access InfluxDB. - - [Members](/influxdb/cloud/reference/glossary/#member) are users in - an organization with access to the specified resource. - - Use this endpoint to retrieve all users with access to a bucket. - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) - operationId: GetBucketsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve users for. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/buckets/37407e232b3911d8/members - users: - - id: 791df274afd48a83 - links: - self: /api/v2/users/791df274afd48a83 - name: example_user_1 - role: member - status: active - - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_2 - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. - The response body contains a list of all users 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a bucket - tags: - - Buckets - post: - description: | - Add a user to a bucket and return the new user information. - - InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have - permission to access InfluxDB. - - [Members](/influxdb/cloud/reference/glossary/#member) are users in - an organization. - - Use this endpoint to give a user member privileges to a bucket. - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) - operationId: PostBucketsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve users for. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as a member to the bucket. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_1 - role: member - status: active - schema: - $ref: '#/components/schemas/ResourceMember' - description: | - Success. - The response body contains the user information. - '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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "id": "09cfb87051cbe000" - } - /api/v2/buckets/{bucketID}/members/{userID}: - delete: - description: | - Removes a member from a bucket. - - Use this endpoint to remove a user's member privileges from a bucket. This - removes the user's `read` and `write` permissions for the bucket. - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) - operationId: DeleteBucketsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the user to remove. - in: path - name: userID - required: true - schema: - type: string - - description: | - The ID of the bucket to remove a user from. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer a member of the bucket. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/owners: - get: - description: | - Lists all [owners](/influxdb/cloud/reference/glossary/#owner) - of a bucket. - - Bucket owners have permission to delete buckets and remove user and member - permissions from the bucket. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `read-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a - list of owners for. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - operationId: GetBucketsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve owners for. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '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: | - 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a bucket - 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-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - *`INFLUX_ORG_ID`* is the ID of the organization that you want to add - an owner for. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - operationId: PostBucketsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to add an owner for. - in: path - name: bucketID - required: true - schema: - type: string - 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: A user to add as an owner for the bucket. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - 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-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner - from. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - operationId: DeleteBucketsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: | - The ID of the bucket to remove an owner from. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer an owner of the bucket. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a bucket - tags: - - Buckets + /api/v2: {} + /api/v2/authorizations: {} + /api/v2/authorizations/{authID}: {} + /api/v2/buckets: {} + /api/v2/buckets/{bucketID}: {} + /api/v2/buckets/{bucketID}/labels: {} + /api/v2/buckets/{bucketID}/labels/{labelID}: {} + /api/v2/buckets/{bucketID}/members: {} + /api/v2/buckets/{bucketID}/members/{userID}: {} + /api/v2/buckets/{bucketID}/owners: {} + /api/v2/buckets/{bucketID}/owners/{userID}: {} /api/v2/buckets/{bucketID}/schema/measurements: - get: - description: | - Lists _explicit_ - [schemas](/influxdb/cloud/reference/glossary/#schema) - (`"schemaType": "explicit"`) for a bucket. - - _Explicit_ schemas are used to enforce column names, tags, fields, and data - types for your data. - - By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`) - that conforms to your data. - - #### Related guides - - - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/) - operationId: getMeasurementSchemas - parameters: - - description: | - An organization name. - Specifies the organization that owns the schema. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Specifies the organization that owns the schema. - in: query - name: orgID - schema: - type: string - - description: | - A measurement name. - Only returns measurement schemas with the specified name. - in: query - name: name - schema: - type: string - - description: | - A bucket ID. - Lists measurement schemas for the specified bucket. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/MeasurementSchemaList' - description: A list of measurement schemas returning summary information. - headers: - ETag: - description: The current version of the bucket schema - schema: - type: string - '400': - content: - application/json: - examples: - invalidSchemaType: - summary: Invalid schema type. - value: - code: invalid - message: bucket schemaType must be explicit - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - summary: List measurement schemas of a bucket - tags: - - Bucket Schemas - post: - description: | - Creates an _explict_ measurement [schema](/influxdb/cloud/reference/glossary/#schema) - for a bucket. - - _Explicit_ schemas are used to enforce column names, tags, fields, and data - types for your data. - - By default, buckets have an _implicit_ schema-type (`"schemaType": "implicit"`) - that conforms to your data. - - Use this endpoint to create schemas that prevent non-conforming write requests. - - #### Limitations - - - Buckets must be created with the "explict" `schemaType` in order to use - schemas. - - #### Related guides - - - [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). - - [Create a bucket with an explicit schema](/influxdb/cloud/organizations/buckets/create-bucket/#create-a-bucket-with-an-explicit-schema) - operationId: createMeasurementSchema - parameters: - - description: | - An organization name. - Specifies the organization that owns the schema. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Specifies the organization that owns the schema. - in: query - name: orgID - schema: - type: string - - description: | - A bucket ID. - Adds a schema for the specified bucket. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/MeasurementSchemaCreateRequest' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/MeasurementSchema' - description: The current version of the measurement schema. - headers: - ETag: - description: The current version of the measurement schema - schema: - type: string - '400': - content: - 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. - summary: Invalid name - value: - code: invalid - message: name is invalid - duplicateColumnNamesExample: - 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. - 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. - 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. - summary: Missing timestamp - value: - code: invalid - message: Timestamp column is required - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - summary: Create a measurement schema for a bucket - tags: - - Bucket Schemas - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "temperature", - "column": [ - { - "type": "tag", - "name": "location" - }, - { - "type": "field", - "name": "value", - "dataType": "float" - }, - { - "type": "timestamp", - "name": "time" - } - ] - }' summary: Bucket schemas /api/v2/buckets/{bucketID}/schema/measurements/{measurementID}: - get: - description: | - Retrieves an explicit measurement [schema](/influxdb/cloud/reference/glossary/#schema). - operationId: getMeasurementSchema - parameters: - - description: | - Organization name. - Specifies the organization that owns the schema. - in: query - name: org - schema: - type: string - - description: | - Organization ID. - Specifies the organization that owns the schema. - in: query - name: orgID - schema: - type: string - - description: | - A bucket ID. - Retrieves schemas for the specified bucket. - in: path - name: bucketID - required: true - schema: - type: string - - description: | - The measurement schema ID. - Specifies the measurement schema to retrieve. - in: path - name: measurementID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/MeasurementSchema' - description: Schema definition for a single measurement - headers: - ETag: - description: The current version of the measurement schema - schema: - type: string - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - summary: Retrieve a measurement schema - tags: - - Bucket Schemas - patch: - description: | - Updates a measurement [schema](/influxdb/cloud/reference/glossary/#schema). - - Use this endpoint to update the fields (`name`, `type`, and `dataType`) of a - measurement schema. - - #### Limitations - - - You can't update the `name` of a measurement. - - #### Related guides - - - [Manage bucket schemas](/influxdb/cloud/organizations/buckets/bucket-schema/). - - [Using bucket schemas](https://www.influxdata.com/blog/new-bucket-schema-option-protect-from-unwanted-schema-changes/). - operationId: updateMeasurementSchema - parameters: - - description: | - An organization name. - Specifies the organization that owns the schema. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Specifies the organization that owns the schema. - in: query - name: orgID - schema: - type: string - - description: | - A bucket ID. - Specifies the bucket to retrieve schemas for. - in: path - name: bucketID - required: true - schema: - type: string - - description: | - A measurement schema ID. - Retrieves the specified measurement schema. - in: path - name: measurementID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/MeasurementSchemaUpdateRequest' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/MeasurementSchema' - description: | - Success. - The response body contains the measurement schema. - '400': - content: - application/json: - examples: - missingColumnsExample: - description: The error returned when the request body does not contain all the columns from the source. - summary: Deleted columns - value: - code: invalid - message: Unable to delete columns from schema - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - summary: Update a measurement schema - tags: - - Bucket Schemas - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request PATCH "INFLUX_URL/api/v2/buckets/BUCKET_ID/schema/measurements \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "column": [ - { - "type": "tag", - "name": "location" - }, - { - "type": "field", - "name": "value", - "dataType": "float" - }, - { - "type": "timestamp", - "name": "time" - } - ] - }' summary: Bucket Schema - /api/v2/checks: - get: - operationId: GetChecks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show checks that belong to a specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Checks' - description: A list of checks - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all checks - tags: - - Checks - post: - operationId: CreateCheck - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostCheck' - description: Check to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: Check created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add new check - tags: - - Checks - /api/v2/checks/{checkID}: - delete: - operationId: DeleteChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a check - tags: - - Checks - get: - operationId: GetChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: The check requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a check - tags: - - Checks - patch: - operationId: PatchChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CheckPatch' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: An updated check - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a check - tags: - - Checks - put: - operationId: PutChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: An updated check - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a check - tags: - - Checks - /api/v2/checks/{checkID}/labels: - get: - operationId: GetChecksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a check - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a check - tags: - - Checks - post: - operationId: PostChecksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the check - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a check - tags: - - Checks - /api/v2/checks/{checkID}/labels/{labelID}: - delete: - operationId: DeleteChecksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Check or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete label from a check - tags: - - Checks - /api/v2/checks/{checkID}/query: - get: - operationId: GetChecksIDQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxResponse' - description: The check query requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Check not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a check query - tags: - - Checks - /api/v2/dashboards: - get: - description: | - Lists [dashboards](/influxdb/cloud/reference/glossary/#dashboard). - - #### Related guides - - - [Manage dashboards](/influxdb/cloud/visualize-data/dashboards/). - operationId: GetDashboards - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Descending' - - description: | - The maximum number of [dashboards](/influxdb/cloud/reference/glossary/#dashboard) to return. - Default is `20`. - The minimum is `-1` and the maximum is `100`. - in: query - name: limit - schema: - default: 20 - maximum: 100 - minimum: -1 - type: integer - - description: A user ID. Only returns [dashboards](/influxdb/cloud/reference/glossary/#dashboard) where the specified user has the `owner` role. - in: query - name: owner - schema: - type: string - - description: The column to sort by. - in: query - name: sortBy - schema: - enum: - - ID - - CreatedAt - - UpdatedAt - type: string - - description: | - A list of dashboard IDs. - Returns only the specified [dashboards](/influxdb/cloud/reference/glossary/#dashboard). - If you specify `id` and `owner`, only `id` is used. - in: query - name: id - schema: - items: - type: string - type: array - - description: | - An organization ID. - Only returns [dashboards](/influxdb/cloud/reference/glossary/#dashboard) that belong to the specified - [organization](/influxdb/cloud/reference/glossary/#organization). - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns [dashboards](/influxdb/cloud/reference/glossary/#dashboard) that belong to the specified - [organization](/influxdb/cloud/reference/glossary/#organization). - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboards' - description: Success. The response body contains dashboards. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List dashboards - tags: - - Dashboards - post: - operationId: PostDashboards - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateDashboardRequest' - description: Dashboard to create - required: true - responses: - '201': - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Dashboard' - - $ref: '#/components/schemas/DashboardWithViewProperties' - description: Success. The dashboard is created. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}: - delete: - operationId: DeleteDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a dashboard - tags: - - Dashboards - get: - operationId: GetDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: If `properties`, includes the cell view properties in the response. - in: query - name: include - required: false - schema: - enum: - - properties - type: string - responses: - '200': - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Dashboard' - - $ref: '#/components/schemas/DashboardWithViewProperties' - description: Retrieve a single dashboard - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a dashboard - tags: - - Dashboards - patch: - operationId: PatchDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - cells: - $ref: '#/components/schemas/CellWithViewProperties' - description: optional, when provided will replace all existing cells with the cells provided - description: - description: optional, when provided will replace the description - type: string - name: - description: optional, when provided will replace the name - type: string - title: PatchDashboardRequest - type: object - description: Patching of a dashboard - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboard' - description: Updated dashboard - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/cells: - post: - operationId: PostDashboardsIDCells - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateCell' - description: Cell that will be added - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Cell' - description: Cell successfully added - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a dashboard cell - tags: - - Cells - - Dashboards - put: - 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' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Cells' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboard' - description: Replaced dashboard cells - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Replace cells in a dashboard - tags: - - Cells - - Dashboards - /api/v2/dashboards/{dashboardID}/cells/{cellID}: - delete: - operationId: DeleteDashboardsIDCellsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to delete. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to delete. - in: path - name: cellID - required: true - schema: - type: string - responses: - '204': - description: Cell successfully deleted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a dashboard cell - tags: - - 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. - operationId: PatchDashboardsIDCellsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to update. - in: path - name: cellID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CellUpdate' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Cell' - description: Updated dashboard cell - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update the non-positional information related to a cell - tags: - - Cells - - Dashboards - /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: - get: - operationId: GetDashboardsIDCellsIDView - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The cell ID. - in: path - name: cellID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/View' - description: A dashboard cells view - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve the view for a cell - tags: - - Cells - - Dashboards - - Views - patch: - operationId: PatchDashboardsIDCellsIDView - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to update. - in: path - name: cellID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/View' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/View' - description: Updated cell view - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update the view for a cell - tags: - - Cells - - Dashboards - - Views - /api/v2/dashboards/{dashboardID}/labels: - get: - operationId: GetDashboardsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a dashboard - tags: - - Dashboards - post: - operationId: PostDashboardsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/labels/{labelID}: - delete: - operationId: DeleteDashboardsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/members: - get: - operationId: GetDashboardsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of users who have member privileges for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboard members - tags: - - Dashboards - post: - operationId: PostDashboardsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Added to dashboard members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/members/{userID}: - delete: - operationId: DeleteDashboardsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/owners: - get: - operationId: GetDashboardsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of users who have owner privileges for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboard owners - tags: - - Dashboards - post: - operationId: PostDashboardsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Added to dashboard owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/owners/{userID}: - delete: - operationId: DeleteDashboardsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a dashboard - tags: - - Dashboards - /api/v2/dbrps: - get: - description: | - Lists database retention policy (DBRP) mappings. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) - operationId: GetDBRPs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Only returns DBRP mappings for the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns DBRP mappings for the specified organization. - in: query - name: org - schema: - type: string - - description: | - A DBPR mapping ID. - Only returns the specified DBRP mapping. - in: query - name: id - schema: - type: string - - description: | - A bucket ID. - Only returns DBRP mappings that belong to the specified bucket. - in: query - name: bucketID - schema: - type: string - - description: Specifies filtering on default - in: query - name: default - schema: - type: boolean - - description: | - A database. - Only returns DBRP mappings that belong to the 1.x database. - in: query - name: db - schema: - type: string - - description: | - A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). - Specifies the 1.x retention policy to filter on. - in: query - name: rp - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - - bucketID: 4d4d9d5b61dee751 - database: example_database_1 - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - - bucketID: 4d4d9d5b61dee751 - database: example_database_2 - default: false - id: 0a3cbcde20e38000 - orgID: bea7ea952287f70d - retention_policy: example_retention_policy - schema: - $ref: '#/components/schemas/DBRPs' - description: Success. The response body contains a list of database retention policy mappings. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The request has one or more invalid parameters. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List database retention policy mappings - tags: - - DBRPs - post: - description: | - Creates a database retention policy (DBRP) mapping and returns the mapping. - - Use this endpoint to add InfluxDB 1.x API compatibility to your - InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a - DBRP mapping in order to query and write using the InfluxDB 1.x API. - object. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) - operationId: PostDBRP - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPCreate' - description: | - The database retention policy mapping to add. - - Note that _`retention_policy`_ is a required parameter in the request body. - The value of _`retention_policy`_ can be any arbitrary `string` name or - value, with the default value commonly set as `autogen`. - The value of _`retention_policy`_ isn't a [retention_policy](/influxdb/cloud/reference/glossary/#retention-policy-rp) - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - bucketID: 4d4d9d5b61dee751 - database: example_database - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - schema: - $ref: '#/components/schemas/DBRP' - description: Created. The response body contains the database retention policy mapping. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The mapping in the request has one or more invalid IDs. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a database retention policy mapping - tags: - - DBRPs - x-codeSamples: - - label: 'cURL: create a database retention policy mapping' - lang: Shell - source: | - curl --request POST \ - "http://localhost:8086/api/v2/dbrp/" \ - --header 'Content-type: application/json' \ - --header "Authorization: Token INFLUXDB_TOKEN" \ - --data-binary @- << EOF - { \ - "bucketID": "INFLUXDB_BUCKET_ID", \ - "orgID": "INFLUXDB_ORG_ID", \ - "database": "database_name", \ - "default": true, \ - "retention_policy": "example_retention_policy_name" \ - } - EOF - /api/v2/dbrps/{dbrpID}: - delete: - description: | - Deletes the specified database retention policy (DBRP) mapping. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) - operationId: DeleteDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Only returns the specified DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '204': - description: Success. The delete is accepted. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a database retention policy - tags: - - DBRPs - get: - description: | - Retrieves the specified retention policy (DBRP) mapping. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) - operationId: GetDBRPsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Specifies the DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - bucketID: 4d4d9d5b61dee751 - database: example_database_1 - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - schema: - $ref: '#/components/schemas/DBRPGet' - description: Success. The response body contains the DBRP mapping. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a database retention policy mapping - tags: - - DBRPs - patch: - operationId: PatchDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Specifies the DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPUpdate' - description: | - Updates the database retention policy (DBRP) mapping and returns the mapping. - - Use this endpoint to modify the _retention policy_ (`retention_policy` property) of a DBRP mapping. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/cloud/reference/api/influxdb-1x/dbrp/) - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - bucketID: 4d4d9d5b61dee751 - database: example_database - default: false - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: example_retention_policy - schema: - $ref: '#/components/schemas/DBRPGet' - description: An updated mapping - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a database retention policy mapping - tags: - - DBRPs - x-codeSamples: - - label: 'cURL: Update a DBRP mapping' - lang: Shell - source: | - curl --request PATCH \ - "http://localhost:8086/api/v2/dbrp/DBRP_ID" \ - --header 'Content-type: application/json' \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data-binary @- << EOF - { - "default": true, - "retention_policy": "example_retention_policy_name" - } - EOF - /api/v2/delete: - post: - description: | - Deletes data from a bucket. - - Use this endpoint to delete points from a bucket in a specified time range. - - #### InfluxDB Cloud - - - Does the following when you send a delete request: - - 1. Validates the request and queues the delete. - 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. - 3. Handles the delete asynchronously and reaches eventual consistency. - - To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, - wait for a success response (HTTP `2xx` status code) before you send the next request. - - Because writes and deletes are asynchronous, your change might not yet be readable - when you receive the response. - - #### InfluxDB OSS - - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - - #### Required permissions - - - `write-buckets` or `write-bucket BUCKET_ID`. - - *`BUCKET_ID`* is the ID of the destination bucket. - - #### Rate limits (with InfluxDB Cloud) - - `write` rate limits apply. - For more information, see [limits and adjustable quotas](/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/) - and [deleted fields](https://docs.influxdata.com/flux/v0.x/stdlib/influxdata/influxdb/schema/measurementfieldkeys/). - operationId: PostDelete - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Deletes data from the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - Deletes data from the bucket in the specified organization. - - If you pass both `orgID` and `org`, they must both be valid. - in: query - name: org - schema: - description: The organization name or ID. - type: string - - description: | - A bucket name or ID. - Specifies the bucket to delete data from. - If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. - in: query - name: bucket - schema: - description: The bucket name or ID. - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Deletes data from the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - Deletes data from the bucket in the specified organization. - - If you pass both `orgID` and `org`, they must both be valid. - in: query - name: orgID - schema: - description: The organization ID. - type: string - - description: | - A bucket ID. - Specifies the bucket to delete data from. - If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. - in: query - name: bucketID - schema: - description: The bucket ID. - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DeletePredicateRequest' - description: | - Time range parameters and an optional **delete predicate expression**. - - To select points to delete within the specified time range, pass a - **delete predicate expression** in the `predicate` property of the request body. - If you don't pass a `predicate`, InfluxDB deletes all data with timestamps - in the specified time range. - - #### Related guides - - - [Delete data](/influxdb/cloud/write-data/delete-data/) - - Learn how to use [delete predicate syntax](/influxdb/cloud/reference/syntax/delete-predicate/). - required: true - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - - Validated and queued the request. - - Handles the delete asynchronously - the deletion might not have completed yet. - - An HTTP `2xx` status code acknowledges that the write or delete is queued. - To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, - wait for a response before you send the next request. - - Because writes are asynchronous, data might not yet be written - when you receive the response. - - #### InfluxDB OSS - - - Deleted the data. - '400': - content: - application/json: - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete data - tags: - - Data I/O endpoints - - Delete - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --header 'Content-Type: application/json' \ - --data '{ - "start": "2020-03-01T00:00:00Z", - "stop": "2020-11-14T00:00:00Z", - "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")" - }' - /api/v2/flags: - get: - description: | - Retrieves the feature flag key-value pairs configured for the InfluxDB - instance. - _Feature flags_ are configuration options used to develop and test - experimental InfluxDB features and are intended for internal use only. - - This endpoint represents the first step in the following three-step process - to configure feature flags: - - 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve - feature flags and their values. - 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/cloud/reference/config-options/#feature-flags). - 3. **Optional**: To confirm that your change is applied, do one of the following: - - - Send a request to this endpoint to retrieve the current feature flag values. - - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the - current runtime server configuration. - - #### Related guides - - - [InfluxDB configuration options](/influxdb/cloud/reference/config-options/) - operationId: GetFlags - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Flags' - description: Success. The response body contains feature flags. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve feature flags - tags: - - Config - /api/v2/labels: - get: - operationId: GetLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: Success. The response body contains a list of labels. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List all labels - tags: - - Labels - post: - operationId: PostLabels - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelCreateRequest' - description: The label to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The label was created. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Create a label - tags: - - Labels - /api/v2/labels/{labelID}: - delete: - operationId: DeleteLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Success. The delete was accepted. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a label - tags: - - Labels - get: - operationId: GetLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to update. - in: path - name: labelID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the label. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a label - tags: - - Labels - patch: - operationId: PatchLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to update. - in: path - name: labelID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelUpdate' - description: A label update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the updated label. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a label - tags: - - Labels + /api/v2/checks: {} + /api/v2/checks/{checkID}: {} + /api/v2/checks/{checkID}/labels: {} + /api/v2/checks/{checkID}/labels/{labelID}: {} + /api/v2/checks/{checkID}/query: {} + /api/v2/dashboards: {} + /api/v2/dashboards/{dashboardID}: {} + /api/v2/dashboards/{dashboardID}/cells: {} + /api/v2/dashboards/{dashboardID}/cells/{cellID}: {} + /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: {} + /api/v2/dashboards/{dashboardID}/labels: {} + /api/v2/dashboards/{dashboardID}/labels/{labelID}: {} + /api/v2/dashboards/{dashboardID}/members: {} + /api/v2/dashboards/{dashboardID}/members/{userID}: {} + /api/v2/dashboards/{dashboardID}/owners: {} + /api/v2/dashboards/{dashboardID}/owners/{userID}: {} + /api/v2/dbrps: {} + /api/v2/dbrps/{dbrpID}: {} + /api/v2/delete: {} + /api/v2/flags: {} + /api/v2/labels: {} + /api/v2/labels/{labelID}: {} /api/v2/maps/mapToken: get: operationId: getMapboxToken @@ -10594,8208 +6790,89 @@ paths: default: $ref: '#/components/responses/ServerError' summary: Get a mapbox token - /api/v2/me: - get: - operationId: GetMe - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: Success. The response body contains the currently authenticated user. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve the currently authenticated user - tags: - - Users - /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 - - - Doesn't let you manage user passwords through the API. - Use the InfluxDB Cloud user interface (UI) to update your password. - - #### Related endpoints - - - [Signin](#tag/Signin) - - [Signout](#tag/Signout) - - [Users](#tag/Users) - - #### Related guides - - - [InfluxDB Cloud - Change your password](/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: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: The new password. - required: true - responses: - '204': - description: Success. The password is updated. - '400': - description: | - Bad request. - - #### InfluxDB Cloud - - - Doesn't let you manage user passwords through the API; always responds with this status. - - #### InfluxDB OSS - - - Doesn't understand a value passed in the request. - '401': - $ref: '#/components/responses/AuthorizationError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication - security: - - BasicAuthentication: [] - summary: Update a password - tags: - - Users - /api/v2/notificationEndpoints: - get: - operationId: GetNotificationEndpoints - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show notification endpoints that belong to specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoints' - description: A list of notification endpoints - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all notification endpoints - tags: - - NotificationEndpoints - post: - operationId: CreateNotificationEndpoint - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostNotificationEndpoint' - description: Notification endpoint to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: Notification endpoint created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}: - delete: - operationId: DeleteNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a notification endpoint - tags: - - NotificationEndpoints - get: - operationId: GetNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: The notification endpoint requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification endpoint - tags: - - NotificationEndpoints - patch: - operationId: PatchNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpointUpdate' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: An updated notification endpoint - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification endpoint - tags: - - NotificationEndpoints - put: - operationId: PutNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: A new notification endpoint to replace the existing endpoint with - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: An updated notification endpoint - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}/labels: - get: - operationId: GetNotificationEndpointsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a notification endpoint - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a notification endpoint - tags: - - NotificationEndpoints - post: - operationId: PostNotificationEndpointIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the notification endpoint - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: - delete: - operationId: DeleteNotificationEndpointsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Endpoint or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationRules: - get: - operationId: GetNotificationRules - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show notification rules that belong to a specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - - description: Only show notifications that belong to the specific check ID. - in: query - name: checkID - schema: - type: string - - description: Only return notification rules that "would match" statuses which contain the tag key value pairs provided. - in: query - name: tag - schema: - example: env:prod - pattern: ^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRules' - description: A list of notification rules - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all notification rules - tags: - - NotificationRules - post: - operationId: CreateNotificationRule - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostNotificationRule' - description: Notification rule to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: Notification rule created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}: - delete: - operationId: DeleteNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a notification rule - tags: - - NotificationRules - get: - operationId: GetNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: The notification rule requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification rule - tags: - - NotificationRules - patch: - operationId: PatchNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRuleUpdate' - description: Notification rule update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: An updated notification rule - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification rule was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification rule - tags: - - NotificationRules - put: - operationId: PutNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: Notification rule update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: An updated notification rule - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification rule was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/labels: - get: - operationId: GetNotificationRulesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a notification rule - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a notification rule - tags: - - NotificationRules - post: - operationId: PostNotificationRuleIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the notification rule - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/labels/{labelID}: - delete: - operationId: DeleteNotificationRulesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Rule or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete label from a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/query: - get: - operationId: GetNotificationRulesIDQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxResponse' - description: The notification rule query requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Notification rule not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification rule query - tags: - - Rules - /api/v2/orgs: - get: - description: | - Lists [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. - - #### Related guides - - - [View organizations](/influxdb/cloud/organizations/view-orgs/) - operationId: GetOrgs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/Descending' - - description: | - An organization name. - Only returns the specified organization. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Only returns the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A user ID. - Only returns organizations where the specified user is a member or owner. - in: query - name: userID - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/orgs - orgs: - - createdAt: '2022-07-17T23:00:30.778487Z' - description: Example InfluxDB organization - id: INFLUX_ORG_ID - links: - buckets: /api/v2/buckets?org=INFLUX_ORG - dashboards: /api/v2/dashboards?org=INFLUX_ORG - labels: /api/v2/orgs/INFLUX_ORG_ID/labels - logs: /api/v2/orgs/INFLUX_ORG_ID/logs - members: /api/v2/orgs/INFLUX_ORG_ID/members - owners: /api/v2/orgs/INFLUX_ORG_ID/owners - secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets - self: /api/v2/orgs/INFLUX_ORG_ID - tasks: /api/v2/tasks?org=InfluxData - name: INFLUX_ORG - updatedAt: '2022-07-17T23:00:30.778487Z' - schema: - $ref: '#/components/schemas/Organizations' - description: Success. The response body contains a list of organizations. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List organizations - tags: - - Organizations - - Security and access endpoints - post: - 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: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostOrganizationRequest' - description: The organization to create. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-24T23:05:52.881317Z' - description: '' - id: INFLUX_ORG_ID - links: - buckets: /api/v2/buckets?org=INFLUX_ORG - dashboards: /api/v2/dashboards?org=INFLUX_ORG - labels: /api/v2/orgs/INFLUX_ORG_ID/labels - logs: /api/v2/orgs/INFLUX_ORG_ID/logs - members: /api/v2/orgs/INFLUX_ORG_ID/members - owners: /api/v2/orgs/INFLUX_ORG_ID/owners - secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets - self: /api/v2/orgs/INFLUX_ORG_ID - tasks: /api/v2/tasks?org=INFLUX_ORG - name: INFLUX_ORG - updatedAt: '2022-08-24T23:05:52.881318Z' - schema: - $ref: '#/components/schemas/Organization' - description: Created. The response body contains the organization information. - '400': - $ref: '#/components/responses/BadRequestError' - examples: - invalidRequest: - summary: The `name` field is missing from the request body. - value: - code: invalid - message: org name is empty - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create an organization - tags: - - Organizations - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/orgs \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "INFLUX_ORG", - "description: "Example InfluxDB organization" - }' - /api/v2/orgs/{orgID}: - delete: - description: | - Deletes an organization. - - Deleting an organization from InfluxDB Cloud can't be undone. - Once deleted, all data associated with the organization is removed. - - #### InfluxDB Cloud - - - Does the following when you send a delete request: - - 1. Validates the request and queues the delete. - 2. Returns an HTTP `204` status code if queued; _error_ otherwise. - 3. Handles the delete asynchronously. - - #### InfluxDB OSS - - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - - #### Limitations - - - Only one organization can be deleted per request. - - #### Related guides - - - [Delete organizations](/influxdb/cloud/organizations/delete-orgs/) - operationId: DeleteOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to delete. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - The organization is queued for deletion. - - #### InfluxDB OSS - - The organization is deleted. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested organization was not found. - value: - code: not found - message: org not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - InfluxDB can't find the organization. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete an organization - tags: - - Organizations - get: - description: | - Retrieves an organization. - - Use this endpoint to retrieve information for a specific organization. - - #### Related guides - - - [View organizations](/influxdb/cloud/organizations/view-orgs/) - operationId: GetOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to retrieve. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: | - Success. - The response body contains the organization information. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested organization wasn't found. - value: - code: not found - message: organization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Organization not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve an organization - tags: - - Organizations - - Security and access endpoints - patch: - description: | - Updates an organization. - - Use this endpoint to update properties - (`name`, `description`) of an organization. - - Updating an organizationโ€™s name affects all resources that reference the - organization by name, including the following: - - - Queries - - Dashboards - - Tasks - - Telegraf configurations - - Templates - - If you change an organization name, be sure to update the organization name - in these resources as well. - - #### Related Guides - - - [Update an organization](/influxdb/cloud/organizations/update-org/) - operationId: PatchOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to update. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchOrganizationRequest' - description: The organization update to apply. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: Success. The response body contains the updated organization. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/limits: - get: - operationId: GetOrgLimitsID - parameters: - - description: The ID of the organization. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - description: These are org limits similar to those configured in/by quartz. - properties: - limits: - $ref: '#/components/schemas/Limit' - links: - $ref: '#/components/schemas/Links' - type: object - description: Limits defined for the organization. - default: - $ref: '#/components/responses/GeneralServerError' - description: unexpected error - summary: Retrieve limits for an organization - tags: - - Limits - /api/v2/orgs/{orgID}/members: - get: - description: | - Lists 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-(API-tokens)) to assign user permissions. - - #### Limitations - - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `read-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve - members for. - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) - operationId: GetOrgsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to retrieve users for. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/orgs/055aa4783aa38398/members - users: - - id: 791df274afd48a83 - links: - self: /api/v2/users/791df274afd48a83 - name: example_user_1 - role: member - status: active - - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_2 - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. - The response body contains a list of all users within the organization. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested organization wasn't found. - value: - code: not found - message: 404 page not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - InfluxDB can't find the organization. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all members of an organization - tags: - - Organizations - - Security and access endpoints - post: - 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-(API-tokens)) to assign user permissions. - - #### Limitations - - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to. - - #### Related guides - - - [Manage users](/influxdb/cloud/users/) - - [Manage members](/influxdb/cloud/organizations/members/) - operationId: PostOrgsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - The user to add to the organization. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_1 - role: member - status: active - schema: - $ref: '#/components/schemas/ResourceMember' - description: | - Success. - The response body contains the user information. - '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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to an organization - tags: - - Organizations - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "id": "09cfb87051cbe000" - }' - /api/v2/orgs/{orgID}/members/{userID}: - delete: - description: | - Removes a member from an organization. - - Use this endpoint to remove a user's member privileges for an organization. - Removing member privileges removes the user's `read` and `write` permissions - from the organization. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an - owner from. - - #### Related guides - - - [Manage members](/influxdb/cloud/organizations/members/) - operationId: DeleteOrgsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The ID of the organization to remove a user from. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer a member of the organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from an organization - tags: - - Organizations - - Security and access endpoints - /api/v2/orgs/{orgID}/owners: - get: - description: | - Lists all owners of an organization. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Required permissions - - - `read-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a - list of owners from. - operationId: GetOrgsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to list owners for. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/orgs/055aa4783aa38398/owners - users: - - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_2 - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of organization owners - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Organization not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of an organization - tags: - - Organizations - - Security and access endpoints - post: - description: | - Adds an owner to an organization. - - Use this endpoint to assign the organization `owner` role to a user. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - operationId: PostOrgsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization that you want to add an owner for. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - examples: - successResponse: - value: - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_1 - role: owner - status: active - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: The user to add as an owner of the organization. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: | - Success. The user is an owner of the organization. - The response body contains the owner with role and user detail. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to an organization - tags: - - Organizations - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "id": "09cfb87051cbe000" - }' - /api/v2/orgs/{orgID}/owners/{userID}: - delete: - description: | - Removes an [owner](/influxdb/cloud/reference/glossary/#owner) from - the organization. - - Organization owners have permission to delete organizations and remove user and member - permissions from the organization. - - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to - remove an owner from. - - #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) - operationId: DeleteOrgsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to remove. - in: path - name: userID - required: true - schema: - type: string - - description: | - The ID of the organization to remove an owner from. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer an owner of the organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from an organization - tags: - - Organizations - - Security and access endpoints - /api/v2/orgs/{orgID}/secrets: - get: - operationId: GetOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SecretKeysResponse' - description: A list of all secret keys - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all secret keys for an organization - tags: - - Secrets - - Security and access endpoints - patch: - operationId: PatchOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Secrets' - description: Secret key value pairs to update/add - required: true - responses: - '204': - description: Keys successfully patched - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update secrets in an organization - tags: - - Secrets - /api/v2/orgs/{orgID}/secrets/{secretID}: - delete: - operationId: DeleteOrgsIDSecretsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - - description: The secret ID. - in: path - name: secretID - required: true - schema: - type: string - responses: - '204': - description: Keys successfully deleted - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Delete a secret from an organization - tags: - - Secrets - - Security and access endpoints - /api/v2/orgs/{orgID}/secrets/delete: - post: - deprecated: true - operationId: PostOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SecretKeys' - description: Secret key to delete - required: true - responses: - '204': - description: Keys successfully patched - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete secrets from an organization - tags: - - Secrets - - Security and access endpoints - /api/v2/orgs/{orgID}/usage: - get: - operationId: GetOrgUsageID - parameters: - - description: The ID of the organization. - in: path - name: orgID - required: true - schema: - type: string - - description: | - Earliest time to include in results. - 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: | - Latest time to include in results. - For more information about timestamps, see [Manipulate timestamps with Flux](/influxdb/cloud/query-data/flux/manipulate-timestamps/). - in: query - name: stop - required: false - schema: - format: unix timestamp - type: integer - - description: return raw usage data - in: query - name: raw - required: false - schema: - default: false - type: boolean - responses: - '200': - 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 - type: string - description: Usage data - headers: - Content-Encoding: - 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. - enum: - - gzip - - identity - type: string - default: - $ref: '#/components/responses/GeneralServerError' - description: unexpected error - summary: Retrieve usage for an organization - tags: - - Usage - /ping: - get: - description: | - Retrieves the status and InfluxDB version of the instance. - - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. - - #### InfluxDB Cloud - - - Isn't versioned and doesn't return `X-Influxdb-Version` in the headers. - - #### Related guides - - - [Influx ping](/influxdb/cloud/reference/cli/influx/ping/) - operationId: GetPing - responses: - '204': - description: | - Success. - Headers contain InfluxDB version information. - headers: - X-Influxdb-Build: - description: | - The type of InfluxDB build. - schema: - type: string - X-Influxdb-Version: - description: | - The version of InfluxDB. - - #### InfluxDB Cloud - - Doesn't return version. - schema: - type: integer - servers: [] - summary: Get the status of the instance - tags: - - Ping - - System information endpoints - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "http://localhost:8086/ping" - head: - description: | - Returns the status and InfluxDB version of the instance. - - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. - - #### InfluxDB Cloud - - - Isn't versioned and doesn't return `X-Influxdb-Version` in the headers. - - #### Related guides - - - [Influx ping](/influxdb/cloud/reference/cli/influx/ping/) - operationId: HeadPing - responses: - '204': - description: | - Success. - Headers contain InfluxDB version information. - headers: - X-Influxdb-Build: - description: The type of InfluxDB build. - schema: - type: string - X-Influxdb-Version: - description: | - The version of InfluxDB. - - #### InfluxDB Cloud - - Doesn't return version. - schema: - type: integer - servers: [] - summary: Get the status of the instance - tags: - - Ping - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request HEAD "http://localhost:8086/ping" - /api/v2/query: - post: - description: | - Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a bucket. - - #### Rate limits (with InfluxDB Cloud) - - `read` rate limits apply. - For more information, see [limits and adjustable quotas](/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/) - operationId: PostQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - 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. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - enum: - - application/json - - application/vnd.flux - type: string - - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - in: query - name: orgID - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - example: | - from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement") - schema: - type: string - description: Flux query or specification to execute - responses: - '200': - content: - application/csv: - example: | - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 - schema: - 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. - schema: - default: identity - description: | - The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - Trace-Id: - description: The trace ID, if generated, of the request. - schema: - description: Trace ID of a request. - type: string - '400': - content: - application/json: - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](/influxdb/cloud/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Query data - tags: - - Data I/O endpoints - - Query - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ - --header 'Content-Type: application/vnd.flux' \ - --header 'Accept: application/csv \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --data 'from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement")' - /api/v2/query/analyze: - post: - description: | - Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax - errors and returns the list of errors. - - In the following sample query, `from()` is missing the property key. - - ```json - { "query": "from(: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")", - "type": "flux" - } - ``` - - If you pass this in a request to the `/api/v2/analyze` endpoint, - InfluxDB returns an `errors` list that contains an error object for the missing key. - - #### Limitations - - - The endpoint doesn't validate values in the query--for example: - - - The following sample query has correct syntax, but contains an incorrect `from()` property key: - - ```json - { "query": "from(foo: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")", - "type": "flux" - } - ``` - - If you pass this in a request to the `/api/v2/analyze` endpoint, - InfluxDB returns an empty `errors` list. - operationId: PostQueryAnalyze - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - description: Flux query to analyze - responses: - '200': - content: - application/json: - examples: - missingQueryPropertyKey: - description: | - Returns an error object if the Flux query is missing a property key. - - The following sample query is missing the _`bucket`_ property key: - - ```json - { - "query": "from(: \"iot_center\")\ - ... - } - ``` - summary: Missing property key error - value: - errors: - - character: 0 - column: 6 - line: 1 - message: missing property key - schema: - $ref: '#/components/schemas/AnalyzeQueryResponse' - description: | - Success. - The response body contains the list of `errors`. - If the query syntax is valid, the endpoint returns an empty `errors` list. - '400': - content: - application/json: - examples: - invalidJSONStringValue: - description: If the request body contains invalid JSON, returns `invalid` and problem detail. - summary: Invalid JSON - value: - code: invalid - message: 'invalid json: invalid character ''\'''' looking for beginning of value' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the problem. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - default: - content: - application/json: - examples: - emptyJSONObject: - description: | - If the request body contains an empty JSON object, returns `internal error`. - summary: Empty JSON object in request body - value: - code: internal error - message: An internal error has occurred - check server logs - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - headers: - X-Influx-Error: - description: A string that describes the problem. - schema: - type: string - X-Influx-Reference: - description: The numeric reference code for the error type. - schema: - type: integer - X-Platform-Error-Code: - description: The reason for the error. - schema: - example: internal error - type: string - summary: Analyze a Flux query - tags: - - Query - x-codeSamples: - - label: 'cURL: Analyze a Flux query' - lang: Shell - source: | - curl -v --request POST \ - "http://localhost:8086/api/v2/query/analyze" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header 'Content-type: application/json' \ - --header 'Accept: application/json' \ - --data-binary @- << EOF - { "query": "from(bucket: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")", - "type": "flux" - } - EOF - /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) - for the query. - - Use this endpoint for deep query analysis such as debugging unexpected query - results. - - A Flux query AST provides a semantic, tree-like representation with contextual - information about the query. The AST illustrates how the query is distributed - into different components for execution. - - #### Limitations - - - The endpoint doesn't validate values in the query--for example: - - The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: - - ```js - from(foo: "iot_center") - |> range(start: -90d) - |> filter(fn: (r) => r._measurement == "environment") - ``` - - The following sample JSON shows how to pass the query in the request body: - - ```js - from(foo: "iot_center") - |> range(start: -90d) - |> filter(fn: (r) => r._measurement == "environment") - ``` - - The following code sample shows how to pass the query as JSON in the request body: - - ```json - { "query": "from(foo: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")" - } - ``` - - Passing this to `/api/v2/query/ast` will return a successful response - with a generated AST. - operationId: PostQueryAst - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LanguageRequest' - description: The Flux query to analyze. - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - ast: - files: - - body: - - expression: - argument: - argument: - arguments: - - location: - end: - column: 25 - line: 1 - source: 'bucket: "example-bucket"' - start: - column: 6 - line: 1 - properties: - - key: - location: - end: - column: 12 - line: 1 - source: bucket - start: - column: 6 - line: 1 - name: bucket - type: Identifier - location: - end: - column: 25 - line: 1 - source: 'bucket: "example-bucket"' - start: - column: 6 - line: 1 - type: Property - value: - location: - end: - column: 25 - line: 1 - source: '"example-bucket"' - start: - column: 14 - line: 1 - type: StringLiteral - value: example-bucket - type: ObjectExpression - callee: - location: - end: - column: 5 - line: 1 - source: from - start: - column: 1 - line: 1 - name: from - type: Identifier - location: - end: - column: 26 - line: 1 - source: 'from(bucket: "example-bucket")' - start: - column: 1 - line: 1 - type: CallExpression - call: - arguments: - - location: - end: - column: 46 - line: 1 - source: 'start: -5m' - start: - column: 36 - line: 1 - properties: - - key: - location: - end: - column: 41 - line: 1 - source: start - start: - column: 36 - line: 1 - name: start - type: Identifier - location: - end: - column: 46 - line: 1 - source: 'start: -5m' - start: - column: 36 - line: 1 - type: Property - value: - argument: - location: - end: - column: 46 - line: 1 - source: 5m - start: - column: 44 - line: 1 - type: DurationLiteral - values: - - magnitude: 5 - unit: m - location: - end: - column: 46 - line: 1 - source: '-5m' - start: - column: 43 - line: 1 - operator: '-' - type: UnaryExpression - type: ObjectExpression - callee: - location: - end: - column: 35 - line: 1 - source: range - start: - column: 30 - line: 1 - name: range - type: Identifier - location: - end: - column: 47 - line: 1 - source: 'range(start: -5m)' - start: - column: 30 - line: 1 - type: CallExpression - location: - end: - column: 47 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m)' - start: - column: 1 - line: 1 - type: PipeExpression - call: - arguments: - - location: - end: - column: 108 - line: 1 - source: 'fn: (r) => r._measurement == "example-measurement"' - start: - column: 58 - line: 1 - properties: - - key: - location: - end: - column: 60 - line: 1 - source: fn - start: - column: 58 - line: 1 - name: fn - type: Identifier - location: - end: - column: 108 - line: 1 - source: 'fn: (r) => r._measurement == "example-measurement"' - start: - column: 58 - line: 1 - type: Property - value: - body: - left: - location: - end: - column: 83 - line: 1 - source: r._measurement - start: - column: 69 - line: 1 - object: - location: - end: - column: 70 - line: 1 - source: r - start: - column: 69 - line: 1 - name: r - type: Identifier - property: - location: - end: - column: 83 - line: 1 - source: _measurement - start: - column: 71 - line: 1 - name: _measurement - type: Identifier - type: MemberExpression - location: - end: - column: 108 - line: 1 - source: r._measurement == "example-measurement" - start: - column: 69 - line: 1 - operator: '==' - right: - location: - end: - column: 108 - line: 1 - source: '"example-measurement"' - start: - column: 87 - line: 1 - type: StringLiteral - value: example-measurement - type: BinaryExpression - location: - end: - column: 108 - line: 1 - source: (r) => r._measurement == "example-measurement" - start: - column: 62 - line: 1 - params: - - key: - location: - end: - column: 64 - line: 1 - source: r - start: - column: 63 - line: 1 - name: r - type: Identifier - location: - end: - column: 64 - line: 1 - source: r - start: - column: 63 - line: 1 - type: Property - value: null - type: FunctionExpression - type: ObjectExpression - callee: - location: - end: - column: 57 - line: 1 - source: filter - start: - column: 51 - line: 1 - name: filter - type: Identifier - location: - end: - column: 109 - line: 1 - source: 'filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 51 - line: 1 - type: CallExpression - location: - end: - column: 109 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 1 - line: 1 - type: PipeExpression - location: - end: - column: 109 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 1 - line: 1 - type: ExpressionStatement - imports: null - location: - end: - column: 109 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 1 - line: 1 - metadata: parser-type=rust - package: null - type: File - package: main - type: Package - schema: - $ref: '#/components/schemas/ASTResponse' - description: | - Success. - The response body contains an Abstract Syntax Tree (AST) of the Flux query. - '400': - content: - application/json: - examples: - invalidASTValue: - description: | - If the request body contains a missing property key in `from()`, - returns `invalid` and problem detail. - summary: Invalid AST - value: - code: invalid - message: 'invalid AST: loc 1:6-1:19: missing property key' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the problem. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - summary: Generate a query Abstract Syntax Tree (AST) - tags: - - Query - x-codeSamples: - - label: 'cURL: Analyze and generate AST for the query' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/query/ast" \ - --header 'Content-Type: application/json' \ - --header 'Accept: application/json' \ - --header "Authorization: Token INFLUX_TOKEN" \ - --data-binary @- << EOL - { - "query": "from(bucket: \"INFLUX_BUCKET_NAME\")\ - |> range(start: -5m)\ - |> filter(fn: (r) => r._measurement == \"example-measurement\")" - } - EOL - /api/v2/query/suggestions: - get: - description: | - Lists Flux query suggestions. Each suggestion contains a - [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - name and parameters. - - Use this endpoint to retrieve a list of Flux query suggestions used in the - InfluxDB Flux Query Builder. - - #### Limitations - - - When writing a query, avoid using `_functionName()` helper functions - exposed by this endpoint. Helper function names have an underscore (`_`) - prefix and aren't meant to be used directly in queries--for example: - - - To sort on a column and keep the top n records, use the - `top(n, columns=["_value"], tables=<-)` function instead of the `_sortLimit` - helper function. `top` uses `_sortLimit`. - - #### Related Guides - - - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - operationId: GetQuerySuggestions - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - funcs: - - name: _fillEmpty - params: - createEmpty: bool - tables: stream - - name: _highestOrLowest - params: - _sortLimit: function - column: invalid - groupColumns: array - 'n': invalid - reducer: function - tables: stream - - name: _hourSelection - params: - location: object - start: int - stop: int - tables: stream - timeColumn: string - - name: _sortLimit - params: - columns: array - desc: bool - 'n': int - tables: stream - - name: _window - params: - createEmpty: bool - every: duration - location: object - offset: duration - period: duration - startColumn: string - stopColumn: string - tables: stream - timeColumn: string - - name: aggregateWindow - params: - column: invalid - createEmpty: bool - every: duration - fn: function - location: object - offset: duration - period: duration - tables: stream - timeDst: string - timeSrc: string - - name: bool - params: - v: invalid - - name: bottom - params: - columns: array - 'n': int - tables: stream - - name: buckets - params: - host: string - org: string - orgID: string - token: string - - name: bytes - params: - v: invalid - - name: cardinality - params: - bucket: string - bucketID: string - host: string - org: string - orgID: string - predicate: function - start: invalid - stop: invalid - token: string - - name: chandeMomentumOscillator - params: - columns: array - 'n': int - tables: stream - - name: columns - params: - column: string - tables: stream - - name: contains - params: - set: array - value: invalid - - name: count - params: - column: string - tables: stream - - name: cov - params: - 'on': array - pearsonr: bool - x: invalid - 'y': invalid - - name: covariance - params: - columns: array - pearsonr: bool - tables: stream - valueDst: string - - name: cumulativeSum - params: - columns: array - tables: stream - - name: derivative - params: - columns: array - initialZero: bool - nonNegative: bool - tables: stream - timeColumn: string - unit: duration - - name: die - params: - msg: string - - name: difference - params: - columns: array - initialZero: bool - keepFirst: bool - nonNegative: bool - tables: stream - - name: display - params: - v: invalid - - name: distinct - params: - column: string - tables: stream - - name: doubleEMA - params: - 'n': int - tables: stream - - name: drop - params: - columns: array - fn: function - tables: stream - - name: duplicate - params: - as: string - column: string - tables: stream - - name: duration - params: - v: invalid - - name: elapsed - params: - columnName: string - tables: stream - timeColumn: string - unit: duration - - name: exponentialMovingAverage - params: - 'n': int - tables: stream - - name: fill - params: - column: string - tables: stream - usePrevious: bool - value: invalid - - name: filter - params: - fn: function - onEmpty: string - tables: stream - - name: findColumn - params: - column: string - fn: function - tables: stream - - name: findRecord - params: - fn: function - idx: int - tables: stream - - name: first - params: - column: string - tables: stream - - name: float - params: - v: invalid - - name: from - params: - bucket: string - bucketID: string - host: string - org: string - orgID: string - token: string - - name: getColumn - params: - column: string - - name: getRecord - params: - idx: int - - name: group - params: - columns: array - mode: string - tables: stream - - name: highestAverage - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: highestCurrent - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: highestMax - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: histogram - params: - bins: array - column: string - countColumn: string - normalize: bool - tables: stream - upperBoundColumn: string - - name: histogramQuantile - params: - countColumn: string - minValue: float - quantile: float - tables: stream - upperBoundColumn: string - valueColumn: string - - name: holtWinters - params: - column: string - interval: duration - 'n': int - seasonality: int - tables: stream - timeColumn: string - withFit: bool - - name: hourSelection - params: - location: object - start: int - stop: int - tables: stream - timeColumn: string - - name: increase - params: - columns: array - tables: stream - - name: int - params: - v: invalid - - name: integral - params: - column: string - interpolate: string - tables: stream - timeColumn: string - unit: duration - - name: join - params: - method: string - 'on': array - tables: invalid - - name: kaufmansAMA - params: - column: string - 'n': int - tables: stream - - name: kaufmansER - params: - 'n': int - tables: stream - - name: keep - params: - columns: array - fn: function - tables: stream - - name: keyValues - params: - keyColumns: array - tables: stream - - name: keys - params: - column: string - tables: stream - - name: last - params: - column: string - tables: stream - - name: length - params: - arr: array - - name: limit - params: - 'n': int - offset: int - tables: stream - - name: linearBins - params: - count: int - infinity: bool - start: float - width: float - - name: logarithmicBins - params: - count: int - factor: float - infinity: bool - start: float - - name: lowestAverage - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: lowestCurrent - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: lowestMin - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: map - params: - fn: function - mergeKey: bool - tables: stream - - name: max - params: - column: string - tables: stream - - name: mean - params: - column: string - tables: stream - - name: median - params: - column: string - compression: float - method: string - tables: stream - - name: min - params: - column: string - tables: stream - - name: mode - params: - column: string - tables: stream - - name: movingAverage - params: - 'n': int - tables: stream - - name: now - params: {} - - name: pearsonr - params: - 'on': array - x: invalid - 'y': invalid - - name: pivot - params: - columnKey: array - rowKey: array - tables: stream - valueColumn: string - - name: quantile - params: - column: string - compression: float - method: string - q: float - tables: stream - - name: range - params: - start: invalid - stop: invalid - tables: stream - - name: reduce - params: - fn: function - identity: invalid - tables: stream - - name: relativeStrengthIndex - params: - columns: array - 'n': int - tables: stream - - name: rename - params: - columns: invalid - fn: function - tables: stream - - name: sample - params: - column: string - 'n': int - pos: int - tables: stream - - name: set - params: - key: string - tables: stream - value: string - - name: skew - params: - column: string - tables: stream - - name: sort - params: - columns: array - desc: bool - tables: stream - - name: spread - params: - column: string - tables: stream - - name: stateCount - params: - column: string - fn: function - tables: stream - - name: stateDuration - params: - column: string - fn: function - tables: stream - timeColumn: string - unit: duration - - name: stateTracking - params: - countColumn: string - durationColumn: string - durationUnit: duration - fn: function - tables: stream - timeColumn: string - - name: stddev - params: - column: string - mode: string - tables: stream - - name: string - params: - v: invalid - - name: sum - params: - column: string - tables: stream - - name: tableFind - params: - fn: function - tables: stream - - name: tail - params: - 'n': int - offset: int - tables: stream - - name: time - params: - v: invalid - - name: timeShift - params: - columns: array - duration: duration - tables: stream - - name: timeWeightedAvg - params: - tables: stream - unit: duration - - name: timedMovingAverage - params: - column: string - every: duration - period: duration - tables: stream - - name: to - params: - bucket: string - bucketID: string - fieldFn: function - host: string - measurementColumn: string - org: string - orgID: string - tables: stream - tagColumns: array - timeColumn: string - token: string - - name: toBool - params: - tables: stream - - name: toFloat - params: - tables: stream - - name: toInt - params: - tables: stream - - name: toString - params: - tables: stream - - name: toTime - params: - tables: stream - - name: toUInt - params: - tables: stream - - name: today - params: {} - - name: top - params: - columns: array - 'n': int - tables: stream - - name: tripleEMA - params: - 'n': int - tables: stream - - name: tripleExponentialDerivative - params: - 'n': int - tables: stream - - name: truncateTimeColumn - params: - tables: stream - timeColumn: invalid - unit: duration - - name: uint - params: - v: invalid - - name: union - params: - tables: array - - name: unique - params: - column: string - tables: stream - - name: wideTo - params: - bucket: string - bucketID: string - host: string - org: string - orgID: string - tables: stream - token: string - - name: window - params: - createEmpty: bool - every: duration - location: object - offset: duration - period: duration - startColumn: string - stopColumn: string - tables: stream - timeColumn: string - - name: yield - params: - name: string - tables: stream - schema: - $ref: '#/components/schemas/FluxSuggestions' - description: | - Success. - 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`. - summary: Invalid URL - value: | - Moved Permanently - schema: - properties: - body: - description: Response message with URL of requested resource. - readOnly: true - type: string - description: | - Moved Permanently. - InfluxData has moved the URL of the endpoint. - Use `/api/v2/query/suggestions` (without a trailing slash). - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - summary: List Flux query suggestions - tags: - - Query - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "INFLUX_URL/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 - requested function. - - Use this endpoint to pass a branching suggestion (a Flux function name) and - retrieve the parameters of the requested function. - - #### Limitations - - - Use `/api/v2/query/suggestions/{name}` (without a trailing slash). - `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a - HTTP `301 Moved Permanently` status. - - - The function `name` must exist and must be spelled correctly. - - #### Related Guides - - - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - operationId: GetQuerySuggestionsName - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name. - in: path - name: name - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - name: sum - params: - column: string - tables: stream - schema: - $ref: '#/components/schemas/FluxSuggestion' - description: | - Success. - The response body contains the function name and parameters. - '500': - content: - application/json: - examples: - internalError: - description: | - The requested function doesn't exist. - summary: Invalid function - value: - code: internal error - message: An internal error has occurred - schema: - $ref: '#/components/schemas/Error' - description: | - Internal server error. - The value passed for _`name`_ may have been misspelled. - summary: Retrieve a query suggestion for a branching suggestion - tags: - - Query - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "INFLUX_URL/api/v2/query/suggestions/sum/" \ - --header "Accept: application/json" \ - --header "Authorization: Token INFLUX_API_TOKEN" - /api/v2/resources: - get: - operationId: GetResources - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - items: - type: string - type: array - description: All resources targets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: List all known resources - tags: - - Resources - - System information endpoints - /api/v2/scripts: - get: - description: | - Lists [scripts](/influxdb/cloud/api-guide/api-invokable-scripts/). - - #### Related guides - - - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) - operationId: GetScripts - parameters: - - description: | - The offset for pagination. - The number of records to skip. - - For more information about pagination parameters, see [Pagination](/influxdb/cloud/api/#tag/Pagination). - in: query - name: offset - required: false - schema: - minimum: 0 - type: integer - - description: | - The maximum number of scripts to return. Default is `100`. - in: query - name: limit - required: false - schema: - default: 100 - maximum: 500 - minimum: 0 - type: integer - - description: The script name. Lists scripts with the specified name. - in: query - name: name - required: false - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - scripts: - - createdAt: '2022-07-17T23:49:45.731237Z' - description: find the last point from Sample Bucket - id: 09afa3b220fe4000 - language: flux - name: getLastPointFromSampleBucket - orgID: bea7ea952287f70d - 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 - id: 09afa23ff13e4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:43:26.660308Z' - schema: - $ref: '#/components/schemas/Scripts' - description: | - Success. - The response body contains the list of scripts. - '400': - content: - application/json: - examples: - invalidSyntaxError: - summary: Query parameter contains invalid syntax. - value: - code: 3 - details: [] - 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': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: List scripts - tags: - - Data I/O endpoints - - Invokable Scripts - x-codeSamples: - - label: 'cURL: retrieves the first 100 scripts.' - lang: Shell - source: | - curl --request GET "INFLUX_URL/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/) - and returns the script. - - #### Related guides - - - [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: - application/json: - schema: - $ref: '#/components/schemas/ScriptCreateRequest' - description: The script to create. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-07-17T23:43:26.660308Z' - description: getLastPoint finds the last point in a bucket - id: 09afa23ff13e4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:43:26.660308Z' - schema: - $ref: '#/components/schemas/Script' - description: | - Success. - The response body contains the script and its metadata. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '422': - content: - application/json: - examples: - uniquenessError: - description: | - A script with the same `name` exists. - value: - code: conflict - message: uniqueness violation - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Create a script - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "INFLUX_URL/api/v2/scripts" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "getLastPoint", - "description": "getLastPoint finds the last point in a bucket", - "orgID": "INFLUX_ORG_ID", - "script": "from(bucket: INFLUX_BUCKET) |> range(start: -7d) |> limit(n:1)", - "language": "flux" - }' - /api/v2/scripts/{scriptID}: - delete: - description: | - Deletes a [script](/influxdb/cloud/api-guide/api-invokable-scripts/) and all associated records. - - #### Limitations - - - You can delete only one script per request. - - If the script ID you provide doesn't exist for the organization, InfluxDB - responds with an HTTP `204` status code. - - #### Related Guides - - - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) - operationId: DeleteScriptsID - parameters: - - description: | - A script ID. - Deletes the specified script. - in: path - name: scriptID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The script is queued for deletion. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a script - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl -X 'DELETE' \ - "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header 'Accept: application/json' - get: - description: | - Retrieves a [script](/influxdb/cloud/api-guide/api-invokable-scripts/). - - #### Related Guides - - - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) - operationId: GetScriptsID - parameters: - - description: | - A script ID. - Retrieves the specified script. - in: path - name: scriptID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-07-17T23:49:45.731237Z' - description: getLastPoint finds the last point in a bucket - id: 09afa3b220fe4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-17T23:49:45.731237Z' - schema: - $ref: '#/components/schemas/Script' - description: Success. The response body contains the script. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested script was not found. - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/ServerError' - description: Internal server error. - summary: Retrieve a script - tags: - - Data I/O endpoints - - Invokable Scripts - patch: - description: | - Updates an invokable script. - - Use this endpoint to modify values for script properties (`description` and `script`). - - To update a script, pass an object that contains the updated key-value pairs. - - #### Limitations - - - If you send an empty request body, the script will neither update nor - store an empty script, but InfluxDB will respond with an HTTP `200` status - code. - - #### Related Guides - - - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) - operationId: PatchScriptsID - parameters: - - description: | - A script ID. - Updates the specified script. - in: path - name: scriptID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScriptUpdateRequest' - description: | - An object that contains the updated script properties to apply. - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-07-17T23:49:45.731237Z' - description: get last point from new bucket - id: 09afa3b220fe4000 - language: flux - name: getLastPoint - orgID: bea7ea952287f70d - script: 'from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)' - updatedAt: '2022-07-19T22:27:23.185436Z' - schema: - $ref: '#/components/schemas/Script' - description: Success. The response body contains the updated script. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested script wasn't found. - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/ServerError' - description: Internal server error - summary: Update a script - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl -X 'PATCH' \ - "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" - --header "Content-Type: application/json" - --data '{ - "description": "get last point from new bucket", - "script": "from(bucket: updatedBucket) |> range(start: -7d) |> limit(n:1)", "language": "flux" - }' - /api/v2/scripts/{scriptID}/invoke: - post: - 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 the _`mybucket`_ parameter: - - ```json - { - "params": { - "mybucket": "air_sensor" - } - } - ``` - - #### Related guides - - - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) - operationId: PostScriptsIDInvoke - parameters: - - description: | - A script ID. - Runs the specified script. - in: path - name: scriptID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScriptInvocationParams' - responses: - '200': - content: - text/csv: - examples: - successResponse: - 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' - description: | - Success. - The response body contains the result of the script execution. - '400': - content: - application/json: - examples: - invalidParameters: - summary: The parameters passed to the script are invalid. - value: - code: invalid - message: invalid parameters provided - schema: - $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: | - The reason for the error. - schema: - example: invalid - type: string - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - bucketNotFound: - description: InfluxDB can't find the requested bucket. - summary: | - Bucket not found - value: - code: not found - message: 'failed to initialize execute state: could not find bucket "test-bucket"' - scriptNotFound: - description: InfluxDB can't find the requested script. - summary: | - Script not found - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: not found - type: string - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Invoke a script - tags: - - Data I/O endpoints - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "INFLUX_URL/api/v2/scripts/SCRIPT_ID/invoke" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header 'Accept: application/csv' \ - --header 'Content-Type: application/json' \ - --data '{ - "params": { - "mybucket": "air_sensor" - } - }' - /api/v2/scripts/{scriptID}/params: - get: - description: | - Analyzes a script and determines required parameters. - Find all `params` keys referenced in a script and return a list - of keys. If it is possible to determine the type of the value - from the context then the type is also returned -- for example: - - The following sample script contains a _`mybucket`_ parameter : - - ```json - "script": "from(bucket: params.mybucket) - |> range(start: -7d) - |> limit(n:1)" - ``` - - Requesting the parameters using `GET /api/v2/scripts/SCRIPT_ID/params` - returns the following: - - ```json - { - "params": { - "mybucket": "string" - } - } - ``` - - The type name returned for a parameter will be one of: - - - `any` - - `bool` - - `duration` - - `float` - - `int` - - `string` - - `time` - - `uint` - - The type name `any` is used when the type of a parameter cannot - be determined from the context, or the type is determined to - be a structured type such as an array or record. - - #### Related guides - - - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) - operationId: GetScriptsIDParams - parameters: - - description: | - A script ID. - The script to analyze for params. - in: path - name: scriptID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - params: - mybucket: string - schema: - $ref: '#/components/schemas/Params' - description: | - Success. - The response body contains the parameters found, along with their types. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - scriptNotFound: - description: InfluxDB can't find the requested script. - summary: | - Script not found - value: - code: not found - message: script "09afa3b220fe400" not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: not found - type: string - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error. - summary: Find script parameters. - tags: - - Invokable Scripts - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \ - --header "Authorization: Token INFLUX_TOKEN" - /api/v2/setup: - get: - 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' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/IsOnboarding' - description: Setup is allowed, true or false - summary: Retrieve setup status - tags: - - Setup - post: - description: Post an onboarding request to create an initial user, organization, and bucket. - operationId: PostSetup - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingRequest' - description: Source to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse' - description: The created default user, bucket, and organization - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Create an initial user, organization, and bucket - tags: - - Setup - /api/v2/setup/user: - post: - description: Post an onboarding request to create a new user, organization, and bucket. - operationId: PostSetupUser - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingRequest' - description: Source to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse' - description: The created default user, bucket, and organization. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Create a new user, organization, and bucket - tags: - - Setup - /api/v2/signin: - post: - 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 syntax and more information, see [Basic Authentication](#section/Authentication/BasicAuthentication) for - syntax and more information. - - If authentication is successful, InfluxDB creates a new session for the user - and then returns the session cookie in the `Set-Cookie` response header. - - InfluxDB stores user sessions in memory only. - They expire within ten minutes and during restarts of the InfluxDB instance. - - #### User sessions with authorizations - - - In InfluxDB Cloud, a user session inherits all the user's permissions for - the organization. - - In InfluxDB OSS, a user session inherits all the user's permissions for all - the organizations that the user belongs to. - - #### Related endpoints - - - [Signout](#tag/Signout) - operationId: PostSignin - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '204': - 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. - 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: Forbidden. The user account is disabled. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication. - security: - - BasicAuthentication: [] - summary: Create a user session. - tags: - - Security and access endpoints - - 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 a user session specified by a session cookie. - - Use this endpoint to expire a user session that was generated when the user - authenticated with the InfluxDB Developer Console (UI) or the `POST /api/v2/signin` endpoint. - - For example, the `POST /api/v2/signout` endpoint represents the third step - in the following three-step process - to authenticate a user, retrieve the `user` resource, and then expire the session: - - 1. Send a request with the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) - to the `POST /api/v2/signin` endpoint to create a user session and - generate a session cookie. - 2. Send a request to the `GET /api/v2/me` endpoint, passing the stored session cookie - from step 1 to retrieve user information. - 3. Send a request to the `POST /api/v2/signout` endpoint, passing the stored session - cookie to expire the session. - - _See the complete example in request samples._ - - InfluxDB stores user sessions in memory only. - If a user doesn't sign out, then the user session automatically expires within ten minutes or - during a restart of the InfluxDB instance. - - To learn more about cookies in HTTP requests, see - [Mozilla Developer Network (MDN) Web Docs, HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). - - #### Related endpoints - - - [Signin](#tag/Signin) - operationId: PostSignout - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '204': - description: Success. The session is expired. - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unauthorized. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The session expiry is unsuccessful. - summary: Expire a user session - tags: - - Security and access endpoints - - Signout - x-codeSamples: - - label: 'cURL: sign in a user, verify the user session, and then end the session' - lang: Shell - source: | - # The following example shows how to use cURL and the InfluxDB API - # to do the following: - # 1. Sign in a user with a username and password. - # 2. Check that the user session exists for the user. - # 3. Sign out the user to expire the session. - # 4. Check that the session is no longer active. - - # 1. Send a request to `POST /api/v2/signin` to sign in the user. - # In your request, pass the following: - # - # - `--user` option with basic authentication credentials. - # - `-c` option with a file path where cURL will write cookies. - - curl --request POST \ - -c ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/signin" \ - --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}" - - # 2. To check that a user session exists for the user in step 1, - # send a request to `GET /api/v2/me`. - # In your request, pass the `-b` option with the session cookie file path from step 1. - - curl --request GET \ - -b ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/me" - - # InfluxDB responds with the `user` resource. - - # 3. Send a request to `POST /api/v2/signout` to expire the user session. - # In your request, pass the `-b` option with the session cookie file path from step 1. - - curl --request POST \ - -b ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/signout" - - # If the user session is successfully expired, InfluxDB responds with - an HTTP `204` status code. - - # 4. To check that the user session is expired, call `GET /api/v2/me` again, - # passing the `-b` option with the cookie file path. - - curl --request GET \ - -b ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/me" - - # If the user session is expired, InfluxDB responds with an HTTP `401` status code. - /api/v2/stacks: - get: - description: | - Lists installed InfluxDB stacks. - - To limit stacks in the response, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all installed stacks - for the organization. - - #### Related guides - - - [View InfluxDB stacks](/influxdb/cloud/influxdb-templates/stacks/). - operationId: ListStacks - parameters: - - description: | - An organization ID. - Only returns stacks owned by the specified [organization](/influxdb/cloud/reference/glossary/#organization). - - #### InfluxDB Cloud - - - Doesn't require this parameter; - InfluxDB only returns resources allowed by the API token. - in: query - name: orgID - required: true - schema: - type: string - - description: | - A stack name. - Finds stack `events` with this name and returns the stacks. - - Repeatable. - To filter for more than one stack name, - repeat this parameter with each name--for example: - - - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` - examples: - findStackByName: - summary: Find stacks with the event name - value: project-stack-0 - in: query - name: name - schema: - type: string - - description: | - A stack ID. - Only returns the specified stack. - - Repeatable. - To filter for more than one stack ID, - repeat this parameter with each ID--for example: - - - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` - examples: - findStackByID: - summary: Find a stack with the ID - value: 09bd87cd33be3000 - in: query - name: stackID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - properties: - stacks: - items: - $ref: '#/components/schemas/Stack' - type: array - type: object - description: Success. The response body contains the list of stacks. - '400': - content: - application/json: - examples: - orgIdMissing: - summary: The orgID query parameter is missing - value: - code: invalid - message: 'organization id[""] is invalid: id must have a length of 16 bytes' - orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in the header - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List installed stacks - tags: - - Templates - post: - description: | - Creates or initializes a stack. - - Use this endpoint to _manually_ initialize a new stack with the following - optional information: - - - Stack name - - Stack description - - URLs for template manifest files - - To automatically create a stack when applying templates, - use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). - - #### Required permissions - - - `write` permission for the organization - - #### Related guides - - - [Initialize an InfluxDB stack](/influxdb/cloud/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](/influxdb/cloud/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). - operationId: CreateStack - requestBody: - content: - application/json: - schema: - properties: - description: - type: string - name: - type: string - orgID: - type: string - urls: - items: - type: string - type: array - title: PostStackRequest - type: object - description: The stack to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Success. Returns the newly created stack. - '401': - $ref: '#/components/responses/AuthorizationError' - '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: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a stack - tags: - - Templates - /api/v2/stacks/{stack_id}: - delete: - operationId: DeleteStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - - description: The identifier of the organization. - in: query - name: orgID - required: true - schema: - type: string - responses: - '204': - description: The stack and its associated resources were deleted. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a stack and associated resources - tags: - - Templates - get: - operationId: ReadStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a stack - tags: - - Templates - patch: - operationId: UpdateStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - additionalResources: - items: - properties: - kind: - type: string - resourceID: - type: string - templateMetaName: - type: string - required: - - kind - - resourceID - type: object - type: array - description: - nullable: true - type: string - name: - nullable: true - type: string - templateURLs: - items: - type: string - nullable: true - type: array - title: PatchStackRequest - type: object - description: The stack to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the updated stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a stack - tags: - - Templates - /api/v2/stacks/{stack_id}/uninstall: - post: - operationId: UninstallStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the uninstalled stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Uninstall a stack - tags: - - Templates - /api/v2/tasks: - get: - description: | - Lists [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`. - - #### Related guide - - - [Process data with InfluxDB tasks](/influxdb/cloud/process-data/) - operationId: GetTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task name. - Only returns [tasks](/influxdb/cloud/reference/glossary/#task) with the specified name. - Different tasks may have the same name. - in: query - name: name - schema: - type: string - - description: | - A task ID. - Only returns [task](/influxdb/cloud/reference/glossary/#task) created after the specified task. - in: query - name: after - schema: - type: string - - description: | - A user ID. - Only returns [tasks](/influxdb/cloud/reference/glossary/#task) owned by the specified [user](/influxdb/cloud/reference/glossary/#user). - in: query - name: user - schema: - type: string - - description: | - An organization name. - Only returns [tasks](/influxdb/cloud/reference/glossary/#task) owned by the specified [organization](/influxdb/cloud/reference/glossary/#organization). - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Only returns tasks owned by the specified [organization](/influxdb/cloud/reference/glossary/#organization). - in: query - name: orgID - schema: - type: string - - description: | - A task status. - Only returns [tasks](/influxdb/cloud/reference/glossary/#task) that have the specified status. - in: query - name: status - schema: - enum: - - active - - inactive - type: string - - 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. - examples: - all: - summary: Return all tasks, without pagination. - value: '-1' - minPaginated: - summary: Return a maximum of 50 tasks. - value: '50' - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: -1 - type: integer - - description: The number of records to skip. - in: query - name: offset - required: false - schema: - default: 0 - minimum: 0 - type: integer - - description: | - The sort field. - Specifies the task property used to sort records in the list. - Default is `name`. - - The parameter has one supported value: `name`. - in: query - name: sortBy - required: false - schema: - enum: - - name - type: string - - description: | - A task type. - Specifies the level of detail for [tasks](/influxdb/cloud/reference/glossary/#task) in the response. - Default is `system`. - - The default (`system`) response contains all the metadata properties for tasks. - To reduce the response size, set the `type` parameter to `basic` (`type=basic`) - to omit some task properties (`flux`, `createdAt`, `updatedAt`). - in: query - name: type - required: false - schema: - default: '' - enum: - - basic - - system - type: string - - description: | - A script ID. - Only returns tasks that use the specified [invokable script](#tag/Invokable-Scripts). - in: query - name: scriptID - schema: - type: string - responses: - '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: | - Success. - The response body contains the list of tasks. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List tasks - tags: - - Data I/O endpoints - - Tasks - x-codeSamples: - - label: 'cURL: all tasks, basic output' - lang: Shell - source: | - curl INFLUX_URL/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/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a script. - - #### Related guides - - - [Get started with tasks](/influxdb/cloud/process-data/get-started/) - - [Create a task](/influxdb/cloud/process-data/manage-tasks/create-task/) - - [Common tasks](/influxdb/cloud/process-data/common-tasks/) - - [Task configuration options](/influxdb/cloud/process-data/task-options/) - operationId: PostTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' - schema: - $ref: '#/components/schemas/TaskCreateRequest' - description: | - In the request body, provide the task. - - Set one of the following properties to provide the script that the task runs: - - `flux` - - `scriptID` - - If you set the `scriptID` property, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, you must provide the `task` configuration option - in the Flux script. - - See [task configuration options](/influxdb/cloud/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't use `flux` and `scriptID` in the same task. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains a `tasks` list with the task. - '400': - content: - application/json: - examples: - fluxAndScriptError: - summary: The request body can't contain both flux and scriptID - value: - code: invalid - message: 'failed to decode request: can not provide both scriptID and flux' - missingFluxError: - summary: The request body requires either a flux parameter or scriptID parameter - value: - code: invalid - message: 'failed to decode request: flux required' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB Cloud - - - Returns this error if the task doesn't contain the `flux` property - or the `scriptID` property. - - Returns this error if the task contains `flux` _and_ `scriptID` - properties. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a task - tags: - - Data I/O endpoints - - Tasks - /api/v2/tasks/{taskID}: - delete: - description: | - Deletes the specified [task](/influxdb/cloud/reference/glossary/#task) - and all associated records (task runs, logs, and labels). - Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task's `status` - property to `inactive`. - operationId: DeleteTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to delete. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The task and task runs are deleted. Scheduled runs are canceled. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a task - tags: - - Tasks - get: - description: | - Retrieves the specified [task](/influxdb/cloud/reference/glossary/#task). - operationId: GetTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to retrieve. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a task - tags: - - Data I/O endpoints - - Tasks - patch: - description: | - Updates the specified [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. - - To activate or inactivate a task, set the `status` property. - The `status` property set to `inactive` cancels scheduled runs and prevents manual runs of the task. - - #### Related guides - - - [Update a task](/influxdb/cloud/process-data/manage-tasks/update-task/) - - [Task configuration options](/influxdb/cloud/process-data/task-options/) - operationId: PatchTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to update. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - TaskWithScriptID: - $ref: '#/components/examples/TaskWithScriptRequest' - schema: - $ref: '#/components/schemas/TaskUpdateRequest' - description: | - In the request body, provide the task properties to update. - To provide the script that the task runs, - set either the `flux` property or the `scriptID` property. - - If you set `scriptID`, you can set the following properties to configure the task: - - `cron` - - `every` - - `offset` - - `scriptParameters` - - If you set the `flux` property, provide the `task` configuration option - in the Flux script. - - See [task configuration options](/influxdb/cloud/process-data/task-options/) - for detail and examples. - - #### Limitations: - - - You can't set `flux` and `scriptID` properties for the same task--for - example, if you set the `scriptID` property, then InfluxDB sets the `flux` property - to an empty string (`""`). - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains the updated task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels: - get: - description: | - Lists all labels for a task. - - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. - operationId: GetTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the task to retrieve labels for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: Success. The response body contains a list of all labels for the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List labels for a task - tags: - - Tasks - post: - description: | - Adds a label to a [task](/influxdb/cloud/reference/glossary/#task). - - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. - operationId: PostTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to label. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: | - In the request body, provide an object that specifies the label. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the label. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Add a label to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels/{labelID}: - delete: - description: | - Deletes a label from a [task](/influxdb/cloud/reference/glossary/#task). - operationId: DeleteTasksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to delete the label from. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A label ID. - Specifies the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Success. The label is deleted. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a label from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/logs: - get: - description: | - Lists all log events for a [task](/influxdb/cloud/reference/glossary/#task). - - When a task runs, InfluxDB creates a `run` record in the taskโ€™s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. - - Use this endpoint to retrieve only the log events for a task, - without additional task metadata. - operationId: GetTasksIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](/influxdb/cloud/reference/glossary/#task) to retrieve logs for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - taskFailure: - summary: Events for a failed task run - value: - events: - - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 - time: '2022-07-13T07:06:54.198167Z' - - message: Completed(failed) - runID: 09a946fc3167d000 - time: '2022-07-13T07:07:13.104037Z' - - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' - runID: 09a946fc3167d000 - time: '2022-07-13T08:24:37.115323Z' - taskSuccess: - summary: Events for 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)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - schema: - $ref: '#/components/schemas/Logs' - description: | - Success. - The response body contains an `events` list with logs for the task. - Each log event `message` contains detail about the event. - If a task run fails, InfluxDB logs an event with the reason for the failure. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List logs for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members: - get: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Lists all users that have the `member` role for the specified [task](/influxdb/cloud/reference/glossary/#task). - operationId: GetTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to retrieve members for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. The response body contains a list of `users` that have - the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all task members - tags: - - Tasks - post: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Adds a specified user to members of the specified [task](/influxdb/cloud/reference/glossary/#task) and then returns - the member. - operationId: PostTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](/influxdb/cloud/reference/glossary/#task) ID. - Specifies the task for the member. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members/{userID}: - delete: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes a member from a [task](/influxdb/cloud/reference/glossary/#task). - operationId: DeleteTasksIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: A task ID. Specifies the [task](/influxdb/cloud/reference/glossary/#task) to remove the member from. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The member is removed. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners: - get: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Lists all users that have the `owner` role for the specified task. - operationId: GetTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the task to retrieve owners for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: | - Success. - The response contains a list of `users` that have the `owner` role for the task. - - If the task has no owners, the response contains an empty `users` array. - '401': - $ref: '#/components/responses/AuthorizationError' - '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: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a task - tags: - - Tasks - post: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Adds a specified user to owners of the specified task and then returns the - owner. - - Use this endpoint to create a _resource owner_ for the task. - A _resource owner_ is a user with `role: owner` for a specific resource. - operationId: PostTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) for the owner. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. - required: true - responses: - '201': - content: - application/json: - examples: - createdOwner: - summary: User has the owner role for the resource - value: - id: 0772396d1f411000 - links: - logs: /api/v2/users/0772396d1f411000/logs - self: /api/v2/users/0772396d1f411000 - name: USER_NAME - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceOwner' - description: | - Created. The task `owner` role is assigned to the user. - The response body contains the resource owner with - role and user detail. - '401': - $ref: '#/components/responses/AuthorizationError' - '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: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners/{userID}: - delete: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes an owner from a [task](/influxdb/cloud/reference/glossary/#task). - operationId: DeleteTasksIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the owner to remove from the [task](/influxdb/cloud/reference/glossary/#task). - in: path - name: userID - required: true - schema: - type: string - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to remove the owner from. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The owner is removed. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/runs: - get: - description: | - Lists runs for the specified [task](/influxdb/cloud/process-data/). - - To limit which task runs are returned, pass query parameters in your request. - If you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. - operationId: GetTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to - to list runs for. - in: path - name: taskID - required: true - schema: - type: string - - description: A task run ID. Only returns runs created after the specified run. - in: query - name: after - schema: - type: string - - description: | - Limits the number of task runs returned. Default is `100`. - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: 1 - type: integer - - description: | - A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. - in: query - name: afterTime - schema: - format: date-time - type: string - - description: | - A timestamp ([RFC3339 date/time format](/influxdb/cloud/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. - in: query - name: beforeTime - schema: - format: date-time - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Runs' - description: Success. The response body contains the list of task runs. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List runs for a task - tags: - - Tasks - post: - description: | - Schedules a task run to start immediately, ignoring scheduled runs. - - Use this endpoint to manually start a task run. - Scheduled runs will continue to run as scheduled. - This may result in concurrently running tasks. - - To _retry_ a previous run (and avoid creating a new run), - use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. - operationId: PostTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to - to run. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RunManually' - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Run' - description: Success. The run is scheduled to start. - '400': - content: - application/json: - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Start a task run, overriding the schedule - tags: - - Data I/O endpoints - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}: - delete: - description: | - Cancels a running [task](/influxdb/cloud/reference/glossary/#task). - - Use this endpoint to cancel a running task. - - #### InfluxDB Cloud - - - Doesn't support this operation. - operationId: DeleteTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) to - to cancel. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A task run ID. - Specifies the task run to cancel. - in: path - name: runID - required: true - schema: - type: string - responses: - '204': - description: | - Success. The `DELETE` is accepted and the run will be cancelled. - - #### InfluxDB Cloud - - - Doesn't support this operation. - - Doesn't return this status. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Method not allowed. - - #### InfluxDB Cloud - - - Always returns this error; doesn't support cancelling tasks. - - #### InfluxDB OSS - - - Doesn't return this error. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Cancel a running task - tags: - - Tasks - get: - description: | - Retrieves the specified run for the specified [task](/influxdb/cloud/reference/glossary/#task). - - Use this endpoint to retrieve detail and logs for a specific task run. - operationId: GetTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) - that the task run belongs to. - in: path - name: taskID - required: true - schema: - type: string - - description: A task run ID. Specifies the run to retrieve. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - runSuccess: - summary: A successful task run. - value: - finishedAt: '2022-07-18T14:46:07.308254Z' - id: 09b070dadaa7d000 - links: - logs: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs - retry: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry - self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 - task: /api/v2/tasks/0996e56b2f378000 - log: - - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - requestedAt: '2022-07-18T14:46:06Z' - scheduledFor: '2022-07-18T14:46:06Z' - startedAt: '2022-07-18T14:46:07.16222Z' - status: success - taskID: 0996e56b2f378000 - schema: - $ref: '#/components/schemas/Run' - description: Success. The response body contains the task run. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a run for a task. - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/logs: - get: - description: | - Lists all logs for a task run. - A log is a list of run events with `runID`, `time`, and `message` properties. - - Use this endpoint to help analyze [task](/influxdb/cloud/reference/glossary/#task) performance and troubleshoot failed task runs. - operationId: GetTasksIDRunsIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](/influxdb/cloud/reference/glossary/#task) that the run belongs to. - in: path - name: taskID - required: true - schema: - type: string - - description: A run ID. Specifies the task run to list logs for. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - taskFailure: - summary: Events for a failed task. - value: - events: - - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 - time: '2022-07-13T07:06:54.198167Z' - - message: Completed(failed) - runID: 09a946fc3167d000 - time: '2022-07-13T07:07:13.104037Z' - - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' - runID: 09a946fc3167d000 - time: '2022-07-13T08:24:37.115323Z' - taskSuccess: - summary: Events for 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)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - schema: - $ref: '#/components/schemas/Logs' - description: | - 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. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List logs for a run - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/retry: - post: - description: | - Queues a [task](/influxdb/cloud/reference/glossary/#task) run to - retry and then returns the scheduled run. - - To manually start a _new_ task run, use the - [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. - operationId: PostTasksIDRunsIDRetry - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/cloud/reference/glossary/#task) that the task run belongs to. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A 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 - schema: - type: string - requestBody: - content: - application/json; charset=utf-8: - schema: - type: object - responses: - '200': - content: - application/json: - examples: - retryTaskRun: - summary: A task run scheduled to retry - value: - id: 09d60ffe08738000 - links: - logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs - retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry - self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 - task: /api/v2/tasks/09a776832f381000 - requestedAt: '2022-08-16T20:05:11.84145Z' - scheduledFor: '2022-08-15T00:00:00Z' - status: scheduled - taskID: 09a776832f381000 - schema: - $ref: '#/components/schemas/Run' - description: Success. The response body contains the queued run. - '400': - content: - application/json: - examples: - inactiveTask: - summary: Can't retry an inactive task - value: - code: invalid - message: 'failed to retry run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - InfluxDB may return this error for the following reasons: - - - The task has `status: inactive`. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retry a task run - tags: - - Tasks - /api/v2/telegraf/plugins: - get: - operationId: GetTelegrafPlugins - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The type of plugin desired. - in: query - name: type - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPlugins' - description: A list of Telegraf plugins. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf plugins - tags: - - Telegraf Plugins - /api/v2/telegrafs: - get: - operationId: GetTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID the Telegraf config belongs to. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegrafs' - description: A list of Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf configurations - tags: - - Telegrafs - post: - operationId: PostTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPluginRequest' - description: Telegraf configuration to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: Telegraf configuration created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}: - delete: - operationId: DeleteTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a Telegraf configuration - tags: - - Telegrafs - get: - operationId: GetTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - - in: header - name: Accept - required: false - schema: - default: application/toml - enum: - - application/toml - - application/json - - application/octet-stream - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - application/octet-stream: - example: |- - [agent] - interval = "10s" - schema: - type: string - application/toml: - example: |- - [agent] - interval = "10s" - schema: - type: string - description: Telegraf configuration details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a Telegraf configuration - tags: - - Telegrafs - put: - operationId: PutTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPluginRequest' - description: Telegraf configuration update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: An updated Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels: - get: - operationId: GetTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels/{labelID}: - delete: - operationId: DeleteTelegrafsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Telegraf config not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members: - get: - operationId: GetTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of Telegraf config members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members/{userID}: - delete: - operationId: DeleteTelegrafsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners: - get: - operationId: GetTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: Returns Telegraf configuration owners as a ResourceOwners list - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a Telegraf configuration - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners/{userID}: - delete: - operationId: DeleteTelegrafsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a Telegraf config - tags: - - Telegrafs - /api/v2/templates/apply: - post: - description: | - Applies a template to - 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. - 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. - To provide custom values for environment references, pass the _`envRefs`_ - property in the request body. - For more information and examples, see how to - [define environment references](/influxdb/cloud/influxdb-templates/use/#define-environment-references). - - - Some templates may contain queries that use - [secrets](/influxdb/cloud/security/secrets/). - To provide custom secret values, pass the _`secrets`_ property - in the request body. - Don't expose secret values in templates. - For more information, see [how to pass secrets when installing a template](/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template). - - #### Required permissions - - - `write` permissions for resource types in the template. - - #### Rate limits (with InfluxDB Cloud) - - - Adjustable service quotas apply. - For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Use templates](/influxdb/cloud/influxdb-templates/use/) - - [Stacks](/influxdb/cloud/influxdb-templates/stacks/) - operationId: ApplyTemplate - requestBody: - content: - application/json: - examples: - skipKindAction: - summary: Skip all bucket and task resources in the provided templates - value: - actions: - - action: skipKind - properties: - kind: Bucket - - action: skipKind - properties: - kind: Task - orgID: INFLUX_ORG_ID - templates: - - contents: - - '[object Object]': null - skipResourceAction: - summary: Skip specific resources in the provided templates - value: - actions: - - action: skipResource - properties: - kind: Label - resourceTemplateName: foo-001 - - action: skipResource - properties: - kind: Bucket - resourceTemplateName: bar-020 - - action: skipResource - properties: - kind: Bucket - resourceTemplateName: baz-500 - orgID: INFLUX_ORG_ID - templates: - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Bucket - metadata: - name: baz-500 - templateObjectEnvRefs: - summary: envRefs for template objects - value: - envRefs: - docker-bucket: MY_DOCKER_BUCKET - docker-spec-1: MY_DOCKER_SPEC - linux-cpu-label: MY_CPU_LABEL - orgID: INFLUX_ORG_ID - templates: - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Label - metadata: - name: - envRef: - key: linux-cpu-label - spec: - color: '#326BBA' - name: inputs.cpu - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Bucket - metadata: - name: - envRef: - key: docker-bucket - schema: - $ref: '#/components/schemas/TemplateApply' - application/x-jsonnet: - schema: - $ref: '#/components/schemas/TemplateApply' - text/yml: - schema: - $ref: '#/components/schemas/TemplateApply' - description: | - Parameters for applying templates. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: | - Success. - The template dry run succeeded. - The response body contains a resource diff of changes that the - template would have made if installed. - No resources were created or updated. - The diff and summary won't contain IDs for resources - that didn't exist at the time of the dry run. - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: | - Success. - The template applied successfully. - The response body contains the stack ID, a diff, and a summary. - The diff compares the initial state to the state after the template installation. - The summary contains newly created resources. - '422': - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/TemplateSummary' - - properties: - code: - type: string - message: - type: string - required: - - message - - code - type: object - description: | - Unprocessable entity. - - - The error may indicate one of the following problems: - - - The template failed validation. - - You passed a parameter combination that InfluxDB doesn't support. - '500': - content: - application/json: - examples: - createExceedsQuota: - summary: 'InfluxDB Cloud: Creating resource would exceed quota.' - value: - code: internal error - message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\"" - schema: - $ref: '#/components/schemas/Error' - description: | - Internal server error. - - #### InfluxDB Cloud - - - Returns this error if creating one of the template - resources (bucket, dashboard, task, user) exceeds your planโ€™s - adjustable service quotas. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Apply or dry-run a template - tags: - - Templates - x-codeSamples: - - label: 'cURL: Dry run with a remote template' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF - { - "dryRun": true, - "orgID": "INFLUX_ORG_ID", - "remotes": [ - { - "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml" - } - ] - } - EOF - - label: 'cURL: Apply with secret values' - lang: Shell - source: | - curl "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF | jq . - { - "orgID": "INFLUX_ORG_ID", - "secrets": { - "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL" - }, - "remotes": [ - { - "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml" - } - ] - } - EOF - - label: 'cURL: Apply template objects with environment references' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF - { "orgID": "INFLUX_ORG_ID", - "envRefs": { - "linux-cpu-label": "MY_CPU_LABEL", - "docker-bucket": "MY_DOCKER_BUCKET", - "docker-spec-1": "MY_DOCKER_SPEC" - }, - "templates": [ - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Label", - "metadata": { - "name": { - "envRef": { - "key": "linux-cpu-label" - } - } - }, - "spec": { - "color": "#326BBA", - "name": "inputs.cpu" - } - }] - }, - "templates": [ - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Label", - "metadata": { - "name": { - "envRef": { - "key": "linux-cpu-label" - } - } - }, - "spec": { - "color": "#326BBA", - "name": "inputs.cpu" - } - }] - }, - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Bucket", - "metadata": { - "name": { - "envRef": { - "key": "docker-bucket" - } - } - } - }] - } - ] - } - EOF - /api/v2/templates/export: - post: - operationId: ExportTemplate - requestBody: - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/TemplateExportByID' - - $ref: '#/components/schemas/TemplateExportByName' - description: Export resources as an InfluxDB template. - required: false - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Template' - application/x-yaml: - schema: - $ref: '#/components/schemas/Template' - description: The template was created successfully. Returns the newly created template. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Export a new template - tags: - - Templates - /api/v2/users: - get: - description: | - Lists [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` | - - *`USER_ID`* is the 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`. - - #### 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 - summary: List users - tags: - - Security and access endpoints - - Users - post: - description: | - (InfluxData internal use only) - - Creates and returns a [user](/influxdb/cloud/reference/glossary/#user) - that can access InfluxDB. - - #### InfluxDB Cloud - - - InfluxDB Cloud Doesn't let you manage users through the API. - Use the InfluxDB Cloud user interface (UI) to manage account information. - - #### Required permissions for InfluxDB Cloud - - | Action | Permission required | Restriction | - |:-------|:--------------------|:------------| - | Create user | Operator token | InfluxData internal use only | - - #### Related guides - - - [Manage users](/influxdb/cloud/organizations/users/) - operationId: PostUsers - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/User' - description: In the request body, provide the user. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: | - Success. - The response body contains the user. - '401': - content: - application/json: - schema: - $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: | - 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 - summary: Create a user - tags: - - 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 let you manage users through the API. - Use the InfluxDB Cloud user interface (UI) to manage account information. - - #### Required permissions - - | Action | Permission required | Restriction | - |:-------|:--------------------|:------------| - | Delete user | Operator token | InfluxData internal use only | - - #### Related guides - - - [Manage users](/influxdb/cloud/organizations/users/) - operationId: DeleteUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Deletes the specified [user](/influxdb/cloud/reference/glossary/#user). - in: path - name: userID - required: true - schema: - type: string - responses: - '204': - description: Success. The user is deleted. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a user - 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: | - A user ID. - Retrieves the specified [user](/influxdb/cloud/reference/glossary/#user). - in: path - name: userID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: Success. The response body contains the user. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Retrieve a user - tags: - - Users - patch: - description: | - (InfluxData internal use only) - - Updates a [user](/influxdb/cloud/reference/glossary/#user) and returns the user. - - #### InfluxDB Cloud - - - Doesn't let you manage users through the API. - Use the InfluxDB Cloud user interface (UI) to manage account information. - - #### Required permissions for InfluxDB Cloud - - | Action | Permission required | Restriction | - |:-------|:--------------------|:------------| - | Update user | Operator token | InfluxData internal use only | - - #### Related guides - - - [Manage users](/influxdb/cloud/organizations/users/) - operationId: PatchUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Updates the specified [user](/influxdb/cloud/reference/glossary/#user). - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/User' - description: The user update to apply. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: Success. The response body contains the updated user. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a user - tags: - - Users - /api/v2/users/{userID}/password: - post: - description: | - Updates a user password. - - #### InfluxDB Cloud - - - Doesn't allow you to manage user passwords through the API. - Use the InfluxDB Cloud user interface (UI) to update a password. - - #### Related guides - - - [InfluxDB Cloud - Change your password](/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 ID of the user to set the password for. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: The new password to set for the user. - required: true - responses: - '204': - description: Success. The password is updated. - '400': - 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: | - 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 - summary: Update a password - tags: - - Security and access endpoints - - Users - x-codeSamples: - - label: 'cURL: use HTTP POST 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' \ - --header "Authorization: Token INFLUX_TOKEN" \ - --data-binary @- << EOF - {"password": "NEW_USER_PASSWORD"} - EOF - put: - description: | - Updates a user password. - - Use this endpoint to let a user authenticate with - [Basic authentication credentials](#section/Authentication/BasicAuthentication) - and set a new password. - - #### InfluxDB Cloud - - - Doesn't allow you to manage user passwords through the API. - Use the InfluxDB Cloud user interface (UI) to update a password. - - #### Related guides - - - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) - - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) - operationId: PutUsersIDPassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to set the password for. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: The new password to set for the user. - required: true - responses: - '204': - description: Success. The password is updated. - '400': - 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: | - 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 -c ./cookie-file.tmp --request POST \ - "http://localhost:8086/api/v2/signin" \ - --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}" - - curl -b ./cookie-file.tmp --request PUT \ - "http://localhost:8086/api/v2/users/USER_ID/password" \ - --header 'Content-type: application/json' \ - --data-binary @- << EOF - {"password": "NEW_USER_PASSWORD"} - EOF - /api/v2/variables: - get: - operationId: GetVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the organization. - in: query - name: org - schema: - type: string - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variables' - description: A list of variables for an organization. - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: List all variables - tags: - - Variables - post: - operationId: PostVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable created - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Create a variable - tags: - - Variables - /api/v2/variables/{variableID}: - delete: - operationId: DeleteVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '204': - description: Variable deleted - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Delete a variable - tags: - - Variables - get: - operationId: GetVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable found - '404': - $ref: '#/components/responses/GeneralServerError' - description: Variable not found - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Retrieve a variable - tags: - - Variables - patch: - operationId: PatchVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Update a variable - tags: - - Variables - put: - operationId: PutVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to replace - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Replace a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels: - get: - operationId: GetVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a variable - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a variable - tags: - - Variables - post: - operationId: PostVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels/{labelID}: - delete: - operationId: DeleteVariablesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - - description: The label ID to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Variable not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a variable - tags: - - Variables - /api/v2/write: - post: - description: | - Writes data to a bucket. - - Use this endpoint to send data in [line protocol](/influxdb/cloud/reference/syntax/line-protocol/) format to InfluxDB. - - #### InfluxDB Cloud - - - Does the following when you send a write request: - - 1. Validates the request and queues the write. - 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. - 3. Handles the delete asynchronously and reaches eventual consistency. - - To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, - wait for a success response (HTTP `2xx` status code) before you send the next request. - - Because writes and deletes are asynchronous, your change might not yet be readable - when you receive the response. - - #### InfluxDB OSS - - - Validates the request and handles the write synchronously. - - If all points were written successfully, responds with HTTP `2xx` status code; - otherwise, returns the first line that failed. - - #### Required permissions - - - `write-buckets` or `write-bucket BUCKET_ID`. - - *`BUCKET_ID`* is the ID of the destination bucket. - - #### Rate limits (with InfluxDB Cloud) - - `write` rate limits apply. - For more information, see [limits and adjustable quotas](/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/) - operationId: PostWrite - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The compression applied to the line protocol in the request payload. - To send a GZIP payload, pass `Content-Encoding: gzip` header. - in: header - name: Content-Encoding - schema: - default: identity - description: | - Content coding. - Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - description: | - The format of the data in the request body. - 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. - enum: - - text/plain - - text/plain; charset=utf-8 - type: string - - description: | - The size of the entity-body, in bytes, sent to InfluxDB. - If the length is greater than the `max body` configuration option, - the server responds with status code `413`. - in: header - name: Content-Length - schema: - description: The length in decimal number of octets. - type: integer - - description: | - The content type that the client can understand. - Writes only return a response body if they fail--for example, - due to a formatting problem or quota limit. - - #### InfluxDB Cloud - - - Returns only `application/json` for format and limit errors. - - Returns only `text/html` for some quota limit errors. - - #### InfluxDB OSS - - - Returns only `application/json` for format and limit errors. - - #### Related guides - - - [Troubleshoot issues writing data](/influxdb/cloud/write-data/troubleshoot/) - in: header - name: Accept - schema: - default: application/json - description: Error content type. - enum: - - application/json - type: string - - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Writes data to the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - If you pass both `orgID` and `org`, they must both be valid. - - Writes data to the bucket in the specified organization. - in: query - name: org - required: true - schema: - description: The organization name or ID. - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Writes data to the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - If you pass both `orgID` and `org`, they must both be valid. - - Writes data to the bucket in the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A bucket name or ID. - InfluxDB writes all points in the batch to the specified bucket. - in: query - name: bucket - required: true - schema: - description: The bucket name or ID. - type: string - - description: The precision for unix timestamps in the line protocol batch. - in: query - name: precision - schema: - $ref: '#/components/schemas/WritePrecision' - requestBody: - content: - 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 - schema: - format: byte - type: string - description: | - In the request body, provide data in [line protocol format](/influxdb/cloud/reference/syntax/line-protocol/). - - To send compressed data, do the following: - - 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. - 2. In your request, send the compressed data and the - `Content-Encoding: gzip` header. - - #### Related guides - - - [Best practices for optimizing writes](/influxdb/cloud/write-data/best-practices/optimize-writes/) - required: true - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - - Validated and queued the request. - - Handles the write asynchronously - the write might not have completed yet. - - #### InfluxDB OSS - - - Successfully wrote all points in the batch. - - #### Related guides - - - [How to check for write errors](/influxdb/cloud/write-data/troubleshoot/) - '400': - content: - application/json: - examples: - measurementSchemaFieldTypeConflict: - summary: (Cloud) field type conflict thrown by an explicit bucket schema - value: - code: invalid - message: 'partial write error (2 written): unable to parse ''air_sensor,service=S1,sensor=L1 temperature="90.5",humidity=70.0 1632850122'': schema: field type for field "temperature" not permitted by schema; got String but expected Float' - orgNotFound: - summary: (OSS) organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/LineProtocolError' - description: | - Bad request. The response body contains detail about the error. - - InfluxDB returns this error if the line protocol data in the request is malformed. - The response body contains the first malformed line in the data, and indicates what was expected. - For partial writes, the number of points written and the number of points rejected are also included. - For more information, check the `rejected_points` measurement in your `_monitoring` bucket. - - #### InfluxDB Cloud - - - Returns this error for bucket schema conflicts. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '413': - content: - application/json: - examples: - dataExceedsSizeLimitOSS: - summary: InfluxDB OSS response - value: | - {"code":"request too large","message":"unable to read data: points batch is too large"} - schema: - $ref: '#/components/schemas/LineProtocolLengthError' - text/html: - examples: - dataExceedsSizeLimit: - summary: InfluxDB Cloud response - value: | - - 413 Request Entity Too Large - -

413 Request Entity Too Large

-
-
nginx
- - - schema: - type: string - description: | - The request payload is too large. - InfluxDB rejected the batch and did not write any data. - - #### InfluxDB Cloud: - - - Returns this error if the payload exceeds the 50MB size limit. - - Returns `Content-Type: text/html` for this error. - - #### InfluxDB OSS: - - - Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. - - Returns `Content-Type: application/json` for this error. - '429': - description: | - Too many requests. - - #### InfluxDB Cloud - - - Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits). - - For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. - - For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header. - - Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. - Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. - - #### InfluxDB OSS - - - Doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - '500': - $ref: '#/components/responses/InternalServerError' - '503': - description: | - Service unavailable. - - - Returns this error if - the server is temporarily unavailable to accept writes. - - Returns a `Retry-After` header that describes when to try the write again. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - default: - $ref: '#/components/responses/GeneralServerError' - summary: Write data - tags: - - Data I/O endpoints - - Write + /api/v2/me: {} + /api/v2/me/password: {} + /api/v2/notificationEndpoints: {} + /api/v2/notificationEndpoints/{endpointID}: {} + /api/v2/notificationEndpoints/{endpointID}/labels: {} + /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: {} + /api/v2/notificationRules: {} + /api/v2/notificationRules/{ruleID}: {} + /api/v2/notificationRules/{ruleID}/labels: {} + /api/v2/notificationRules/{ruleID}/labels/{labelID}: {} + /api/v2/notificationRules/{ruleID}/query: {} + /api/v2/orgs: {} + /api/v2/orgs/{orgID}: {} + /api/v2/orgs/{orgID}/limits: {} + /api/v2/orgs/{orgID}/members: {} + /api/v2/orgs/{orgID}/members/{userID}: {} + /api/v2/orgs/{orgID}/owners: {} + /api/v2/orgs/{orgID}/owners/{userID}: {} + /api/v2/orgs/{orgID}/secrets: {} + /api/v2/orgs/{orgID}/secrets/{secretID}: {} + /api/v2/orgs/{orgID}/secrets/delete: {} + /api/v2/orgs/{orgID}/usage: {} + /ping: {} + /api/v2/query: {} + /api/v2/query/analyze: {} + /api/v2/query/ast: {} + /api/v2/query/suggestions: {} + /api/v2/query/suggestions/{name}: {} + /api/v2/resources: {} + /api/v2/scripts: {} + /api/v2/scripts/{scriptID}: {} + /api/v2/scripts/{scriptID}/invoke: {} + /api/v2/scripts/{scriptID}/params: {} + /api/v2/setup: {} + /api/v2/setup/user: {} + /api/v2/signin: {} + /api/v2/signout: {} + /api/v2/stacks: {} + /api/v2/stacks/{stack_id}: {} + /api/v2/stacks/{stack_id}/uninstall: {} + /api/v2/tasks: {} + /api/v2/tasks/{taskID}: {} + /api/v2/tasks/{taskID}/labels: {} + /api/v2/tasks/{taskID}/labels/{labelID}: {} + /api/v2/tasks/{taskID}/logs: {} + /api/v2/tasks/{taskID}/members: {} + /api/v2/tasks/{taskID}/members/{userID}: {} + /api/v2/tasks/{taskID}/owners: {} + /api/v2/tasks/{taskID}/owners/{userID}: {} + /api/v2/tasks/{taskID}/runs: {} + /api/v2/tasks/{taskID}/runs/{runID}: {} + /api/v2/tasks/{taskID}/runs/{runID}/logs: {} + /api/v2/tasks/{taskID}/runs/{runID}/retry: {} + /api/v2/telegraf/plugins: {} + /api/v2/telegrafs: {} + /api/v2/telegrafs/{telegrafID}: {} + /api/v2/telegrafs/{telegrafID}/labels: {} + /api/v2/telegrafs/{telegrafID}/labels/{labelID}: {} + /api/v2/telegrafs/{telegrafID}/members: {} + /api/v2/telegrafs/{telegrafID}/members/{userID}: {} + /api/v2/telegrafs/{telegrafID}/owners: {} + /api/v2/telegrafs/{telegrafID}/owners/{userID}: {} + /api/v2/templates/apply: {} + /api/v2/templates/export: {} + /api/v2/users: {} + /api/v2/users/{userID}: {} + /api/v2/users/{userID}/password: {} + /api/v2/variables: {} + /api/v2/variables/{variableID}: {} + /api/v2/variables/{variableID}/labels: {} + /api/v2/variables/{variableID}/labels/{labelID}: {} + /api/v2/write: {} /legacy/authorizations: - get: - operationId: GetLegacyAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - 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 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 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 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 the specified name. - in: query - name: token - schema: - type: string - - description: | - An authorization ID. - Returns the specified legacy authorization. - in: query - name: authID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - properties: - authorizations: - items: - $ref: '#/components/schemas/Authorization' - type: array - links: - $ref: '#/components/schemas/Links' - readOnly: true - type: object - description: Success. The response body contains a list of legacy `authorizations`. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: List all legacy authorizations - tags: - - Legacy Authorizations - post: - 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. - - *`USER_ID`* is the ID of the user that you want to scope the authorization to. - operationId: PostLegacyAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LegacyAuthorizationPostRequest' - description: The legacy authorization to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: | - Created. The legacy authorization is created. - The response body contains the newly created legacy authorization. - '400': - $ref: '#/components/responses/ServerError' - description: Invalid request - '401': - content: - application/json: - examples: - unauthorizedWriteUsers: - summary: The token doesn't have the write:user permission - value: - code: unauthorized - message: write:users/08028e90933bf000 is unauthorized - schema: - properties: - code: - 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. - readOnly: true - type: string - description: | - Unauthorized. - The API token passed doesn't have the permissions necessary for the - request. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Create a legacy authorization - tags: - - Legacy Authorizations servers: - url: /private /legacy/authorizations/{authID}: - delete: - operationId: DeleteLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to delete. - in: path - name: authID - required: true - schema: - type: string - responses: - '204': - description: Legacy authorization deleted - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a legacy authorization - tags: - - Legacy Authorizations - get: - operationId: GetLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to get. - in: path - name: authID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Legacy authorization details - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Retrieve a legacy authorization - tags: - - Legacy Authorizations - patch: - operationId: PatchLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: Legacy authorization to update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: The active or inactive legacy authorization - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Update a legacy authorization to be active or inactive - tags: - - Legacy Authorizations servers: - url: /private /legacy/authorizations/{authID}/password: - post: - operationId: PostLegacyAuthorizationsIDPassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - password: - type: string - required: - - password - description: New password - required: true - responses: - '204': - description: Legacy authorization password set - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Set a legacy authorization password - tags: - - Legacy Authorizations servers: - url: /private - /query: - get: - description: Queries InfluxDB using InfluxQL. - operationId: GetLegacyQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Accept - schema: - default: application/json - 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). - 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. - in: header - name: Accept-Encoding - schema: - default: identity - description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - - description: The InfluxDB 1.x username to authenticate the request. - in: query - name: u - schema: - type: string - - description: The InfluxDB 1.x password to authenticate the request. - in: query - name: p - schema: - type: string - - 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/). - in: query - name: db - required: true - schema: - type: string - - 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/). - in: query - name: rp - schema: - type: string - - 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: | - 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. - in: query - name: epoch - schema: - enum: - - ns - - u - - ยต - - ms - - s - - m - - h - type: string - responses: - '200': - content: - application/csv: - schema: - $ref: '#/components/schemas/InfluxqlCsvResponse' - application/json: - schema: - $ref: '#/components/schemas/InfluxqlJsonResponse' - application/x-msgpack: - schema: - format: binary - type: string - text/csv: - schema: - $ref: '#/components/schemas/InfluxqlCsvResponse' - description: Query results - headers: - Content-Encoding: - description: Lists encodings (usually compression algorithms) that have been applied to the response payload. - schema: - default: identity - description: | - The content coding: - - `gzip`: compressed data - - `identity`: unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - Trace-Id: - description: The trace ID, if generated, of the request. - schema: - description: Trace ID of a request. - type: string - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](/influxdb/cloud/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: A non-negative decimal integer indicating the seconds to delay after the response is received. - schema: - format: int32 - type: integer - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Error processing query - summary: Query with the 1.x compatibility API - tags: - - Legacy Query - /write: - post: - operationId: PostLegacyWrite - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The InfluxDB 1.x username to authenticate the request. - in: query - name: u - schema: - type: string - - description: The InfluxDB 1.x password to authenticate the request. - in: query - name: p - schema: - type: string - - 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 - schema: - type: string - - description: Retention policy name. - in: query - name: rp - schema: - type: string - - description: Write precision. - in: query - name: precision - schema: - type: string - - 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. - enum: - - gzip - - identity - type: string - requestBody: - content: - text/plain: - schema: - type: string - description: Line protocol body - required: true - responses: - '204': - 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. - '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. - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: No token was sent and they are required. - '413': - content: - 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. - '429': - 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. - 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. - headers: - Retry-After: - description: A non-negative decimal integer indicating the seconds to delay after the response is received. - schema: - format: int32 - type: integer - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Write time series data into InfluxDB in a V1-compatible format - tags: - - Legacy Write + /query: {} + /write: {} security: - TokenAuthentication: [] servers: @@ -19102,7 +7179,7 @@ tags: Write time series data to [buckets](/influxdb/cloud/reference/glossary/#bucket). name: Write x-tagGroups: - - name: Overview + - name: Using the InfluxDB HTTP API tags: - Quick start - Authentication @@ -19110,8 +7187,6 @@ x-tagGroups: - Headers - Pagination - Response codes - - name: '' - tags: - Data I/O endpoints - Security and access endpoints - System information endpoints diff --git a/api-docs/cloud/swaggerV1Compat.yml b/api-docs/cloud/swaggerV1Compat.yml index 07def9efd..edda47f3d 100644 --- a/api-docs/cloud/swaggerV1Compat.yml +++ b/api-docs/cloud/swaggerV1Compat.yml @@ -429,4 +429,3 @@ tags: x-traitTag: true - name: Query - name: Write -x-tagGroups: [] diff --git a/api-docs/generate-api-docs.sh b/api-docs/generate-api-docs.sh index aa630969d..207946f8a 100755 --- a/api-docs/generate-api-docs.sh +++ b/api-docs/generate-api-docs.sh @@ -91,6 +91,8 @@ do menu="influxdb_$(echo $version | sed 's/\./_/g;s/v//g;')_ref" if [[ $version == "cloud" ]]; then titleVersion="Cloud" + elif [[ $version == "cloud-iox" ]]; then + titleVersion="Cloud (IOx)" else titleVersion="$version" fi diff --git a/api-docs/getswagger.sh b/api-docs/getswagger.sh index 865b3fdfb..d9c2108a7 100755 --- a/api-docs/getswagger.sh +++ b/api-docs/getswagger.sh @@ -3,7 +3,7 @@ # This script provides a simple way grab the latest fully resolved openapi (OAS, OpenAPI Specification) contract files # from the influxdata/openapi repo. # -# Specify a platform to retrieve (cloud, oss, v1compat, all). +# Specify a platform to retrieve (cloud-iox, cloud, oss, v1compat, all). # Optionally specify: # - an OSS version as the second argument or using the -o flag. # The version specifies where to write the updated openapi. @@ -20,6 +20,7 @@ # sh ./getswagger.sh -c -o -b # # Examples: +# sh ./getswagger.sh cloud-iox # sh ./getswagger.sh cloud # sh ./getswagger.sh -c oss -o v2.0 -b file:///Users/johnsmith/github/openapi @@ -56,7 +57,7 @@ function showHelp { subcommand=$1 case "$subcommand" in - cloud|oss|v1compat|all) + cloud-iox|cloud|oss|v1compat|all) platform=$1 shift @@ -131,6 +132,12 @@ function updateCloud { postProcess $outFile cloud } +function updateCloudIOx { + outFile="cloud-iox/ref.yml" + curl $UPDATE_OPTIONS ${baseUrl}/contracts/ref/cloud.yml -o $outFile + postProcess $outFile cloud-iox +} + function updateOSS { mkdir -p ${ossVersion} outFile="$ossVersion/ref.yml" @@ -160,6 +167,9 @@ fi if [ "$platform" = "cloud" ]; then updateCloud +elif [ "$platform" = "cloud-iox" ]; +then + updateCloudIOx elif [ "$platform" = "oss" ]; then updateOSS @@ -169,9 +179,10 @@ then elif [ "$platform" = "all" ]; then updateCloud + updateCloudIOx updateOSS updateV1Compat else - echo "Provide a platform argument: cloud, oss, v1compat, or all." + echo "Provide a platform argument: cloud, cloud-iox, oss, v1compat, or all." showHelp fi diff --git a/api-docs/openapi/plugins/decorators/tags/set-tag-groups.js b/api-docs/openapi/plugins/decorators/tags/set-tag-groups.js index 07477bb5c..d9315fa1f 100644 --- a/api-docs/openapi/plugins/decorators/tags/set-tag-groups.js +++ b/api-docs/openapi/plugins/decorators/tags/set-tag-groups.js @@ -1,6 +1,6 @@ module.exports = SetTagGroups; -const { collect, getName, sortName } = require('../../helpers/content-helper.js') +const { collect, getName, sortName, isPresent } = require('../../helpers/content-helper.js') /** * Returns an object that defines handler functions for: * - Operation nodes @@ -19,17 +19,47 @@ function SetTagGroups(data) { data = []; } + const ALL_ENDPOINTS = 'All endpoints'; + /** Tag names used for ad-hoc grouping of Operations and not specific to a resource or path. + * For example, these might be useful for UI navigation and filtering, but shouldn't appear + * in a list of resource tags. + */ + const nonResourceTags = [ + 'Data I/O endpoints', + 'Security and access endpoints', + 'System information endpoints' + ]; + + const allEndpointsGroup = data.filter(customGroup => customGroup.name === ALL_ENDPOINTS).pop(); + let tags = []; /** Collect tags for each operation and convert string tags to object tags. **/ return { DefinitionRoot: { Operation: { - leave(op) { + leave(op, ctx) { let opTags = op.tags?.map( function(t) { return typeof t === 'string' ? { name: t } : t; } ) || []; + + const { parent, key } = ctx; + if(allEndpointsGroup) { + opTags.forEach( + function(t) { + if(!allEndpointsGroup.tags.includes(t.name) && !nonResourceTags.includes(t.name)) { + /** If a custom allEndpointsGroup is defined and the current Operation + * contains a tag not specified in allEndpointsGroup, + * then delete the Operation from the doc so that it doesn't appear in other tags. + */ + delete parent[key]; + return; + } + } + ) + } + tags = collect(tags, opTags); } }, @@ -40,34 +70,24 @@ function SetTagGroups(data) { endpointTags = root.tags .filter(t => !t['x-traitTag']) + .filter(t => !nonResourceTags.includes(getName(t))) .map(t => getName(t)); - if(Array.isArray(root['x-tagGroups'])) { - root['x-tagGroups'].concat(data); - } else { + /** In Redoc, if x-tagGroups is present, a tag (and its paths) + * must be assigned to an x-tagGroup in order to display. */ + if(data.length) { + addAllEndpointTags(data); root['x-tagGroups'] = data; } - - let nonEndpointTags = [] - root['x-tagGroups'].map( - function(grp) { - if(grp.name !== 'All endpoints') { - nonEndpointTags = nonEndpointTags.concat(grp.tags); - } - if(!['All endpoints', 'Overview'].includes(grp.name)) { - grp.name = "" - } - }); - root['x-tagGroups'].map( - function(grp) { - if(grp.name === 'All endpoints') { - grp.tags = endpointTags - .filter(t => !nonEndpointTags.includes(t)); + function addAllEndpointTags(tagGroups) { + tagGroups.map(grp => { + if(grp.name === 'All endpoints' && !grp.tags.length) { + grp.tags = endpointTags; } return grp; - } - ) + }) + } } } } diff --git a/api-docs/openapi/plugins/docs-plugin.js b/api-docs/openapi/plugins/docs-plugin.js index e56aae28e..bcc1c5f1d 100644 --- a/api-docs/openapi/plugins/docs-plugin.js +++ b/api-docs/openapi/plugins/docs-plugin.js @@ -30,7 +30,7 @@ const decorators = { 'strip-trailing-slash': StripTrailingSlash, 'set-info': () => SetInfo(info()), 'set-tag-groups': () => SetTagGroups(tagGroups()), - 'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl, + 'replace-docs-url-shortcode': ReplaceShortcodes().docsUrl } }; @@ -50,7 +50,7 @@ module.exports = { 'docs/strip-trailing-slash': 'error', 'docs/set-info': 'error', 'docs/set-tag-groups': 'error', - 'docs/replace-docs-url-shortcode': 'error', + 'docs/replace-docs-url-shortcode': 'error' }, }, }, diff --git a/api-docs/v2.6/content/tag-groups.yml b/api-docs/v2.6/content/tag-groups.yml new file mode 100644 index 000000000..62cc43226 --- /dev/null +++ b/api-docs/v2.6/content/tag-groups.yml @@ -0,0 +1,13 @@ +- name: Using the InfluxDB HTTP API + tags: + - Quick start + - Authentication + - Supported operations + - Headers + - Pagination + - Response codes + - Data I/O endpoints + - Security and access endpoints + - System information endpoints +- name: All endpoints + tags: [] diff --git a/api-docs/v2.6/ref.yml b/api-docs/v2.6/ref.yml index 8b85873d6..88bd3a613 100644 --- a/api-docs/v2.6/ref.yml +++ b/api-docs/v2.6/ref.yml @@ -6751,4392 +6751,54 @@ info: url: https://opensource.org/licenses/MIT openapi: 3.0.0 paths: - /api/v2: - get: - description: | - Retrieves all the top level routes for the InfluxDB API. - - #### Limitations - - - Only returns top level routes--for example, the response contains - `"tasks":"/api/v2/tasks"`, and doesn't contain resource-specific routes - for tasks (`/api/v2/tasks/TASK_ID/...`). - operationId: GetRoutes - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Routes' - description: | - Success. - The response body contains key-value pairs with the resource name and - top-level route. - summary: List all top level routes - tags: - - Routes - - System information endpoints - /api/v2/authorizations: - get: - description: | - Lists authorizations. - - To limit which authorizations are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all authorizations. - - #### InfluxDB Cloud - - - InfluxDB Cloud doesn't expose [API token](/influxdb/latest/reference/glossary/#token) - values in `GET /api/v2/authorizations` responses; - returns `token: redacted` for all authorizations. - - #### Required permissions - - To retrieve an authorization, the request must use an API token that has the - following permissions: - - - `read-authorizations` - - `read-user` for the user that the authorization is scoped to - - #### Related guides - - - [View tokens](/influxdb/latest/security/tokens/view-tokens/) - operationId: GetAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Only returns authorizations scoped to the specified [user](/influxdb/latest/reference/glossary/#user). - in: query - name: userID - schema: - type: string - - description: | - A user name. - Only returns authorizations scoped to the specified [user](/influxdb/latest/reference/glossary/#user). - in: query - name: user - schema: - type: string - - description: An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/latest/reference/glossary/#organization). - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns authorizations that belong to the specified [organization](/influxdb/latest/reference/glossary/#organization). - in: query - name: org - schema: - type: string - - description: | - An API [token](/influxdb/latest/reference/glossary/#token) value. - Specifies an authorization by its `token` property value - and returns the authorization. - - #### InfluxDB OSS - - - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, - applies other parameters, and then returns the result. - - #### Limitations - - - The parameter is non-repeatable. If you specify more than one, - only the first one is used. If a resource with the specified - property value doesn't exist, then the response body contains an empty list. - in: query - name: token - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorizations' - description: | - Success. The response body contains a list of authorizations. - - If the response body is missing authorizations that you expect, check that the API - token used in the request has `read-user` permission for the users (`userID` property value) - in those authorizations. - - #### InfluxDB OSS - - - **Warning**: The response body contains authorizations with their - [API token](/influxdb/latest/reference/glossary/#token) values in clear text. - - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: List authorizations - tags: - - Authorizations (API tokens) - - Security and access endpoints - post: - description: | - Creates an authorization and returns the authorization with the - generated API [token](/influxdb/latest/reference/glossary/#token). - - Use this endpoint to create an authorization, which generates an API token - with permissions to `read` or `write` to a specific resource or `type` of resource. - The API token is the authorization's `token` property value. - - To follow best practices for secure API token generation and retrieval, - InfluxDB enforces access restrictions on API tokens. - - - InfluxDB allows access to the API token value immediately after the authorization is created. - - You canโ€™t change access (read/write) permissions for an API token after itโ€™s created. - - Tokens stop working when the user who created the token is deleted. - - We recommend the following for managing your tokens: - - - Create a generic user to create and manage tokens for writing data. - - Store your tokens in a secure password vault for future access. - - #### Required permissions - - - `write-authorizations` - - `write-user` for the user that the authorization is scoped to - - #### Related guides - - - [Create a token](/influxdb/latest/security/tokens/create-token/) - operationId: PostAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - examples: - AuthorizationPostRequest: - $ref: '#/components/examples/AuthorizationPostRequest' - AuthorizationWithResourcePostRequest: - $ref: '#/components/examples/AuthorizationWithResourcePostRequest' - AuthorizationWithUserPostRequest: - $ref: '#/components/examples/AuthorizationWithUserPostRequest' - schema: - $ref: '#/components/schemas/AuthorizationPostRequest' - description: The authorization to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: | - Success. The authorization is created. The response body contains the - authorization. - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Create an authorization - tags: - - Authorizations (API tokens) - - Security and access endpoints - /api/v2/authorizations/{authID}: - delete: - description: | - Deletes an authorization. - - Use the endpoint to delete an API token. - - If you want to disable an API token instead of delete it, - [update the authorization's status to `inactive`](#operation/PatchAuthorizationsID). - operationId: DeleteAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to delete. - in: path - name: authID - required: true - schema: - type: string - responses: - '204': - description: Success. The authorization is deleted. - '400': - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Delete an authorization - tags: - - Authorizations (API tokens) - - Security and access endpoints - get: - description: | - Retrieves an authorization. - - Use this endpoint to retrieve information about an API token, including - the token's permissions and the user that the token is scoped to. - - #### InfluxDB OSS - - - InfluxDB OSS returns - [API token](/influxdb/latest/reference/glossary/#token) values in authorizations. - - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_, - InfluxDB OSS returns authorizations for all organizations in the instance. - - #### Related guides - - - [View tokens](/influxdb/latest/security/tokens/view-tokens/) - externalDocs: - description: View tokens - url: https://docs.influxdata.com/influxdb/latest/security/tokens/view-tokens/ - operationId: GetAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to retrieve. - in: path - name: authID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the authorization. - '400': - content: - application/json: - examples: - notFound: - summary: | - The specified resource ID is invalid. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested authorization doesn't exist. - value: - code: not found - message: authorization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Retrieve an authorization - tags: - - Authorizations (API tokens) - - Security and access endpoints - patch: - description: | - Updates an authorization. - - Use this endpoint to set an API token's status to be _active_ or _inactive_. - InfluxDB rejects requests that use inactive API tokens. - operationId: PatchAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: An authorization ID. Specifies the authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: In the request body, provide the authorization properties to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Success. The response body contains the updated authorization. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Update an API token to be active or inactive - tags: - - Authorizations (API tokens) - - Security and access endpoints - /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; - avoid using this endpoint with versions greater than 2.1.x. - operationId: GetBackupKV - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/octet-stream: - schema: - format: binary - type: string - description: Success. The response contains a snapshot of KV metadata. - 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. - tags: - - Backup - /api/v2/backup/metadata: - get: - operationId: GetBackupMetadata - parameters: - - $ref: '#/components/parameters/TraceSpan' - - 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. - enum: - - gzip - - identity - type: string - responses: - '200': - content: - multipart/mixed: - schema: - $ref: '#/components/schemas/MetadataBackup' - description: Snapshot of metadata - headers: - Content-Encoding: - 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. - enum: - - gzip - - identity - type: string - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Download snapshot of all metadata in the server - tags: - - Backup - /api/v2/backup/shards/{shardID}: - get: - operationId: GetBackupShardId - parameters: - - $ref: '#/components/parameters/TraceSpan' - - 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. - enum: - - gzip - - identity - type: string - - description: The shard ID. - in: path - name: shardID - required: true - schema: - format: int64 - type: integer - - description: The earliest time [RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp) to include in the snapshot. - examples: - RFC3339: - summary: RFC3339 date/time format - value: 2006-01-02T15:04:05Z07:00 - in: query - name: since - schema: - format: date-time - type: string - responses: - '200': - content: - application/octet-stream: - schema: - format: binary - type: string - description: TSM snapshot. - headers: - Content-Encoding: - 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. - enum: - - gzip - - identity - type: string - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Shard not found. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Download snapshot of all TSM data in a shard - tags: - - Backup - /api/v2/buckets: - get: - description: | - Lists [buckets](/influxdb/latest/reference/glossary/#bucket). - - InfluxDB retrieves buckets owned by the - [organization](/influxdb/latest/reference/glossary/#organization) - associated with the authorization - ([API token](/influxdb/latest/reference/glossary/#token)). - To limit which buckets are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all buckets up to the - default `limit`. - - #### InfluxDB OSS - - - If you use an _[operator token](/influxdb/latest/security/tokens/#operator-token)_ - to authenticate your request, InfluxDB retrieves resources for _all - organizations_ in the instance. - To retrieve resources for only a specific organization, use the - `org` parameter or the `orgID` parameter to specify the organization. - - #### Required permissions - - | Action | Permission required | - |:--------------------------|:--------------------| - | Retrieve _user buckets_ | `read-buckets` | - | Retrieve [_system buckets_](/influxdb/latest/reference/internals/system-buckets/) | `read-orgs` | - - #### Related Guides - - - [Manage buckets](/influxdb/latest/organizations/buckets/) - operationId: GetBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/After' - - description: | - An organization name. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Lists buckets for the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Lists buckets for the specified organization. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Lists buckets for the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Lists buckets for the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A bucket name. - Only returns buckets with the specified name. - in: query - name: name - schema: - type: string - - description: | - A bucket ID. - Only returns the bucket with the specified ID. - in: query - name: id - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - buckets: - - createdAt: '2022-03-15T17:22:33.72617939Z' - description: System bucket for monitoring logs - id: 77ca9dace40a9bfc - labels: [] - links: - labels: /api/v2/buckets/77ca9dace40a9bfc/labels - members: /api/v2/buckets/77ca9dace40a9bfc/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/77ca9dace40a9bfc/owners - self: /api/v2/buckets/77ca9dace40a9bfc - write: /api/v2/write?org=ORG_ID&bucket=77ca9dace40a9bfc - name: _monitoring - orgID: INFLUX_ORG_ID - retentionRules: - - everySeconds: 604800 - type: expire - schemaType: implicit - 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 - schema: - $ref: '#/components/schemas/Buckets' - description: | - Success. - The response body contains a list of `buckets`. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List buckets - tags: - - Buckets - x-codeSamples: - - label: 'cURL: filter buckets by name' - lang: Shell - 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: | - Creates a [bucket](/influxdb/latest/reference/glossary/#bucket) - and returns the bucket resource. - The default data - [retention period](/influxdb/latest/reference/glossary/#retention-period) - is 30 days. - - #### InfluxDB OSS - - - A single InfluxDB OSS instance supports active writes or queries for - approximately 20 buckets across all organizations at a given time. - Reading or writing to more than 20 buckets at a time can adversely affect - performance. - - #### Limitations - - - InfluxDB Cloud Free Plan allows users to create up to two buckets. - Exceeding the bucket quota will result in an HTTP `403` status code. - For additional information regarding InfluxDB Cloud offerings, see - [InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/). - - #### Related Guides - - - [Create a bucket](/influxdb/latest/organizations/buckets/create-bucket/) - - [Create bucket CLI reference](/influxdb/latest/reference/cli/influx/bucket/create) - operationId: PostBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostBucketRequest' - description: The bucket to create. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-03T23:04:41.073704121Z' - description: A bucket holding air sensor data - id: 37407e232b3911d8 - labels: [] - links: - labels: /api/v2/buckets/37407e232b3911d8/labels - members: /api/v2/buckets/37407e232b3911d8/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/37407e232b3911d8/owners - self: /api/v2/buckets/37407e232b3911d8 - write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 - name: air_sensor - orgID: INFLUX_ORG_ID - retentionRules: - - everySeconds: 2592000 - type: expire - schemaType: implicit - type: user - updatedAt: '2022-08-03T23:04:41.073704228Z' - schema: - $ref: '#/components/schemas/Bucket' - description: | - Success. - The bucket is created. - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '403': - content: - application/json: - examples: - quotaExceeded: - summary: Bucket quota exceeded - value: - code: forbidden - message: creating bucket would exceed quota - schema: - $ref: '#/components/schemas/Error' - description: | - Forbidden. - The bucket quota is exceeded. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: forbidden - type: string - '422': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable Entity. - The request body failed validation. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a bucket - tags: - - Buckets - x-codeSamples: - - label: 'cURL: create a bucket with retention period' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/buckets \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "air_sensor", - "description": "A bucket holding air sensor data", - "orgID": "INFLUX_ORG_ID", - "retentionRules": [ - { - "type": "expire", - "everySeconds": 2592000, - } - ] - }' - - label: cURL - lang: Shell - source: '' - /api/v2/buckets/{bucketID}: - delete: - description: | - Deletes a bucket and all associated records. - - #### InfluxDB Cloud - - - Does the following when you send a delete request: - - 1. Validates the request and queues the delete. - 2. Returns an HTTP `204` status code if queued; _error_ otherwise. - 3. Handles the delete asynchronously. - - #### InfluxDB OSS - - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - - #### Limitations - - - Only one bucket can be deleted per request. - - #### Related Guides - - - [Delete a bucket](/influxdb/latest/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui) - operationId: DeleteBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - Bucket ID. - The ID of the bucket to delete. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - The bucket is queued for deletion. - - #### InfluxDB OSS - - The bucket is deleted. - '400': - content: - application/json: - examples: - invalidID: - summary: | - Invalid ID. - value: - code: invalid - message: id must have a length of 16 bytes - schema: - $ref: '#/components/schemas/Error' - description: | - Bad Request. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested bucket was not found. - value: - code: not found - message: bucket not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Bucket not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header 'Accept: application/json' - get: - description: | - Retrieves a bucket. - - Use this endpoint to retrieve information for a specific bucket. - operationId: GetBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-03T23:04:41.073704121Z' - description: bucket for air sensor data - id: 37407e232b3911d8 - labels: [] - links: - labels: /api/v2/buckets/37407e232b3911d8/labels - members: /api/v2/buckets/37407e232b3911d8/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/37407e232b3911d8/owners - self: /api/v2/buckets/37407e232b3911d8 - write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 - name: air-sensor - orgID: bea7ea952287f70d - retentionRules: - - everySeconds: 2592000 - type: expire - schemaType: implicit - type: user - updatedAt: '2022-08-03T23:04:41.073704228Z' - schema: - $ref: '#/components/schemas/Bucket' - description: | - Success. - The response body contains the bucket information. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested bucket wasn't found. - value: - code: not found - message: bucket not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Bucket not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a bucket - tags: - - Buckets - patch: - description: | - Updates a bucket. - - Use this endpoint to update properties - (`name`, `description`, and `retentionRules`) of a bucket. - - #### InfluxDB Cloud - - - Requires the `retentionRules` property in the request body. If you don't - provide `retentionRules`, InfluxDB responds with an HTTP `403` status code. - - #### InfluxDB OSS - - - Doesn't require `retentionRules`. - - #### Related Guides - - - [Update a bucket](/influxdb/latest/organizations/buckets/update-bucket/) - operationId: PatchBucketsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchBucketRequest' - description: The bucket update to apply. - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-03T23:04:41.073704121Z' - description: bucket holding air sensor data - id: 37407e232b3911d8 - labels: [] - links: - labels: /api/v2/buckets/37407e232b3911d8/labels - members: /api/v2/buckets/37407e232b3911d8/members - org: /api/v2/orgs/INFLUX_ORG_ID - owners: /api/v2/buckets/37407e232b3911d8/owners - self: /api/v2/buckets/37407e232b3911d8 - write: /api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8 - name: air_sensor - orgID: INFLUX_ORG_ID - retentionRules: - - everySeconds: 2592000 - type: expire - schemaType: implicit - type: user - updatedAt: '2022-08-07T22:49:49.422962913Z' - schema: - $ref: '#/components/schemas/Bucket' - description: An updated bucket - '400': - content: - application/json: - examples: - invalidJSONStringValue: - 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' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad Request. - '401': - $ref: '#/components/responses/AuthorizationError' - '403': - content: - application/json: - examples: - invalidRetention: - summary: | - The retention policy provided exceeds the max retention for the - organization. - value: - code: forbidden - message: provided retention exceeds orgs maximum retention duration - schema: - $ref: '#/components/schemas/Error' - description: | - Forbidden. - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested bucket wasn't found. - value: - code: not found - message: bucket not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Bucket not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request PATCH "http://localhost:8086/api/v2/buckets/BUCKET_ID \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "air_sensor", - "description": "bucket holding air sensor data", - "retentionRules": [ - { - "type": "expire", - "everySeconds": 2592000 - } - ] - }' - /api/v2/buckets/{bucketID}/labels: - get: - description: | - Lists all labels for a bucket. - - Labels are objects that contain `labelID`, `name`, `description`, and `color` - key-value pairs. They may be used for grouping and filtering InfluxDB - resources. - Labels are also capable of grouping across different resources--for example, - you can apply a label named `air_sensor` to a bucket and a task to quickly - organize resources. - - #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - - [Manage labels in the InfluxDB UI](/influxdb/latest/visualize-data/labels/) - operationId: GetBucketsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve labels for. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - labels: - - id: 09cbd068e7ebb000 - name: production_buckets - orgID: INFLUX_ORG_ID - links: - self: /api/v2/labels - schema: - $ref: '#/components/schemas/LabelsResponse' - description: | - Success. - The response body contains a list of all labels 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a bucket - tags: - - Buckets - post: - description: | - Adds a label to a bucket and returns the new label information. - - Labels are objects that contain `labelID`, `name`, `description`, and `color` - key-value pairs. They may be used for grouping and filtering across one or - more kinds of **resources**--for example, you can apply a label named - `air_sensor` to a bucket and a task to quickly organize resources. - - #### Limitations - - - Before adding a label to a bucket, you must create the label if you - haven't already. To create a label with the InfluxDB API, send a `POST` - request to the [`/api/v2/labels` endpoint](#operation/PostLabels)). - - #### Related guides - - - Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels. - - [Manage labels in the InfluxDB UI](/influxdb/latest/visualize-data/labels/) - operationId: PostBucketsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - Bucket ID. - The ID of the bucket to label. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: An object that contains a _`labelID`_ to add to the bucket. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - label: - id: 09cbd068e7ebb000 - name: production_buckets - orgID: INFLUX_ORG_ID - links: - self: /api/v2/labels - schema: - $ref: '#/components/schemas/LabelResponse' - description: | - Success. - The response body contains the label information. - '400': - $ref: '#/components/responses/BadRequestError' - examples: - invalidRequest: - summary: The `labelID` is missing from the request body. - value: - code: invalid - message: label id is required - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '422': - content: - application/json: - examples: - conflictingResource: - summary: | - Label already exists on the resource. - value: - code: conflict - message: Cannot add label, label already exists on resource - schema: - $ref: '#/components/schemas/Error' - description: | - Unprocessable entity. - Label already exists on the resource. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/buckets/BUCKETS_ID/labels \ - --header "Authorization: Token INFLUX_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "labelID": "09cbd068e7ebb000" - }' - /api/v2/buckets/{bucketID}/labels/{labelID}: - delete: - operationId: DeleteBucketsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Bucket not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/members: - get: - description: | - Lists all users for a bucket. - - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have - permission to access InfluxDB. - - [Members](/influxdb/latest/reference/glossary/#member) are users in - an organization with access to the specified resource. - - Use this endpoint to retrieve all users with access to a bucket. - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) - operationId: GetBucketsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve users for. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/buckets/37407e232b3911d8/members - users: - - id: 791df274afd48a83 - links: - self: /api/v2/users/791df274afd48a83 - name: example_user_1 - role: member - status: active - - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_2 - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. - The response body contains a list of all users 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a bucket - tags: - - Buckets - post: - description: | - Add a user to a bucket and return the new user information. - - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have - permission to access InfluxDB. - - [Members](/influxdb/latest/reference/glossary/#member) are users in - an organization. - - Use this endpoint to give a user member privileges to a bucket. - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) - operationId: PostBucketsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve users for. - in: path - name: bucketID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: A user to add as a member to the bucket. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_1 - role: member - status: active - schema: - $ref: '#/components/schemas/ResourceMember' - description: | - Success. - The response body contains the user information. - '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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a bucket - tags: - - Buckets - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/buckets/BUCKET_ID/members \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "id": "09cfb87051cbe000" - } - /api/v2/buckets/{bucketID}/members/{userID}: - delete: - description: | - Removes a member from a bucket. - - Use this endpoint to remove a user's member privileges from a bucket. This - removes the user's `read` and `write` permissions for the bucket. - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) - operationId: DeleteBucketsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the user to remove. - in: path - name: userID - required: true - schema: - type: string - - description: | - The ID of the bucket to remove a user from. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer a member of the bucket. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a bucket - tags: - - Buckets - /api/v2/buckets/{bucketID}/owners: - get: - description: | - Lists all [owners](/influxdb/latest/reference/glossary/#owner) - of a bucket. - - Bucket owners have permission to delete buckets and remove user and member - permissions from the bucket. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `read-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a - list of owners for. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - operationId: GetBucketsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to retrieve owners for. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '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: | - 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a bucket - tags: - - Buckets - post: - description: | - Adds an owner to a bucket and returns the [owners](/influxdb/latest/reference/glossary/#owner) - with role and user detail. - - Use this endpoint to create a _resource owner_ for the bucket. - Bucket owners have permission to delete buckets and remove user and member - permissions from the bucket. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - *`INFLUX_ORG_ID`* is the ID of the organization that you want to add - an owner for. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - operationId: PostBucketsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the bucket to add an owner for. - in: path - name: bucketID - required: true - schema: - type: string - 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: A user to add as an owner for the bucket. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - 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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - 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-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner - from. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - operationId: DeleteBucketsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: | - The ID of the bucket to remove an owner from. - in: path - name: bucketID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer an owner of the bucket. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a bucket - tags: - - Buckets - /api/v2/checks: - get: - operationId: GetChecks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show checks that belong to a specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Checks' - description: A list of checks - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all checks - tags: - - Checks - post: - operationId: CreateCheck - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostCheck' - description: Check to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: Check created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add new check - tags: - - Checks - /api/v2/checks/{checkID}: - delete: - operationId: DeleteChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a check - tags: - - Checks - get: - operationId: GetChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: The check requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a check - tags: - - Checks - patch: - operationId: PatchChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CheckPatch' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: An updated check - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a check - tags: - - Checks - put: - operationId: PutChecksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Check' - description: An updated check - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a check - tags: - - Checks - /api/v2/checks/{checkID}/labels: - get: - operationId: GetChecksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a check - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a check - tags: - - Checks - post: - operationId: PostChecksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the check - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a check - tags: - - Checks - /api/v2/checks/{checkID}/labels/{labelID}: - delete: - operationId: DeleteChecksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Check or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete label from a check - tags: - - Checks - /api/v2/checks/{checkID}/query: - get: - operationId: GetChecksIDQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The check ID. - in: path - name: checkID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxResponse' - description: The check query requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Check not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a check query - tags: - - Checks - /api/v2/config: - get: - description: | - Returns the active runtime configuration of the InfluxDB instance. - - 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/latest/reference/config-options/#view-your-runtime-server-configuration) - operationId: GetConfig - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Config' - description: | - Success. - The response body contains the active runtime configuration of the InfluxDB instance. - '401': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve runtime configuration - tags: - - Config - - System information endpoints - /api/v2/dashboards: - get: - description: | - Lists [dashboards](/influxdb/latest/reference/glossary/#dashboard). - - #### Related guides - - - [Manage dashboards](/influxdb/latest/visualize-data/dashboards/). - operationId: GetDashboards - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/Descending' - - description: A user ID. Only returns [dashboards](/influxdb/latest/reference/glossary/#dashboard) where the specified user has the `owner` role. - in: query - name: owner - schema: - type: string - - description: The column to sort by. - in: query - name: sortBy - schema: - enum: - - ID - - CreatedAt - - UpdatedAt - type: string - - description: | - A list of dashboard IDs. - Returns only the specified [dashboards](/influxdb/latest/reference/glossary/#dashboard). - If you specify `id` and `owner`, only `id` is used. - in: query - name: id - schema: - items: - type: string - type: array - - description: | - An organization ID. - Only returns [dashboards](/influxdb/latest/reference/glossary/#dashboard) that belong to the specified - [organization](/influxdb/latest/reference/glossary/#organization). - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns [dashboards](/influxdb/latest/reference/glossary/#dashboard) that belong to the specified - [organization](/influxdb/latest/reference/glossary/#organization). - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboards' - description: Success. The response body contains dashboards. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List dashboards - tags: - - Dashboards - post: - operationId: PostDashboards - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateDashboardRequest' - description: Dashboard to create - required: true - responses: - '201': - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Dashboard' - - $ref: '#/components/schemas/DashboardWithViewProperties' - description: Success. The dashboard is created. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}: - delete: - operationId: DeleteDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a dashboard - tags: - - Dashboards - get: - operationId: GetDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: If `properties`, includes the cell view properties in the response. - in: query - name: include - required: false - schema: - enum: - - properties - type: string - responses: - '200': - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Dashboard' - - $ref: '#/components/schemas/DashboardWithViewProperties' - description: Retrieve a single dashboard - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a dashboard - tags: - - Dashboards - patch: - operationId: PatchDashboardsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - cells: - $ref: '#/components/schemas/CellWithViewProperties' - description: optional, when provided will replace all existing cells with the cells provided - description: - description: optional, when provided will replace the description - type: string - name: - description: optional, when provided will replace the name - type: string - title: PatchDashboardRequest - type: object - description: Patching of a dashboard - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboard' - description: Updated dashboard - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/cells: - post: - operationId: PostDashboardsIDCells - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CreateCell' - description: Cell that will be added - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Cell' - description: Cell successfully added - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a dashboard cell - tags: - - Cells - - Dashboards - put: - 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' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Cells' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Dashboard' - description: Replaced dashboard cells - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Replace cells in a dashboard - tags: - - Cells - - Dashboards - /api/v2/dashboards/{dashboardID}/cells/{cellID}: - delete: - operationId: DeleteDashboardsIDCellsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to delete. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to delete. - in: path - name: cellID - required: true - schema: - type: string - responses: - '204': - description: Cell successfully deleted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a dashboard cell - tags: - - 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. - operationId: PatchDashboardsIDCellsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to update. - in: path - name: cellID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/CellUpdate' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Cell' - description: Updated dashboard cell - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update the non-positional information related to a cell - tags: - - Cells - - Dashboards - /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: - get: - operationId: GetDashboardsIDCellsIDView - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The cell ID. - in: path - name: cellID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/View' - description: A dashboard cells view - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve the view for a cell - tags: - - Cells - - Dashboards - - Views - patch: - operationId: PatchDashboardsIDCellsIDView - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the dashboard to update. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the cell to update. - in: path - name: cellID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/View' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/View' - description: Updated cell view - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Cell or dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update the view for a cell - tags: - - Cells - - Dashboards - - Views - /api/v2/dashboards/{dashboardID}/labels: - get: - operationId: GetDashboardsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a dashboard - tags: - - Dashboards - post: - operationId: PostDashboardsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/labels/{labelID}: - delete: - operationId: DeleteDashboardsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Dashboard not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/members: - get: - operationId: GetDashboardsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of users who have member privileges for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboard members - tags: - - Dashboards - post: - operationId: PostDashboardsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Added to dashboard members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/members/{userID}: - delete: - operationId: DeleteDashboardsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/owners: - get: - operationId: GetDashboardsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of users who have owner privileges for a dashboard - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all dashboard owners - tags: - - Dashboards - post: - operationId: PostDashboardsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Added to dashboard owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a dashboard - tags: - - Dashboards - /api/v2/dashboards/{dashboardID}/owners/{userID}: - delete: - operationId: DeleteDashboardsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The dashboard ID. - in: path - name: dashboardID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a dashboard - tags: - - Dashboards - /api/v2/dbrps: - get: - description: | - Lists database retention policy (DBRP) mappings. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/latest/reference/api/influxdb-1x/dbrp/) - operationId: GetDBRPs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Only returns DBRP mappings for the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns DBRP mappings for the specified organization. - in: query - name: org - schema: - type: string - - description: | - A DBPR mapping ID. - Only returns the specified DBRP mapping. - in: query - name: id - schema: - type: string - - description: | - A bucket ID. - Only returns DBRP mappings that belong to the specified bucket. - in: query - name: bucketID - schema: - type: string - - description: Specifies filtering on default - in: query - name: default - schema: - type: boolean - - description: | - A database. - Only returns DBRP mappings that belong to the 1.x database. - in: query - name: db - schema: - type: string - - description: | - A [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp). - Specifies the 1.x retention policy to filter on. - in: query - name: rp - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - - bucketID: 4d4d9d5b61dee751 - database: example_database_1 - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - - bucketID: 4d4d9d5b61dee751 - database: example_database_2 - default: false - id: 0a3cbcde20e38000 - orgID: bea7ea952287f70d - retention_policy: example_retention_policy - schema: - $ref: '#/components/schemas/DBRPs' - description: Success. The response body contains a list of database retention policy mappings. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The request has one or more invalid parameters. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List database retention policy mappings - tags: - - DBRPs - post: - description: | - Creates a database retention policy (DBRP) mapping and returns the mapping. - - Use this endpoint to add InfluxDB 1.x API compatibility to your - InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a - DBRP mapping in order to query and write using the InfluxDB 1.x API. - object. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/latest/reference/api/influxdb-1x/dbrp/) - operationId: PostDBRP - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPCreate' - description: | - The database retention policy mapping to add. - - Note that _`retention_policy`_ is a required parameter in the request body. - The value of _`retention_policy`_ can be any arbitrary `string` name or - value, with the default value commonly set as `autogen`. - The value of _`retention_policy`_ isn't a [retention_policy](/influxdb/latest/reference/glossary/#retention-policy-rp) - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - bucketID: 4d4d9d5b61dee751 - database: example_database - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - schema: - $ref: '#/components/schemas/DBRP' - description: Created. The response body contains the database retention policy mapping. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad request. The mapping in the request has one or more invalid IDs. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a database retention policy mapping - tags: - - DBRPs - x-codeSamples: - - label: 'cURL: create a database retention policy mapping' - lang: Shell - source: | - curl --request POST \ - "http://localhost:8086/api/v2/dbrp/" \ - --header 'Content-type: application/json' \ - --header "Authorization: Token INFLUXDB_TOKEN" \ - --data-binary @- << EOF - { \ - "bucketID": "INFLUXDB_BUCKET_ID", \ - "orgID": "INFLUXDB_ORG_ID", \ - "database": "database_name", \ - "default": true, \ - "retention_policy": "example_retention_policy_name" \ - } - EOF - /api/v2/dbrps/{dbrpID}: - delete: - description: | - Deletes the specified database retention policy (DBRP) mapping. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/latest/reference/api/influxdb-1x/dbrp/) - operationId: DeleteDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Only returns the specified DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '204': - description: Success. The delete is accepted. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a database retention policy - tags: - - DBRPs - get: - description: | - Retrieves the specified retention policy (DBRP) mapping. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/latest/reference/api/influxdb-1x/dbrp/) - operationId: GetDBRPsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Specifies the DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - bucketID: 4d4d9d5b61dee751 - database: example_database_1 - default: true - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: autogen - schema: - $ref: '#/components/schemas/DBRPGet' - description: Success. The response body contains the DBRP mapping. - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a database retention policy mapping - tags: - - DBRPs - patch: - operationId: PatchDBRPID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - An organization ID. - Specifies the organization that owns the DBRP mapping. - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Specifies the organization that owns the DBRP mapping. - in: query - name: org - schema: - type: string - - description: | - A DBRP mapping ID. - Specifies the DBRP mapping. - in: path - name: dbrpID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DBRPUpdate' - description: | - Updates the database retention policy (DBRP) mapping and returns the mapping. - - Use this endpoint to modify the _retention policy_ (`retention_policy` property) of a DBRP mapping. - - #### Related guide - - - [Database and retention policy mapping](/influxdb/latest/reference/api/influxdb-1x/dbrp/) - required: true - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - content: - bucketID: 4d4d9d5b61dee751 - database: example_database - default: false - id: 0a3cbb5dd526a000 - orgID: bea7ea952287f70d - retention_policy: example_retention_policy - schema: - $ref: '#/components/schemas/DBRPGet' - description: An updated mapping - '400': - content: - application/json: - examples: - invalidRequest: - description: | - The query parameters contain invalid values. - value: - code: invalid - message: invalid ID - schema: - $ref: '#/components/schemas/Error' - description: Bad Request. Query parameters contain invalid values. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a database retention policy mapping - tags: - - DBRPs - x-codeSamples: - - label: 'cURL: Update a DBRP mapping' - lang: Shell - source: | - curl --request PATCH \ - "http://localhost:8086/api/v2/dbrp/DBRP_ID" \ - --header 'Content-type: application/json' \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data-binary @- << EOF - { - "default": true, - "retention_policy": "example_retention_policy_name" - } - EOF - /debug/pprof/all: - get: - 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 - - **cpu**: (Optional) Program counters sampled from the executing stack. - Include by passing the `cpu` query parameter with a [duration](/influxdb/latest/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 - operationId: GetDebugPprofAllProfiles - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - Collects and returns CPU profiling data for the specified [duration](/influxdb/latest/reference/glossary/#duration). - in: query - name: cpu - schema: - externalDocs: - description: InfluxDB duration - url: https://docs.influxdata.com/influxdb/latest/reference/glossary/#duration - format: duration - type: string - responses: - '200': - content: - application/octet-stream: - schema: - description: | - GZIP compressed TAR file (`.tar.gz`) that contains - [Go runtime profile](https://pkg.go.dev/runtime/pprof) reports. - 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) reports. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve all runtime profiles - tags: - - Debug - - System information endpoints - 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. - - 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 - source: | - # Download and extract a `tar.gz` of all profiles except CPU. - - curl http://localhost:8086/debug/pprof/all | tar -xz - - # 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 - /debug/pprof/allocs: - get: - 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). - 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. - 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. - in: query - name: debug - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - - description: | - Number of seconds to collect statistics. - - `seconds` is mutually exclusive with `debug=1`. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - 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 - text/plain: - schema: - description: | - Response body contains a report formatted in plain text. - The report contains comments that translate addresses to - function names and line numbers for debugging. - externalDocs: - description: Golang pprof package - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the memory allocations runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - 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) - # (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. - 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. - 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. - in: query - name: debug - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - - description: | - Number of seconds to collect statistics. - - `seconds` is mutually exclusive with `debug=1`. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - 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 - text/plain: - schema: - description: | - Response body contains a report formatted in plain text. - The report contains comments that translate addresses to - function names and line numbers for debugging. - externalDocs: - description: Golang pprof package - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the block runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - 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) - # (pprof) - - # At the prompt, get the top N entries. - - (pprof) top10 - /debug/pprof/cmdline: - get: - description: | - Returns the command line that invoked InfluxDB. - operationId: GetDebugPprofCmdline - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - text/plain: - schema: - format: Command line - type: string - description: Command line invocation. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the command line invocation - tags: - - Debug - - System information endpoints - /debug/pprof/goroutine: - get: - 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. - - `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. - - `debug=1` is mutually exclusive with the `seconds` query parameter. - in: query - name: debug - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - - description: | - Number of seconds to collect statistics. - - `seconds` is mutually exclusive with `debug=1`. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - 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 - text/plain: - schema: - description: | - Response body contains a report formatted in plain text. - The report contains comments that translate addresses to - function names and line numbers for debugging. - externalDocs: - description: Golang pprof package - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the goroutines runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - 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) - # (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) - 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. - 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. - in: query - name: debug - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - - description: | - Number of seconds to collect statistics. - - `seconds` is mutually exclusive with `debug=1`. - in: query - name: seconds - schema: - format: int64 - type: string - - description: | - - `0`: (Default) don't force garbage collection before sampling. - - `1`: Force garbage collection before sampling. - in: query - name: gc - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - responses: - '200': - content: - application/octet-stream: - schema: - 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 - text/plain: - examples: - profileDebugResponse: - summary: Profile in plain text - value: "heap profile: 12431: 137356528 [149885081: 846795139976] @ heap/8192\n23: 17711104 [46: 35422208] @ 0x4c6df65 0x4ce03ec 0x4cdf3c5 0x4c6f4db 0x4c9edbc 0x4bdefb3 0x4bf822a 0x567d158 0x567ced9 0x406c0a1\n#\t0x4c6df64\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*entry).add+0x1a4\t\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/cache.go:97\n#\t0x4ce03eb\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*partition).write+0x2ab\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/ring.go:229\n#\t0x4cdf3c4\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*ring).write+0xa4\t\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/ring.go:95\n#\t0x4c6f4da\tgithub.com/influxdata/influxdb/v2/tsdb/engine/tsm1.(*Cache).WriteMulti+0x31a\t\t\t\t/Users/me/github/influxdb/tsdb/engine/tsm1/cache.go:343\n" - schema: - description: | - Response body contains a report formatted in plain text. - The report contains comments that translate addresses to - function names and line numbers for debugging. - externalDocs: - description: Golang pprof package - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the heap runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - 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) - # (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 - lock contentions. - 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. - 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. - in: query - name: debug - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - - description: | - Number of seconds to collect statistics. - - `seconds` is mutually exclusive with `debug=1`. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - 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 - text/plain: - schema: - description: | - Response body contains a report formatted in plain text. - The report contains comments that translate addresses to - function names and line numbers for debugging. - externalDocs: - description: Golang pprof package - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the mutual exclusion (mutex) runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - 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) - # (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) - report of program counters on the executing stack. - operationId: GetDebugPprofProfile - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Number of seconds to collect profile data. Default is `30` seconds. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the CPU runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - source: | - # Download the profile report. - - curl http://localhost:8086/debug/pprof/profile -o cpu - - # Analyze the profile in interactive mode. - - go tool pprof ./cpu - - # At the prompt, get the top N functions most often running - # or waiting during the sample period. - - (pprof) top10 - /debug/pprof/threadcreate: - get: - 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. - 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. - in: query - name: debug - schema: - enum: - - 0 - - 1 - format: int64 - type: integer - - description: | - Number of seconds to collect statistics. - - `seconds` is mutually exclusive with `debug=1`. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - 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 - text/plain: - examples: - profileDebugResponse: - summary: Profile in plain text - value: "threadcreate profile: total 26\n25 @\n#\t0x0\n\n1 @ 0x403dda8 0x403e54b 0x403e810 0x403a90c 0x406c0a1\n#\t0x403dda7\truntime.allocm+0xc7\t\t\t/Users/me/.gvm/gos/go1.17/src/runtime/proc.go:1877\n#\t0x403e54a\truntime.newm+0x2a\t\t\t/Users/me/.gvm/gos/go1.17/src/runtime/proc.go:2201\n#\t0x403e80f\truntime.startTemplateThread+0x8f\t/Users/me/.gvm/gos/go1.17/src/runtime/proc.go:2271\n#\t0x403a90b\truntime.main+0x1cb\t\t\t/Users/me/.gvm/gos/go1.17/src/runtime/proc.go:234\n" - schema: - description: | - Response body contains a report formatted in plain text. - The report contains comments that translate addresses to - function names and line numbers for debugging. - externalDocs: - description: Golang pprof package - 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. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the threadcreate runtime profile - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool pprof' - lang: Shell - 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) - # (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. - operationId: GetDebugPprofTrace - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Number of seconds to collect profile data. - in: query - name: seconds - schema: - format: int64 - type: string - responses: - '200': - content: - application/octet-stream: - schema: - externalDocs: - description: Golang trace package - url: https://pkg.go.dev/runtime/trace - format: binary - type: string - description: | - [Trace file](https://pkg.go.dev/runtime/trace) compatible - with the [Golang `trace` command](https://pkg.go.dev/cmd/trace). - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the runtime execution trace - tags: - - Debug - - System information endpoints - x-codeSamples: - - label: 'Shell: go tool trace' - lang: Shell - source: | - # Download the trace file. - - curl http://localhost:8086/debug/pprof/trace -o trace - - # Analyze the trace. - - go tool trace ./trace - /api/v2/delete: - post: - description: | - Deletes data from a bucket. - - Use this endpoint to delete points from a bucket in a specified time range. - - #### InfluxDB Cloud - - - Does the following when you send a delete request: - - 1. Validates the request and queues the delete. - 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. - 3. Handles the delete asynchronously and reaches eventual consistency. - - To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, - wait for a success response (HTTP `2xx` status code) before you send the next request. - - Because writes and deletes are asynchronous, your change might not yet be readable - when you receive the response. - - #### InfluxDB OSS - - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - - #### Required permissions - - - `write-buckets` or `write-bucket BUCKET_ID`. - - *`BUCKET_ID`* is the ID of the destination bucket. - - #### Rate limits (with InfluxDB Cloud) - - `write` rate limits apply. - For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Delete data](/influxdb/latest/write-data/delete-data/) - - Learn how to use [delete predicate syntax](/influxdb/latest/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: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Deletes data from the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - Deletes data from the bucket in the specified organization. - - If you pass both `orgID` and `org`, they must both be valid. - in: query - name: org - schema: - description: The organization name or ID. - type: string - - description: | - A bucket name or ID. - Specifies the bucket to delete data from. - If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. - in: query - name: bucket - schema: - description: The bucket name or ID. - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Deletes data from the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - Deletes data from the bucket in the specified organization. - - If you pass both `orgID` and `org`, they must both be valid. - in: query - name: orgID - schema: - description: The organization ID. - type: string - - description: | - A bucket ID. - Specifies the bucket to delete data from. - If you pass both `bucket` and `bucketID`, `bucketID` takes precedence. - in: query - name: bucketID - schema: - description: The bucket ID. - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/DeletePredicateRequest' - description: | - Time range parameters and an optional **delete predicate expression**. - - To select points to delete within the specified time range, pass a - **delete predicate expression** in the `predicate` property of the request body. - If you don't pass a `predicate`, InfluxDB deletes all data with timestamps - in the specified time range. - - #### Related guides - - - [Delete data](/influxdb/latest/write-data/delete-data/) - - Learn how to use [delete predicate syntax](/influxdb/latest/reference/syntax/delete-predicate/). - required: true - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - - Validated and queued the request. - - Handles the delete asynchronously - the deletion might not have completed yet. - - An HTTP `2xx` status code acknowledges that the write or delete is queued. - To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, - wait for a response before you send the next request. - - Because writes are asynchronous, data might not yet be written - when you receive the response. - - #### InfluxDB OSS - - - Deleted the data. - '400': - content: - application/json: - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete data - tags: - - Data I/O endpoints - - Delete - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST INFLUX_URL/api/v2/delete?org=INFLUX_ORG&bucket=INFLUX_BUCKET \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --header 'Content-Type: application/json' \ - --data '{ - "start": "2020-03-01T00:00:00Z", - "stop": "2020-11-14T00:00:00Z", - "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")" - }' - /api/v2/flags: - get: - description: | - Retrieves the feature flag key-value pairs configured for the InfluxDB - instance. - _Feature flags_ are configuration options used to develop and test - experimental InfluxDB features and are intended for internal use only. - - This endpoint represents the first step in the following three-step process - to configure feature flags: - - 1. Use [token authentication](#section/Authentication/TokenAuthentication) or a [user session](#tag/Signin) with this endpoint to retrieve - feature flags and their values. - 2. Follow the instructions to [enable, disable, or override values for feature flags](/influxdb/latest/reference/config-options/#feature-flags). - 3. **Optional**: To confirm that your change is applied, do one of the following: - - - Send a request to this endpoint to retrieve the current feature flag values. - - Send a request to the [`GET /api/v2/config` endpoint](#operation/GetConfig) to retrieve the - current runtime server configuration. - - #### Related guides - - - [InfluxDB configuration options](/influxdb/latest/reference/config-options/) - operationId: GetFlags - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Flags' - description: Success. The response body contains feature flags. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve feature flags - tags: - - Config - /health: - get: - description: Returns the health of the instance. - operationId: GetHealth - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: | - The instance is healthy. - The response body contains the health check items and status. - '503': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The instance is unhealthy. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve the health of the instance - tags: - - Health - - System information endpoints - /api/v2/labels: - get: - operationId: GetLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: Success. The response body contains a list of labels. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List all labels - tags: - - Labels - post: - operationId: PostLabels - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelCreateRequest' - description: The label to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The label was created. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Create a label - tags: - - Labels - /api/v2/labels/{labelID}: - delete: - operationId: DeleteLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Success. The delete was accepted. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a label - tags: - - Labels - get: - operationId: GetLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to update. - in: path - name: labelID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the label. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a label - tags: - - Labels - patch: - operationId: PatchLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the label to update. - in: path - name: labelID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelUpdate' - description: A label update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the updated label. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a label - tags: - - Labels + /api/v2: {} + /api/v2/authorizations: {} + /api/v2/authorizations/{authID}: {} + /api/v2/backup/kv: {} + /api/v2/backup/metadata: {} + /api/v2/backup/shards/{shardID}: {} + /api/v2/buckets: {} + /api/v2/buckets/{bucketID}: {} + /api/v2/buckets/{bucketID}/labels: {} + /api/v2/buckets/{bucketID}/labels/{labelID}: {} + /api/v2/buckets/{bucketID}/members: {} + /api/v2/buckets/{bucketID}/members/{userID}: {} + /api/v2/buckets/{bucketID}/owners: {} + /api/v2/buckets/{bucketID}/owners/{userID}: {} + /api/v2/checks: {} + /api/v2/checks/{checkID}: {} + /api/v2/checks/{checkID}/labels: {} + /api/v2/checks/{checkID}/labels/{labelID}: {} + /api/v2/checks/{checkID}/query: {} + /api/v2/config: {} + /api/v2/dashboards: {} + /api/v2/dashboards/{dashboardID}: {} + /api/v2/dashboards/{dashboardID}/cells: {} + /api/v2/dashboards/{dashboardID}/cells/{cellID}: {} + /api/v2/dashboards/{dashboardID}/cells/{cellID}/view: {} + /api/v2/dashboards/{dashboardID}/labels: {} + /api/v2/dashboards/{dashboardID}/labels/{labelID}: {} + /api/v2/dashboards/{dashboardID}/members: {} + /api/v2/dashboards/{dashboardID}/members/{userID}: {} + /api/v2/dashboards/{dashboardID}/owners: {} + /api/v2/dashboards/{dashboardID}/owners/{userID}: {} + /api/v2/dbrps: {} + /api/v2/dbrps/{dbrpID}: {} + /debug/pprof/all: {} + /debug/pprof/allocs: {} + /debug/pprof/block: {} + /debug/pprof/cmdline: {} + /debug/pprof/goroutine: {} + /debug/pprof/heap: {} + /debug/pprof/mutex: {} + /debug/pprof/profile: {} + /debug/pprof/threadcreate: {} + /debug/pprof/trace: {} + /api/v2/delete: {} + /api/v2/flags: {} + /health: {} + /api/v2/labels: {} + /api/v2/labels/{labelID}: {} /api/v2/maps/mapToken: get: operationId: getMapboxToken @@ -11154,8645 +6816,106 @@ paths: default: $ref: '#/components/responses/ServerError' summary: Get a mapbox token - /api/v2/me: - get: - operationId: GetMe - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: Success. The response body contains the currently authenticated user. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve the currently authenticated user - tags: - - Users - /api/v2/me/password: - put: - description: | - Updates the password for the signed-in [user](/influxdb/latest/reference/glossary/#user). - - This endpoint represents the third step in the following three-step process to let a - user with a user session update their password: - 1. Pass the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) to the `POST /api/v2/signin` - endpoint to create a user session and generate a session cookie. - 2. From the response in the first step, extract the session cookie (`Set-Cookie`) header. - 3. Pass the following in a request to the `PUT /api/v2/me/password` endpoint: - - The `Set-Cookie` header from the second step - - The `Authorization Basic` header with the user's _Basic authentication_ credentials - - `{"password": "NEW_PASSWORD"}` in the request body - - #### InfluxDB Cloud - - - Doesn't let you manage user passwords through the API. - Use the InfluxDB Cloud user interface (UI) to update your password. - - #### Related endpoints - - - [Signin](#tag/Signin) - - [Signout](#tag/Signout) - - [Users](#tag/Users) - - #### Related guides - - - [InfluxDB Cloud - Change your password](/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/latest/reference/glossary/#user) - signed in with [Basic authentication credentials](#section/Authentication/BasicAuthentication). - - #### Related guides - - - [Manage users](/influxdb/v2.6/users/) - example: influxdb-oss-session=19aaaZZZGOvP2GGryXVT2qYftlFKu3bIopurM6AGFow1yF1abhtOlbHfsc-d8gozZFC_6WxmlQIAwLMW5xs523w== - in: cookie - name: influxdb-oss-session - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: The new password. - required: true - responses: - '204': - description: Success. The password is updated. - '400': - description: | - Bad request. - - #### InfluxDB Cloud - - - Doesn't let you manage user passwords through the API; always responds with this status. - - #### InfluxDB OSS - - - Doesn't understand a value passed in the request. - '401': - $ref: '#/components/responses/AuthorizationError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication - security: - - BasicAuthentication: [] - summary: Update a password - tags: - - Users - /metrics: - get: - 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/latest/reference/internals/metrics/). - - Learn how to use InfluxDB to [scrape Prometheus metrics](/influxdb/latest/write-data/developer-tools/scrape-prometheus-metrics/). - - Learn how InfluxDB [parses the Prometheus exposition format](/influxdb/latest/reference/prometheus-metrics/). - operationId: GetMetrics - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - text/plain: - examples: - expositionResponse: - summary: Metrics in plain text - 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 - # 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 - schema: - externalDocs: - description: Prometheus exposition formats - url: https://prometheus.io/docs/instrumenting/exposition_formats - format: Prometheus text-based exposition - type: string - 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. - - 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`) - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Retrieve workload performance metrics - tags: - - Metrics - - System information endpoints - /api/v2/notificationEndpoints: - get: - operationId: GetNotificationEndpoints - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show notification endpoints that belong to specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoints' - description: A list of notification endpoints - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all notification endpoints - tags: - - NotificationEndpoints - post: - operationId: CreateNotificationEndpoint - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostNotificationEndpoint' - description: Notification endpoint to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: Notification endpoint created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}: - delete: - operationId: DeleteNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a notification endpoint - tags: - - NotificationEndpoints - get: - operationId: GetNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: The notification endpoint requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification endpoint - tags: - - NotificationEndpoints - patch: - operationId: PatchNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpointUpdate' - description: Check update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: An updated notification endpoint - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification endpoint - tags: - - NotificationEndpoints - put: - operationId: PutNotificationEndpointsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: A new notification endpoint to replace the existing endpoint with - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationEndpoint' - description: An updated notification endpoint - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification endpoint was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}/labels: - get: - operationId: GetNotificationEndpointsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a notification endpoint - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a notification endpoint - tags: - - NotificationEndpoints - post: - operationId: PostNotificationEndpointIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the notification endpoint - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: - delete: - operationId: DeleteNotificationEndpointsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification endpoint ID. - in: path - name: endpointID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Endpoint or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a notification endpoint - tags: - - NotificationEndpoints - /api/v2/notificationRules: - get: - operationId: GetNotificationRules - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - description: Only show notification rules that belong to a specific organization ID. - in: query - name: orgID - required: true - schema: - type: string - - description: Only show notifications that belong to the specific check ID. - in: query - name: checkID - schema: - type: string - - description: Only return notification rules that "would match" statuses which contain the tag key value pairs provided. - in: query - name: tag - schema: - example: env:prod - pattern: ^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRules' - description: A list of notification rules - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all notification rules - tags: - - NotificationRules - post: - operationId: CreateNotificationRule - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostNotificationRule' - description: Notification rule to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: Notification rule created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}: - delete: - operationId: DeleteNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The check was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a notification rule - tags: - - NotificationRules - get: - operationId: GetNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: The notification rule requested - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification rule - tags: - - NotificationRules - patch: - operationId: PatchNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRuleUpdate' - description: Notification rule update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: An updated notification rule - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification rule was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification rule - tags: - - NotificationRules - put: - operationId: PutNotificationRulesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: Notification rule update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/NotificationRule' - description: An updated notification rule - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The notification rule was not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/labels: - get: - operationId: GetNotificationRulesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a notification rule - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a notification rule - tags: - - NotificationRules - post: - operationId: PostNotificationRuleIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label was added to the notification rule - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/labels/{labelID}: - delete: - operationId: DeleteNotificationRulesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - - description: The ID of the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Rule or label not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete label from a notification rule - tags: - - NotificationRules - /api/v2/notificationRules/{ruleID}/query: - get: - operationId: GetNotificationRulesIDQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The notification rule ID. - in: path - name: ruleID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/FluxResponse' - description: The notification rule query requested - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Invalid request - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Notification rule not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a notification rule query - tags: - - Rules - /api/v2/orgs: - get: - description: | - Lists [organizations](/influxdb/latest/reference/glossary/#organization/). - - To limit which organizations are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all organizations up to the default `limit`. - - #### InfluxDB Cloud - - - Only returns the organization that owns the token passed in the request. - - #### Related guides - - - [View organizations](/influxdb/latest/organizations/view-orgs/) - operationId: GetOrgs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/Descending' - - description: | - An organization name. - Only returns the specified organization. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Only returns the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A user ID. - Only returns organizations where the specified user is a member or owner. - in: query - name: userID - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/orgs - orgs: - - createdAt: '2022-07-17T23:00:30.778487Z' - description: Example InfluxDB organization - id: INFLUX_ORG_ID - links: - buckets: /api/v2/buckets?org=INFLUX_ORG - dashboards: /api/v2/dashboards?org=INFLUX_ORG - labels: /api/v2/orgs/INFLUX_ORG_ID/labels - logs: /api/v2/orgs/INFLUX_ORG_ID/logs - members: /api/v2/orgs/INFLUX_ORG_ID/members - owners: /api/v2/orgs/INFLUX_ORG_ID/owners - secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets - self: /api/v2/orgs/INFLUX_ORG_ID - tasks: /api/v2/tasks?org=InfluxData - name: INFLUX_ORG - updatedAt: '2022-07-17T23:00:30.778487Z' - schema: - $ref: '#/components/schemas/Organizations' - description: Success. The response body contains a list of organizations. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List organizations - tags: - - Organizations - - Security and access endpoints - post: - description: | - Creates an [organization](/influxdb/latest/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/latest/organizations) - operationId: PostOrgs - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PostOrganizationRequest' - description: The organization to create. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - createdAt: '2022-08-24T23:05:52.881317Z' - description: '' - id: INFLUX_ORG_ID - links: - buckets: /api/v2/buckets?org=INFLUX_ORG - dashboards: /api/v2/dashboards?org=INFLUX_ORG - labels: /api/v2/orgs/INFLUX_ORG_ID/labels - logs: /api/v2/orgs/INFLUX_ORG_ID/logs - members: /api/v2/orgs/INFLUX_ORG_ID/members - owners: /api/v2/orgs/INFLUX_ORG_ID/owners - secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets - self: /api/v2/orgs/INFLUX_ORG_ID - tasks: /api/v2/tasks?org=INFLUX_ORG - name: INFLUX_ORG - updatedAt: '2022-08-24T23:05:52.881318Z' - schema: - $ref: '#/components/schemas/Organization' - description: Created. The response body contains the organization information. - '400': - $ref: '#/components/responses/BadRequestError' - examples: - invalidRequest: - summary: The `name` field is missing from the request body. - value: - code: invalid - message: org name is empty - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create an organization - tags: - - Organizations - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/orgs \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "name": "INFLUX_ORG", - "description: "Example InfluxDB organization" - }' - /api/v2/orgs/{orgID}: - delete: - description: | - Deletes an organization. - - Deleting an organization from InfluxDB Cloud can't be undone. - Once deleted, all data associated with the organization is removed. - - #### InfluxDB Cloud - - - Does the following when you send a delete request: - - 1. Validates the request and queues the delete. - 2. Returns an HTTP `204` status code if queued; _error_ otherwise. - 3. Handles the delete asynchronously. - - #### InfluxDB OSS - - - Validates the request, handles the delete synchronously, - and then responds with success or failure. - - #### Limitations - - - Only one organization can be deleted per request. - - #### Related guides - - - [Delete organizations](/influxdb/latest/organizations/delete-orgs/) - operationId: DeleteOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to delete. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - The organization is queued for deletion. - - #### InfluxDB OSS - - The organization is deleted. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested organization was not found. - value: - code: not found - message: org not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - InfluxDB can't find the organization. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete an organization - tags: - - Organizations - get: - description: | - Retrieves an organization. - - Use this endpoint to retrieve information for a specific organization. - - #### Related guides - - - [View organizations](/influxdb/latest/organizations/view-orgs/) - operationId: GetOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to retrieve. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: | - Success. - The response body contains the organization information. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested organization wasn't found. - value: - code: not found - message: organization not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - Organization not found. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve an organization - tags: - - Organizations - - Security and access endpoints - patch: - description: | - Updates an organization. - - Use this endpoint to update properties - (`name`, `description`) of an organization. - - Updating an organizationโ€™s name affects all resources that reference the - organization by name, including the following: - - - Queries - - Dashboards - - Tasks - - Telegraf configurations - - Templates - - If you change an organization name, be sure to update the organization name - in these resources as well. - - #### Related Guides - - - [Update an organization](/influxdb/latest/organizations/update-org/) - operationId: PatchOrgsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to update. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PatchOrganizationRequest' - description: The organization update to apply. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Organization' - description: Success. The response body contains the updated organization. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update an organization - tags: - - Organizations - /api/v2/orgs/{orgID}/members: - get: - description: | - Lists all users that belong to an organization. - - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have - permission to access InfluxDB. - - [Members](/influxdb/latest/reference/glossary/#member) are users - within the organization. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `read-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve - members for. - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) - operationId: GetOrgsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to retrieve users for. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/orgs/055aa4783aa38398/members - users: - - id: 791df274afd48a83 - links: - self: /api/v2/users/791df274afd48a83 - name: example_user_1 - role: member - status: active - - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_2 - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. - The response body contains a list of all users within the organization. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - content: - application/json: - examples: - notFound: - summary: | - The requested organization wasn't found. - value: - code: not found - message: 404 page not found - schema: - $ref: '#/components/schemas/Error' - description: | - Not found. - InfluxDB can't find the organization. - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all members of an organization - tags: - - Organizations - - Security and access endpoints - post: - description: | - Add a user to an organization. - - InfluxDB [users](/influxdb/latest/reference/glossary/#user) have - permission to access InfluxDB. - - [Members](/influxdb/latest/reference/glossary/#member) are users - within the organization. - - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to add a member to. - - #### Related guides - - - [Manage users](/influxdb/latest/users/) - - [Manage members](/influxdb/latest/organizations/members/) - operationId: PostOrgsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - The user to add to the organization. - required: true - responses: - '201': - content: - application/json: - examples: - successResponse: - value: - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_1 - role: member - status: active - schema: - $ref: '#/components/schemas/ResourceMember' - description: | - Success. - The response body contains the user information. - '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: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to an organization - tags: - - Organizations - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "id": "09cfb87051cbe000" - }' - /api/v2/orgs/{orgID}/members/{userID}: - delete: - description: | - Removes a member from an organization. - - Use this endpoint to remove a user's member privileges for an organization. - Removing member privileges removes the user's `read` and `write` permissions - from the organization. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Member permissions are separate from API token permissions. - - Member permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an - owner from. - - #### Related guides - - - [Manage members](/influxdb/latest/organizations/members/) - operationId: DeleteOrgsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The ID of the organization to remove a user from. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer a member of the organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from an organization - tags: - - Organizations - - Security and access endpoints - /api/v2/orgs/{orgID}/owners: - get: - description: | - Lists all owners of an organization. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Required permissions - - - `read-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a - list of owners from. - operationId: GetOrgsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The ID of the organization to list owners for. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - links: - self: /api/v2/orgs/055aa4783aa38398/owners - users: - - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_2 - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of organization owners - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Organization not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of an organization - tags: - - Organizations - - Security and access endpoints - post: - description: | - Adds an owner to an organization. - - Use this endpoint to assign the organization `owner` role to a user. - - #### InfluxDB Cloud - - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to add an owner for. - - #### Related endpoints - - - [Authorizations](#tag/Authorizations-(API-tokens)) - operationId: PostOrgsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization that you want to add an owner for. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - examples: - successResponse: - value: - id: 09cfb87051cbe000 - links: - self: /api/v2/users/09cfb87051cbe000 - name: example_user_1 - role: owner - status: active - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: The user to add as an owner of the organization. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: | - Success. The user is an owner of the organization. - The response body contains the owner with role and user detail. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to an organization - tags: - - Organizations - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header "Accept: application/json" \ - --header "Content-Type: application/json" \ - --data '{ - "id": "09cfb87051cbe000" - }' - /api/v2/orgs/{orgID}/owners/{userID}: - delete: - description: | - Removes an [owner](/influxdb/latest/reference/glossary/#owner) from - the organization. - - Organization owners have permission to delete organizations and remove user and member - permissions from the organization. - - #### InfluxDB Cloud - - Doesn't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - #### Limitations - - - Owner permissions are separate from API token permissions. - - Owner permissions are used in the context of the InfluxDB UI. - - #### Required permissions - - - `write-orgs INFLUX_ORG_ID` - - *`INFLUX_ORG_ID`* is the ID of the organization that you want to - remove an owner from. - - #### Related endpoints - - [Authorizations](#tag/Authorizations-(API-tokens)) - operationId: DeleteOrgsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to remove. - in: path - name: userID - required: true - schema: - type: string - - description: | - The ID of the organization to remove an owner from. - in: path - name: orgID - required: true - schema: - type: string - responses: - '204': - description: | - Success. - The user is no longer an owner of the organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from an organization - tags: - - Organizations - - Security and access endpoints - /api/v2/orgs/{orgID}/secrets: - get: - operationId: GetOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/SecretKeysResponse' - description: A list of all secret keys - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all secret keys for an organization - tags: - - Secrets - - Security and access endpoints - patch: - operationId: PatchOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Secrets' - description: Secret key value pairs to update/add - required: true - responses: - '204': - description: Keys successfully patched - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update secrets in an organization - tags: - - Secrets - /api/v2/orgs/{orgID}/secrets/{secretID}: - delete: - operationId: DeleteOrgsIDSecretsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - - description: The secret ID. - in: path - name: secretID - required: true - schema: - type: string - responses: - '204': - description: Keys successfully deleted - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Delete a secret from an organization - tags: - - Secrets - - Security and access endpoints - /api/v2/orgs/{orgID}/secrets/delete: - post: - deprecated: true - operationId: PostOrgsIDSecrets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: path - name: orgID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/SecretKeys' - description: Secret key to delete - required: true - responses: - '204': - description: Keys successfully patched - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete secrets from an organization - tags: - - Secrets - - Security and access endpoints - /ping: - get: - description: | - Retrieves the status and InfluxDB version of the instance. - - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. - - #### InfluxDB Cloud - - - Isn't versioned and doesn't return `X-Influxdb-Version` in the headers. - - #### Related guides - - - [Influx ping](/influxdb/latest/reference/cli/influx/ping/) - operationId: GetPing - responses: - '204': - description: | - Success. - Headers contain InfluxDB version information. - headers: - X-Influxdb-Build: - description: | - The type of InfluxDB build. - schema: - type: string - X-Influxdb-Version: - description: | - The version of InfluxDB. - - #### InfluxDB Cloud - - Doesn't return version. - schema: - type: integer - servers: [] - summary: Get the status of the instance - tags: - - Ping - - System information endpoints - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "http://localhost:8086/ping" - head: - description: | - Returns the status and InfluxDB version of the instance. - - Use this endpoint to monitor uptime for the InfluxDB instance. The response - returns a HTTP `204` status code to inform you the instance is available. - - #### InfluxDB Cloud - - - Isn't versioned and doesn't return `X-Influxdb-Version` in the headers. - - #### Related guides - - - [Influx ping](/influxdb/latest/reference/cli/influx/ping/) - operationId: HeadPing - responses: - '204': - description: | - Success. - Headers contain InfluxDB version information. - headers: - X-Influxdb-Build: - description: The type of InfluxDB build. - schema: - type: string - X-Influxdb-Version: - description: | - The version of InfluxDB. - - #### InfluxDB Cloud - - Doesn't return version. - schema: - type: integer - servers: [] - summary: Get the status of the instance - tags: - - Ping - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request HEAD "http://localhost:8086/ping" - /api/v2/query: - post: - description: | - Retrieves data from buckets. - - Use this endpoint to send a Flux query request and retrieve data from a bucket. - - #### Rate limits (with InfluxDB Cloud) - - `read` rate limits apply. - For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Query with the InfluxDB API](/influxdb/latest/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. - in: header - name: Accept-Encoding - schema: - default: identity - description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - enum: - - application/json - - application/vnd.flux - type: string - - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - in: query - name: org - schema: - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Queries the bucket in the organization associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or `orgID` parameter. - - Queries the bucket in the specified organization. - in: query - name: orgID - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - application/vnd.flux: - example: | - from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement") - schema: - type: string - description: Flux query or specification to execute - responses: - '200': - content: - application/csv: - example: | - result,table,_start,_stop,_time,region,host,_value - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25 - mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62 - schema: - 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. - schema: - default: identity - description: | - The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - Trace-Id: - description: The trace ID, if generated, of the request. - schema: - description: Trace ID of a request. - type: string - '400': - content: - application/json: - examples: - orgNotFound: - summary: Organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb/latest/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](/influxdb/latest/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Query data - tags: - - Data I/O endpoints - - Query - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \ - --header 'Content-Type: application/vnd.flux' \ - --header 'Accept: application/csv \ - --header 'Authorization: Token INFLUX_API_TOKEN' \ - --data 'from(bucket: "example-bucket") - |> range(start: -5m) - |> filter(fn: (r) => r._measurement == "example-measurement")' - /api/v2/query/analyze: - post: - description: | - Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax - errors and returns the list of errors. - - In the following sample query, `from()` is missing the property key. - - ```json - { "query": "from(: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")", - "type": "flux" - } - ``` - - If you pass this in a request to the `/api/v2/analyze` endpoint, - InfluxDB returns an `errors` list that contains an error object for the missing key. - - #### Limitations - - - The endpoint doesn't validate values in the query--for example: - - - The following sample query has correct syntax, but contains an incorrect `from()` property key: - - ```json - { "query": "from(foo: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")", - "type": "flux" - } - ``` - - If you pass this in a request to the `/api/v2/analyze` endpoint, - InfluxDB returns an empty `errors` list. - operationId: PostQueryAnalyze - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Query' - description: Flux query to analyze - responses: - '200': - content: - application/json: - examples: - missingQueryPropertyKey: - description: | - Returns an error object if the Flux query is missing a property key. - - The following sample query is missing the _`bucket`_ property key: - - ```json - { - "query": "from(: \"iot_center\")\ - ... - } - ``` - summary: Missing property key error - value: - errors: - - character: 0 - column: 6 - line: 1 - message: missing property key - schema: - $ref: '#/components/schemas/AnalyzeQueryResponse' - description: | - Success. - The response body contains the list of `errors`. - If the query syntax is valid, the endpoint returns an empty `errors` list. - '400': - content: - application/json: - examples: - invalidJSONStringValue: - description: If the request body contains invalid JSON, returns `invalid` and problem detail. - summary: Invalid JSON - value: - code: invalid - message: 'invalid json: invalid character ''\'''' looking for beginning of value' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the problem. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - default: - content: - application/json: - examples: - emptyJSONObject: - description: | - If the request body contains an empty JSON object, returns `internal error`. - summary: Empty JSON object in request body - value: - code: internal error - message: An internal error has occurred - check server logs - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - headers: - X-Influx-Error: - description: A string that describes the problem. - schema: - type: string - X-Influx-Reference: - description: The numeric reference code for the error type. - schema: - type: integer - X-Platform-Error-Code: - description: The reason for the error. - schema: - example: internal error - type: string - summary: Analyze a Flux query - tags: - - Query - x-codeSamples: - - label: 'cURL: Analyze a Flux query' - lang: Shell - source: | - curl -v --request POST \ - "http://localhost:8086/api/v2/query/analyze" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header 'Content-type: application/json' \ - --header 'Accept: application/json' \ - --data-binary @- << EOF - { "query": "from(bucket: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")", - "type": "flux" - } - EOF - /api/v2/query/ast: - post: - description: | - Analyzes a Flux query and returns a complete package source [Abstract Syntax - Tree (AST)](/influxdb/latest/reference/glossary/#abstract-syntax-tree-ast) - for the query. - - Use this endpoint for deep query analysis such as debugging unexpected query - results. - - A Flux query AST provides a semantic, tree-like representation with contextual - information about the query. The AST illustrates how the query is distributed - into different components for execution. - - #### Limitations - - - The endpoint doesn't validate values in the query--for example: - - The following sample Flux query has correct syntax, but contains an incorrect `from()` property key: - - ```js - from(foo: "iot_center") - |> range(start: -90d) - |> filter(fn: (r) => r._measurement == "environment") - ``` - - The following sample JSON shows how to pass the query in the request body: - - ```js - from(foo: "iot_center") - |> range(start: -90d) - |> filter(fn: (r) => r._measurement == "environment") - ``` - - The following code sample shows how to pass the query as JSON in the request body: - - ```json - { "query": "from(foo: \"iot_center\")\ - |> range(start: -90d)\ - |> filter(fn: (r) => r._measurement == \"environment\")" - } - ``` - - Passing this to `/api/v2/query/ast` will return a successful response - with a generated AST. - operationId: PostQueryAst - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LanguageRequest' - description: The Flux query to analyze. - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - ast: - files: - - body: - - expression: - argument: - argument: - arguments: - - location: - end: - column: 25 - line: 1 - source: 'bucket: "example-bucket"' - start: - column: 6 - line: 1 - properties: - - key: - location: - end: - column: 12 - line: 1 - source: bucket - start: - column: 6 - line: 1 - name: bucket - type: Identifier - location: - end: - column: 25 - line: 1 - source: 'bucket: "example-bucket"' - start: - column: 6 - line: 1 - type: Property - value: - location: - end: - column: 25 - line: 1 - source: '"example-bucket"' - start: - column: 14 - line: 1 - type: StringLiteral - value: example-bucket - type: ObjectExpression - callee: - location: - end: - column: 5 - line: 1 - source: from - start: - column: 1 - line: 1 - name: from - type: Identifier - location: - end: - column: 26 - line: 1 - source: 'from(bucket: "example-bucket")' - start: - column: 1 - line: 1 - type: CallExpression - call: - arguments: - - location: - end: - column: 46 - line: 1 - source: 'start: -5m' - start: - column: 36 - line: 1 - properties: - - key: - location: - end: - column: 41 - line: 1 - source: start - start: - column: 36 - line: 1 - name: start - type: Identifier - location: - end: - column: 46 - line: 1 - source: 'start: -5m' - start: - column: 36 - line: 1 - type: Property - value: - argument: - location: - end: - column: 46 - line: 1 - source: 5m - start: - column: 44 - line: 1 - type: DurationLiteral - values: - - magnitude: 5 - unit: m - location: - end: - column: 46 - line: 1 - source: '-5m' - start: - column: 43 - line: 1 - operator: '-' - type: UnaryExpression - type: ObjectExpression - callee: - location: - end: - column: 35 - line: 1 - source: range - start: - column: 30 - line: 1 - name: range - type: Identifier - location: - end: - column: 47 - line: 1 - source: 'range(start: -5m)' - start: - column: 30 - line: 1 - type: CallExpression - location: - end: - column: 47 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m)' - start: - column: 1 - line: 1 - type: PipeExpression - call: - arguments: - - location: - end: - column: 108 - line: 1 - source: 'fn: (r) => r._measurement == "example-measurement"' - start: - column: 58 - line: 1 - properties: - - key: - location: - end: - column: 60 - line: 1 - source: fn - start: - column: 58 - line: 1 - name: fn - type: Identifier - location: - end: - column: 108 - line: 1 - source: 'fn: (r) => r._measurement == "example-measurement"' - start: - column: 58 - line: 1 - type: Property - value: - body: - left: - location: - end: - column: 83 - line: 1 - source: r._measurement - start: - column: 69 - line: 1 - object: - location: - end: - column: 70 - line: 1 - source: r - start: - column: 69 - line: 1 - name: r - type: Identifier - property: - location: - end: - column: 83 - line: 1 - source: _measurement - start: - column: 71 - line: 1 - name: _measurement - type: Identifier - type: MemberExpression - location: - end: - column: 108 - line: 1 - source: r._measurement == "example-measurement" - start: - column: 69 - line: 1 - operator: '==' - right: - location: - end: - column: 108 - line: 1 - source: '"example-measurement"' - start: - column: 87 - line: 1 - type: StringLiteral - value: example-measurement - type: BinaryExpression - location: - end: - column: 108 - line: 1 - source: (r) => r._measurement == "example-measurement" - start: - column: 62 - line: 1 - params: - - key: - location: - end: - column: 64 - line: 1 - source: r - start: - column: 63 - line: 1 - name: r - type: Identifier - location: - end: - column: 64 - line: 1 - source: r - start: - column: 63 - line: 1 - type: Property - value: null - type: FunctionExpression - type: ObjectExpression - callee: - location: - end: - column: 57 - line: 1 - source: filter - start: - column: 51 - line: 1 - name: filter - type: Identifier - location: - end: - column: 109 - line: 1 - source: 'filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 51 - line: 1 - type: CallExpression - location: - end: - column: 109 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 1 - line: 1 - type: PipeExpression - location: - end: - column: 109 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 1 - line: 1 - type: ExpressionStatement - imports: null - location: - end: - column: 109 - line: 1 - source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")' - start: - column: 1 - line: 1 - metadata: parser-type=rust - package: null - type: File - package: main - type: Package - schema: - $ref: '#/components/schemas/ASTResponse' - description: | - Success. - The response body contains an Abstract Syntax Tree (AST) of the Flux query. - '400': - content: - application/json: - examples: - invalidASTValue: - description: | - If the request body contains a missing property key in `from()`, - returns `invalid` and problem detail. - summary: Invalid AST - value: - code: invalid - message: 'invalid AST: loc 1:6-1:19: missing property key' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - InfluxDB is unable to parse the request. - The response body contains detail about the problem. - headers: - X-Platform-Error-Code: - description: | - The reason for the error. - schema: - example: invalid - type: string - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - summary: Generate a query Abstract Syntax Tree (AST) - tags: - - Query - x-codeSamples: - - label: 'cURL: Analyze and generate AST for the query' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/query/ast" \ - --header 'Content-Type: application/json' \ - --header 'Accept: application/json' \ - --header "Authorization: Token INFLUX_TOKEN" \ - --data-binary @- << EOL - { - "query": "from(bucket: \"INFLUX_BUCKET_NAME\")\ - |> range(start: -5m)\ - |> filter(fn: (r) => r._measurement == \"example-measurement\")" - } - EOL - /api/v2/query/suggestions: - get: - description: | - Lists Flux query suggestions. Each suggestion contains a - [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - name and parameters. - - Use this endpoint to retrieve a list of Flux query suggestions used in the - InfluxDB Flux Query Builder. - - #### Limitations - - - When writing a query, avoid using `_functionName()` helper functions - exposed by this endpoint. Helper function names have an underscore (`_`) - prefix and aren't meant to be used directly in queries--for example: - - - To sort on a column and keep the top n records, use the - `top(n, columns=["_value"], tables=<-)` function instead of the `_sortLimit` - helper function. `top` uses `_sortLimit`. - - #### Related Guides - - - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - operationId: GetQuerySuggestions - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - funcs: - - name: _fillEmpty - params: - createEmpty: bool - tables: stream - - name: _highestOrLowest - params: - _sortLimit: function - column: invalid - groupColumns: array - 'n': invalid - reducer: function - tables: stream - - name: _hourSelection - params: - location: object - start: int - stop: int - tables: stream - timeColumn: string - - name: _sortLimit - params: - columns: array - desc: bool - 'n': int - tables: stream - - name: _window - params: - createEmpty: bool - every: duration - location: object - offset: duration - period: duration - startColumn: string - stopColumn: string - tables: stream - timeColumn: string - - name: aggregateWindow - params: - column: invalid - createEmpty: bool - every: duration - fn: function - location: object - offset: duration - period: duration - tables: stream - timeDst: string - timeSrc: string - - name: bool - params: - v: invalid - - name: bottom - params: - columns: array - 'n': int - tables: stream - - name: buckets - params: - host: string - org: string - orgID: string - token: string - - name: bytes - params: - v: invalid - - name: cardinality - params: - bucket: string - bucketID: string - host: string - org: string - orgID: string - predicate: function - start: invalid - stop: invalid - token: string - - name: chandeMomentumOscillator - params: - columns: array - 'n': int - tables: stream - - name: columns - params: - column: string - tables: stream - - name: contains - params: - set: array - value: invalid - - name: count - params: - column: string - tables: stream - - name: cov - params: - 'on': array - pearsonr: bool - x: invalid - 'y': invalid - - name: covariance - params: - columns: array - pearsonr: bool - tables: stream - valueDst: string - - name: cumulativeSum - params: - columns: array - tables: stream - - name: derivative - params: - columns: array - initialZero: bool - nonNegative: bool - tables: stream - timeColumn: string - unit: duration - - name: die - params: - msg: string - - name: difference - params: - columns: array - initialZero: bool - keepFirst: bool - nonNegative: bool - tables: stream - - name: display - params: - v: invalid - - name: distinct - params: - column: string - tables: stream - - name: doubleEMA - params: - 'n': int - tables: stream - - name: drop - params: - columns: array - fn: function - tables: stream - - name: duplicate - params: - as: string - column: string - tables: stream - - name: duration - params: - v: invalid - - name: elapsed - params: - columnName: string - tables: stream - timeColumn: string - unit: duration - - name: exponentialMovingAverage - params: - 'n': int - tables: stream - - name: fill - params: - column: string - tables: stream - usePrevious: bool - value: invalid - - name: filter - params: - fn: function - onEmpty: string - tables: stream - - name: findColumn - params: - column: string - fn: function - tables: stream - - name: findRecord - params: - fn: function - idx: int - tables: stream - - name: first - params: - column: string - tables: stream - - name: float - params: - v: invalid - - name: from - params: - bucket: string - bucketID: string - host: string - org: string - orgID: string - token: string - - name: getColumn - params: - column: string - - name: getRecord - params: - idx: int - - name: group - params: - columns: array - mode: string - tables: stream - - name: highestAverage - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: highestCurrent - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: highestMax - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: histogram - params: - bins: array - column: string - countColumn: string - normalize: bool - tables: stream - upperBoundColumn: string - - name: histogramQuantile - params: - countColumn: string - minValue: float - quantile: float - tables: stream - upperBoundColumn: string - valueColumn: string - - name: holtWinters - params: - column: string - interval: duration - 'n': int - seasonality: int - tables: stream - timeColumn: string - withFit: bool - - name: hourSelection - params: - location: object - start: int - stop: int - tables: stream - timeColumn: string - - name: increase - params: - columns: array - tables: stream - - name: int - params: - v: invalid - - name: integral - params: - column: string - interpolate: string - tables: stream - timeColumn: string - unit: duration - - name: join - params: - method: string - 'on': array - tables: invalid - - name: kaufmansAMA - params: - column: string - 'n': int - tables: stream - - name: kaufmansER - params: - 'n': int - tables: stream - - name: keep - params: - columns: array - fn: function - tables: stream - - name: keyValues - params: - keyColumns: array - tables: stream - - name: keys - params: - column: string - tables: stream - - name: last - params: - column: string - tables: stream - - name: length - params: - arr: array - - name: limit - params: - 'n': int - offset: int - tables: stream - - name: linearBins - params: - count: int - infinity: bool - start: float - width: float - - name: logarithmicBins - params: - count: int - factor: float - infinity: bool - start: float - - name: lowestAverage - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: lowestCurrent - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: lowestMin - params: - column: string - groupColumns: array - 'n': int - tables: stream - - name: map - params: - fn: function - mergeKey: bool - tables: stream - - name: max - params: - column: string - tables: stream - - name: mean - params: - column: string - tables: stream - - name: median - params: - column: string - compression: float - method: string - tables: stream - - name: min - params: - column: string - tables: stream - - name: mode - params: - column: string - tables: stream - - name: movingAverage - params: - 'n': int - tables: stream - - name: now - params: {} - - name: pearsonr - params: - 'on': array - x: invalid - 'y': invalid - - name: pivot - params: - columnKey: array - rowKey: array - tables: stream - valueColumn: string - - name: quantile - params: - column: string - compression: float - method: string - q: float - tables: stream - - name: range - params: - start: invalid - stop: invalid - tables: stream - - name: reduce - params: - fn: function - identity: invalid - tables: stream - - name: relativeStrengthIndex - params: - columns: array - 'n': int - tables: stream - - name: rename - params: - columns: invalid - fn: function - tables: stream - - name: sample - params: - column: string - 'n': int - pos: int - tables: stream - - name: set - params: - key: string - tables: stream - value: string - - name: skew - params: - column: string - tables: stream - - name: sort - params: - columns: array - desc: bool - tables: stream - - name: spread - params: - column: string - tables: stream - - name: stateCount - params: - column: string - fn: function - tables: stream - - name: stateDuration - params: - column: string - fn: function - tables: stream - timeColumn: string - unit: duration - - name: stateTracking - params: - countColumn: string - durationColumn: string - durationUnit: duration - fn: function - tables: stream - timeColumn: string - - name: stddev - params: - column: string - mode: string - tables: stream - - name: string - params: - v: invalid - - name: sum - params: - column: string - tables: stream - - name: tableFind - params: - fn: function - tables: stream - - name: tail - params: - 'n': int - offset: int - tables: stream - - name: time - params: - v: invalid - - name: timeShift - params: - columns: array - duration: duration - tables: stream - - name: timeWeightedAvg - params: - tables: stream - unit: duration - - name: timedMovingAverage - params: - column: string - every: duration - period: duration - tables: stream - - name: to - params: - bucket: string - bucketID: string - fieldFn: function - host: string - measurementColumn: string - org: string - orgID: string - tables: stream - tagColumns: array - timeColumn: string - token: string - - name: toBool - params: - tables: stream - - name: toFloat - params: - tables: stream - - name: toInt - params: - tables: stream - - name: toString - params: - tables: stream - - name: toTime - params: - tables: stream - - name: toUInt - params: - tables: stream - - name: today - params: {} - - name: top - params: - columns: array - 'n': int - tables: stream - - name: tripleEMA - params: - 'n': int - tables: stream - - name: tripleExponentialDerivative - params: - 'n': int - tables: stream - - name: truncateTimeColumn - params: - tables: stream - timeColumn: invalid - unit: duration - - name: uint - params: - v: invalid - - name: union - params: - tables: array - - name: unique - params: - column: string - tables: stream - - name: wideTo - params: - bucket: string - bucketID: string - host: string - org: string - orgID: string - tables: stream - token: string - - name: window - params: - createEmpty: bool - every: duration - location: object - offset: duration - period: duration - startColumn: string - stopColumn: string - tables: stream - timeColumn: string - - name: yield - params: - name: string - tables: stream - schema: - $ref: '#/components/schemas/FluxSuggestions' - description: | - Success. - 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`. - summary: Invalid URL - value: | - Moved Permanently - schema: - properties: - body: - description: Response message with URL of requested resource. - readOnly: true - type: string - description: | - Moved Permanently. - InfluxData has moved the URL of the endpoint. - Use `/api/v2/query/suggestions` (without a trailing slash). - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error. - summary: List Flux query suggestions - tags: - - Query - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "INFLUX_URL/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 - requested function. - - Use this endpoint to pass a branching suggestion (a Flux function name) and - retrieve the parameters of the requested function. - - #### Limitations - - - Use `/api/v2/query/suggestions/{name}` (without a trailing slash). - `/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a - HTTP `301 Moved Permanently` status. - - - The function `name` must exist and must be spelled correctly. - - #### Related Guides - - - [List of all Flux functions](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) - operationId: GetQuerySuggestionsName - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [Flux function](https://docs.influxdata.com/flux/v0.x/stdlib/all-functions/) name. - in: path - name: name - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - successResponse: - value: - name: sum - params: - column: string - tables: stream - schema: - $ref: '#/components/schemas/FluxSuggestion' - description: | - Success. - The response body contains the function name and parameters. - '500': - content: - application/json: - examples: - internalError: - description: | - The requested function doesn't exist. - summary: Invalid function - value: - code: internal error - message: An internal error has occurred - schema: - $ref: '#/components/schemas/Error' - description: | - Internal server error. - The value passed for _`name`_ may have been misspelled. - summary: Retrieve a query suggestion for a branching suggestion - tags: - - Query - x-codeSamples: - - label: cURL - lang: Shell - source: | - curl --request GET "INFLUX_URL/api/v2/query/suggestions/sum/" \ - --header "Accept: application/json" \ - --header "Authorization: Token INFLUX_API_TOKEN" - /ready: - get: - operationId: GetReady - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Ready' - description: The instance is ready - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - servers: [] - summary: Get the readiness of an instance at startup - tags: - - Ready - - System information endpoints - /api/v2/remotes: - get: - operationId: GetRemoteConnections - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - required: true - schema: - type: string - - in: query - name: name - schema: - type: string - - in: query - name: remoteURL - schema: - format: uri - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnections' - description: List of remote connections - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List all remote connections - tags: - - RemoteConnections - post: - operationId: PostRemoteConnection - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnectionCreationRequest' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnection' - description: Remote connection saved - '400': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Register a new remote connection - tags: - - RemoteConnections - /api/v2/remotes/{remoteID}: - delete: - operationId: DeleteRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - responses: - '204': - description: Remote connection info deleted. - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a remote connection - tags: - - RemoteConnections - get: - operationId: GetRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnection' - description: Remote connection - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a remote connection - tags: - - RemoteConnections - patch: - operationId: PatchRemoteConnectionByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: remoteID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnectionUpdateRequest' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/RemoteConnection' - description: Updated information saved - '400': - $ref: '#/components/responses/GeneralServerError' - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a remote connection - tags: - - RemoteConnections - /api/v2/replications: - get: - operationId: GetReplications - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. - in: query - name: orgID - required: true - schema: - type: string - - in: query - name: name - schema: - type: string - - in: query - name: remoteID - schema: - type: string - - in: query - name: localBucketID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Replications' - description: List of replications - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List all replications - tags: - - Replications - post: - operationId: PostReplication - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: If true, validate the replication, but don't save it. - in: query - name: validate - schema: - default: false - type: boolean - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ReplicationCreationRequest' - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Replication' - description: Replication saved - '204': - description: Replication validated, but not saved - '400': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Register a new replication - tags: - - Replications - /api/v2/replications/{replicationID}: - delete: - operationId: DeleteReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - responses: - '204': - description: Replication deleted. - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a replication - tags: - - Replications - get: - operationId: GetReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Replication' - description: Replication - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a replication - tags: - - Replications - patch: - operationId: PatchReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - - description: If true, validate the updated information, but don't save it. - in: query - name: validate - schema: - default: false - type: boolean - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ReplicationUpdateRequest' - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Replication' - description: Updated information saved - '204': - description: Updated replication validated, but not saved - '400': - $ref: '#/components/responses/GeneralServerError' - '404': - $ref: '#/components/responses/GeneralServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a replication - tags: - - Replications - /api/v2/replications/{replicationID}/validate: - post: - operationId: PostValidateReplicationByID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: path - name: replicationID - required: true - schema: - type: string - responses: - '204': - description: Replication is valid - '400': - $ref: '#/components/responses/GeneralServerError' - description: Replication failed validation - default: - $ref: '#/components/responses/GeneralServerError' - summary: Validate a replication - tags: - - Replications - /api/v2/resources: - get: - operationId: GetResources - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - items: - type: string - type: array - description: All resources targets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: List all known resources - tags: - - Resources - - System information endpoints - /api/v2/restore/bucket/{bucketID}: - post: - deprecated: true - operationId: PostRestoreBucketID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The bucket ID. - in: path - name: bucketID - required: true - schema: - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - requestBody: - content: - text/plain: - schema: - format: byte - type: string - description: Database info serialized as protobuf. - required: true - responses: - '200': - content: - application/json: - schema: - format: byte - type: string - description: ID mappings for shards in bucket. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Overwrite storage metadata for a bucket with shard info from a backup. - tags: - - Restore - /api/v2/restore/bucketMetadata: - post: - operationId: PostRestoreBucketMetadata - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/BucketMetadataManifest' - description: Metadata manifest for a bucket. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/RestoredBucketMappings' - description: ID mappings for shards in new bucket. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Create a new bucket pre-seeded with shard info from a backup. - tags: - - Restore - /api/v2/restore/kv: - post: - 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. - in: header - name: Content-Encoding - schema: - default: identity - description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - requestBody: - content: - text/plain: - schema: - format: binary - type: string - description: Full KV snapshot. - required: true - responses: - '200': - content: - application/json: - schema: - properties: - token: - 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. - '204': - description: KV store successfully overwritten. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Overwrite the embedded KV store on the server with a backed-up snapshot. - tags: - - Restore - /api/v2/restore/shards/{shardID}: - post: - 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. - 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. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - - description: The shard ID. - in: path - name: shardID - required: true - schema: - type: string - requestBody: - content: - text/plain: - schema: - format: binary - type: string - description: TSM snapshot. - required: true - responses: - '204': - description: TSM snapshot successfully restored. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Restore a TSM snapshot into a shard. - tags: - - Restore - /api/v2/restore/sql: - post: - 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. - 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. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - default: application/octet-stream - enum: - - application/octet-stream - type: string - requestBody: - content: - text/plain: - schema: - format: binary - type: string - description: Full SQL snapshot. - required: true - responses: - '204': - description: SQL store successfully overwritten. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Overwrite the embedded SQL store on the server with a backed-up snapshot. - tags: - - Restore - /api/v2/scrapers: - get: - operationId: GetScrapers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: Specifies the name of the scraper target. - in: query - name: name - schema: - type: string - - description: List of scraper target IDs to return. If both `id` and `owner` are specified, only `id` is used. - in: query - name: id - schema: - items: - type: string - type: array - - description: Specifies the organization ID of the scraper target. - in: query - name: orgID - schema: - type: string - - description: Specifies the organization name of the scraper target. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponses' - description: All scraper targets - summary: List all scraper targets - tags: - - Scraper Targets - post: - operationId: PostScrapers - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetRequest' - description: Scraper target to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponse' - description: Scraper target created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Create a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}: - delete: - operationId: DeleteScrapersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the scraper target. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '204': - description: Scraper target deleted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Delete a scraper target - tags: - - Scraper Targets - get: - operationId: GetScrapersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the scraper target. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponse' - description: The scraper target - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Retrieve a scraper target - tags: - - Scraper Targets - patch: - operationId: PatchScrapersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The identifier of the scraper target. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetRequest' - description: Scraper target update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ScraperTargetResponse' - description: Scraper target updated - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Update a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/labels: - get: - operationId: GetScrapersIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of labels for a scraper target. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a scraper target - tags: - - Scraper Targets - post: - operationId: PostScrapersIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/labels/{labelID}: - delete: - operationId: DeleteScrapersIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Scraper target not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/members: - get: - operationId: GetScrapersIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of scraper target members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a scraper target - tags: - - Scraper Targets - post: - operationId: PostScrapersIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to scraper targets - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/members/{userID}: - delete: - operationId: DeleteScrapersIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/owners: - get: - operationId: GetScrapersIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: A list of scraper target owners - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a scraper target - tags: - - Scraper Targets - post: - operationId: PostScrapersIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Scraper target owner added - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a scraper target - tags: - - Scraper Targets - /api/v2/scrapers/{scraperTargetID}/owners/{userID}: - delete: - operationId: DeleteScrapersIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The scraper target ID. - in: path - name: scraperTargetID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a scraper target - tags: - - Scraper Targets - /api/v2/setup: - get: - description: Returns `true` if no default user, organization, or bucket has been created. - operationId: GetSetup - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/IsOnboarding' - description: allowed true or false - summary: Check if database has default user, org, bucket - tags: - - Setup - post: - description: Post an onboarding request to set up initial user, org and bucket. - operationId: PostSetup - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingRequest' - description: Source to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/OnboardingResponse' - description: Created default user, bucket, org - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Set up initial user, org and bucket - tags: - - Setup - /api/v2/signin: - post: - description: | - Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication) - for a [user](/influxdb/latest/reference/glossary/#user), - and then, if successful, generates a user session. - - To authenticate a user, pass the HTTP `Authorization` header with the - `Basic` scheme and the base64-encoded username and password. - For syntax and more information, see [Basic Authentication](#section/Authentication/BasicAuthentication) for - syntax and more information. - - If authentication is successful, InfluxDB creates a new session for the user - and then returns the session cookie in the `Set-Cookie` response header. - - InfluxDB stores user sessions in memory only. - They expire within ten minutes and during restarts of the InfluxDB instance. - - #### User sessions with authorizations - - - In InfluxDB Cloud, a user session inherits all the user's permissions for - the organization. - - In InfluxDB OSS, a user session inherits all the user's permissions for all - the organizations that the user belongs to. - - #### Related endpoints - - - [Signout](#tag/Signout) - operationId: PostSignin - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '204': - 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. - 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: Forbidden. The user account is disabled. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unsuccessful authentication. - security: - - BasicAuthentication: [] - summary: Create a user session. - tags: - - Security and access endpoints - - 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 a user session specified by a session cookie. - - Use this endpoint to expire a user session that was generated when the user - authenticated with the InfluxDB Developer Console (UI) or the `POST /api/v2/signin` endpoint. - - For example, the `POST /api/v2/signout` endpoint represents the third step - in the following three-step process - to authenticate a user, retrieve the `user` resource, and then expire the session: - - 1. Send a request with the user's [Basic authentication credentials](#section/Authentication/BasicAuthentication) - to the `POST /api/v2/signin` endpoint to create a user session and - generate a session cookie. - 2. Send a request to the `GET /api/v2/me` endpoint, passing the stored session cookie - from step 1 to retrieve user information. - 3. Send a request to the `POST /api/v2/signout` endpoint, passing the stored session - cookie to expire the session. - - _See the complete example in request samples._ - - InfluxDB stores user sessions in memory only. - If a user doesn't sign out, then the user session automatically expires within ten minutes or - during a restart of the InfluxDB instance. - - To learn more about cookies in HTTP requests, see - [Mozilla Developer Network (MDN) Web Docs, HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies). - - #### Related endpoints - - - [Signin](#tag/Signin) - operationId: PostSignout - parameters: - - $ref: '#/components/parameters/TraceSpan' - responses: - '204': - description: Success. The session is expired. - '401': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unauthorized. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: The session expiry is unsuccessful. - summary: Expire a user session - tags: - - Security and access endpoints - - Signout - x-codeSamples: - - label: 'cURL: sign in a user, verify the user session, and then end the session' - lang: Shell - source: | - # The following example shows how to use cURL and the InfluxDB API - # to do the following: - # 1. Sign in a user with a username and password. - # 2. Check that the user session exists for the user. - # 3. Sign out the user to expire the session. - # 4. Check that the session is no longer active. - - # 1. Send a request to `POST /api/v2/signin` to sign in the user. - # In your request, pass the following: - # - # - `--user` option with basic authentication credentials. - # - `-c` option with a file path where cURL will write cookies. - - curl --request POST \ - -c ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/signin" \ - --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}" - - # 2. To check that a user session exists for the user in step 1, - # send a request to `GET /api/v2/me`. - # In your request, pass the `-b` option with the session cookie file path from step 1. - - curl --request GET \ - -b ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/me" - - # InfluxDB responds with the `user` resource. - - # 3. Send a request to `POST /api/v2/signout` to expire the user session. - # In your request, pass the `-b` option with the session cookie file path from step 1. - - curl --request POST \ - -b ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/signout" - - # If the user session is successfully expired, InfluxDB responds with - an HTTP `204` status code. - - # 4. To check that the user session is expired, call `GET /api/v2/me` again, - # passing the `-b` option with the cookie file path. - - curl --request GET \ - -b ./cookie-file.tmp \ - "$INFLUX_URL/api/v2/me" - - # If the user session is expired, InfluxDB responds with an HTTP `401` status code. - /api/v2/sources: - get: - operationId: GetSources - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the organization. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Sources' - description: A list of sources - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all sources - tags: - - Sources - post: - operationId: PostSources - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Source to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Created Source - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a source - tags: - - Sources - /api/v2/sources/{sourceID}: - delete: - operationId: DeleteSourcesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: View not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a source - tags: - - Sources - get: - operationId: GetSourcesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: A source - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Source not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a source - tags: - - Sources - patch: - operationId: PatchSourcesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Source update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Source' - description: Created Source - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Source not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a Source - tags: - - Sources - /api/v2/sources/{sourceID}/buckets: - get: - operationId: GetSourcesIDBuckets - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - - description: The name of the organization. - in: query - name: org - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Buckets' - description: A source - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Source not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Get buckets in a source - tags: - - Sources - - Buckets - /api/v2/sources/{sourceID}/health: - get: - operationId: GetSourcesIDHealth - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The source ID. - in: path - name: sourceID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The source is healthy - '503': - content: - application/json: - schema: - $ref: '#/components/schemas/HealthCheck' - description: The source is not healthy - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Get the health of a source - tags: - - Sources - /api/v2/stacks: - get: - description: | - Lists installed InfluxDB stacks. - - To limit stacks in the response, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all installed stacks - for the organization. - - #### Related guides - - - [View InfluxDB stacks](/influxdb/latest/influxdb-templates/stacks/). - operationId: ListStacks - parameters: - - description: | - An organization ID. - Only returns stacks owned by the specified [organization](/influxdb/latest/reference/glossary/#organization). - - #### InfluxDB Cloud - - - Doesn't require this parameter; - InfluxDB only returns resources allowed by the API token. - in: query - name: orgID - required: true - schema: - type: string - - description: | - A stack name. - Finds stack `events` with this name and returns the stacks. - - Repeatable. - To filter for more than one stack name, - repeat this parameter with each name--for example: - - - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1` - examples: - findStackByName: - summary: Find stacks with the event name - value: project-stack-0 - in: query - name: name - schema: - type: string - - description: | - A stack ID. - Only returns the specified stack. - - Repeatable. - To filter for more than one stack ID, - repeat this parameter with each ID--for example: - - - `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000` - examples: - findStackByID: - summary: Find a stack with the ID - value: 09bd87cd33be3000 - in: query - name: stackID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - properties: - stacks: - items: - $ref: '#/components/schemas/Stack' - type: array - type: object - description: Success. The response body contains the list of stacks. - '400': - content: - application/json: - examples: - orgIdMissing: - summary: The orgID query parameter is missing - value: - code: invalid - message: 'organization id[""] is invalid: id must have a length of 16 bytes' - orgProvidedNotFound: - summary: The org or orgID passed doesn't own the token passed in the header - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List installed stacks - tags: - - Templates - post: - description: | - Creates or initializes a stack. - - Use this endpoint to _manually_ initialize a new stack with the following - optional information: - - - Stack name - - Stack description - - URLs for template manifest files - - To automatically create a stack when applying templates, - use the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate). - - #### Required permissions - - - `write` permission for the organization - - #### Related guides - - - [Initialize an InfluxDB stack](/influxdb/latest/influxdb-templates/stacks/init/). - - [Use InfluxDB templates](/influxdb/latest/influxdb-templates/use/#apply-templates-to-an-influxdb-instance). - operationId: CreateStack - requestBody: - content: - application/json: - schema: - properties: - description: - type: string - name: - type: string - orgID: - type: string - urls: - items: - type: string - type: array - title: PostStackRequest - type: object - description: The stack to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Success. Returns the newly created stack. - '401': - $ref: '#/components/responses/AuthorizationError' - '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: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a stack - tags: - - Templates - /api/v2/stacks/{stack_id}: - delete: - operationId: DeleteStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - - description: The identifier of the organization. - in: query - name: orgID - required: true - schema: - type: string - responses: - '204': - description: The stack and its associated resources were deleted. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a stack and associated resources - tags: - - Templates - get: - operationId: ReadStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a stack - tags: - - Templates - patch: - operationId: UpdateStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - additionalResources: - items: - properties: - kind: - type: string - resourceID: - type: string - templateMetaName: - type: string - required: - - kind - - resourceID - type: object - type: array - description: - nullable: true - type: string - name: - nullable: true - type: string - templateURLs: - items: - type: string - nullable: true - type: array - title: PatchStackRequest - type: object - description: The stack to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the updated stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a stack - tags: - - Templates - /api/v2/stacks/{stack_id}/uninstall: - post: - operationId: UninstallStack - parameters: - - description: The identifier of the stack. - in: path - name: stack_id - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Stack' - description: Returns the uninstalled stack. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Uninstall a stack - tags: - - Templates - /api/v2/tasks: - get: - description: | - Lists [tasks](/influxdb/latest/reference/glossary/#task). - - To limit which tasks are returned, pass query parameters in your request. - If no query parameters are passed, InfluxDB returns all tasks up to the default `limit`. - - #### Related guide - - - [Process data with InfluxDB tasks](/influxdb/latest/process-data/) - operationId: GetTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task name. - Only returns [tasks](/influxdb/latest/reference/glossary/#task) - that have the specified name. - Different tasks may have the same name. - in: query - name: name - schema: - type: string - - description: | - A task ID. - Only returns [tasks](/influxdb/latest/reference/glossary/#task) created after the specified task. - in: query - name: after - schema: - type: string - - description: | - A user ID. - Only returns [tasks](/influxdb/latest/reference/glossary/#task) - owned by the specified [user](/influxdb/latest/reference/glossary/#user). - in: query - name: user - schema: - type: string - - description: | - An organization name. - Only returns tasks owned by the specified [organization](/influxdb/latest/reference/glossary/#organization). - in: query - name: org - schema: - type: string - - description: | - An organization ID. - Only returns [tasks](/influxdb/latest/reference/glossary/#task) owned by the specified [organization](/influxdb/latest/reference/glossary/#organization). - in: query - name: orgID - schema: - type: string - - description: | - A task status. - Only returns [tasks](/influxdb/latest/reference/glossary/#task) that have the specified status. - in: query - name: status - schema: - enum: - - active - - inactive - type: string - - description: | - The maximum number of [tasks](/influxdb/latest/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: - default: 100 - maximum: 500 - minimum: 1 - type: integer - - description: | - A task type. - Specifies the level of detail for [tasks](/influxdb/latest/reference/glossary/#task) in the response. - Default is `system`. - 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 - schema: - default: '' - enum: - - basic - - system - type: string - responses: - '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: | - Success. - The response body contains the list of tasks. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List tasks - tags: - - Data I/O endpoints - - Tasks - x-codeSamples: - - label: 'cURL: all tasks, basic output' - lang: Shell - source: | - curl https://localhost:8086/api/v2/tasks/?limit=-1&type=basic \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Token INFLUX_API_TOKEN' - post: - description: | - Creates a [task](/influxdb/latest/reference/glossary/#task) and returns the task. - - Use this endpoint to create a scheduled task that runs a script. - - #### Related guides - - - [Get started with tasks](/influxdb/latest/process-data/get-started/) - - [Create a task](/influxdb/latest/process-data/manage-tasks/create-task/) - - [Common tasks](/influxdb/latest/process-data/common-tasks/) - - [Task configuration options](/influxdb/latest/process-data/task-options/) - operationId: PostTasks - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - schema: - $ref: '#/components/schemas/TaskCreateRequest' - description: | - In the request body, provide the task. - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains a `tasks` list with the task. - '400': - content: - application/json: - examples: - missingFluxError: - summary: The request body doesn't contain a Flux query - value: - code: invalid - message: 'failed to decode request: missing flux' - orgProvidedNotFound: - summary: The organization specified by org or orgID doesn't own the token passed in the header - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - #### InfluxDB OSS - - - Returns this error if an incorrect value is passed for `org` or `orgID`. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a task - tags: - - Data I/O endpoints - - Tasks - /api/v2/tasks/{taskID}: - delete: - description: | - Deletes the specified [task](/influxdb/latest/reference/glossary/#task) - and all associated records (task runs, logs, and labels). - Once the task is deleted, InfluxDB cancels all scheduled runs of the task. - - To disable a task instead of delete it, use - [`PATCH /api/v2/tasks/TASK_ID`](#operation/PatchTasksID) to set the task status - to `inactive`. - operationId: DeleteTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to delete. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The task and runs are deleted. Scheduled runs are canceled. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a task - tags: - - Tasks - get: - description: | - Retrieves the specified [task](/influxdb/latest/reference/glossary/#task). - operationId: GetTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to retrieve. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a task - tags: - - Data I/O endpoints - - Tasks - patch: - description: | - Updates the specified [task](/influxdb/latest/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. - - #### Related guides - - - [Update a task](/influxdb/latest/process-data/manage-tasks/update-task/) - - [Task configuration options](/influxdb/latest/process-data/task-options/) - operationId: PatchTasksID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task)to update. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - examples: - TaskWithFlux: - $ref: '#/components/examples/TaskWithFluxRequest' - schema: - $ref: '#/components/schemas/TaskUpdateRequest' - description: | - In the request body, provide the task properties to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Task' - description: Success. The response body contains the updated task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels: - get: - description: | - Lists all labels for a task. - - Use this endpoint to list labels applied to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. - operationId: GetTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the task to retrieve labels for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: Success. The response body contains a list of all labels for the task. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List labels for a task - tags: - - Tasks - post: - description: | - Adds a label to a [task](/influxdb/latest/reference/glossary/#task). - - Use this endpoint to add a label to a task. - Labels are a way to add metadata to InfluxDB resources. - You can use labels for grouping and filtering resources in the - InfluxDB UI, `influx` CLI, and InfluxDB API. - operationId: PostTasksIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to label. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: | - In the request body, provide an object that specifies the label. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: Success. The response body contains the label. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Add a label to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/labels/{labelID}: - delete: - description: | - Deletes a label from a [task](/influxdb/latest/reference/glossary/#task). - operationId: DeleteTasksIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to delete the label from. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A label ID. - Specifies the label to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Success. The label is deleted. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Delete a label from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/logs: - get: - description: | - Lists all log events for a [task](/influxdb/latest/reference/glossary/#task). - - When a task runs, InfluxDB creates a `run` record in the taskโ€™s history. - Logs associated with each run provide relevant log messages, timestamps, and the exit status of the `run` attempt. - - Use this endpoint to retrieve only the log events for a task, - without additional task metadata. - operationId: GetTasksIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](/influxdb/latest/reference/glossary/#task) to retrieve logs for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - taskFailure: - summary: Events for a failed task run - value: - events: - - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 - time: '2022-07-13T07:06:54.198167Z' - - message: Completed(failed) - runID: 09a946fc3167d000 - time: '2022-07-13T07:07:13.104037Z' - - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' - runID: 09a946fc3167d000 - time: '2022-07-13T08:24:37.115323Z' - taskSuccess: - summary: Events for 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)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - schema: - $ref: '#/components/schemas/Logs' - description: | - Success. - The response body contains an `events` list with logs for the task. - Each log event `message` contains detail about the event. - If a task run fails, InfluxDB logs an event with the reason for the failure. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List logs for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members: - get: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Lists all users that have the `member` role for the specified [task](/influxdb/latest/reference/glossary/#task). - operationId: GetTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to retrieve members for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: | - Success. The response body contains a list of `users` that have - the `member` role for a task. - - If the task has no members, the response contains an empty `users` array. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all task members - tags: - - Tasks - post: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Adds a specified user to members of the specified [task](/influxdb/latest/reference/glossary/#task) and then returns - the member. - operationId: PostTasksIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A [task](/influxdb/latest/reference/glossary/#task) ID. - Specifies the task for the member. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: | - Created. The task `member` role is assigned to the user. - The response body contains the resource member with - role and user detail. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a task - tags: - - Tasks - /api/v2/tasks/{taskID}/members/{userID}: - delete: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes a member from a [task](/influxdb/latest/reference/glossary/#task). - operationId: DeleteTasksIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: A task ID. Specifies the [task](/influxdb/latest/reference/glossary/#task) to remove the member from. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The member is removed. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners: - get: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Lists all users that have the `owner` role for the specified task. - operationId: GetTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the task to retrieve owners for. - in: path - name: taskID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: | - Success. - The response contains a list of `users` that have the `owner` role for the task. - - If the task has no owners, the response contains an empty `users` array. - '401': - $ref: '#/components/responses/AuthorizationError' - '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: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a task - tags: - - Tasks - post: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Adds a specified user to owners of the specified task and then returns the - owner. - - Use this endpoint to create a _resource owner_ for the task. - A _resource owner_ is a user with `role: owner` for a specific resource. - operationId: PostTasksIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) for the owner. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: | - In the request body, provide an object that specifies the user. - required: true - responses: - '201': - content: - application/json: - examples: - createdOwner: - summary: User has the owner role for the resource - value: - id: 0772396d1f411000 - links: - logs: /api/v2/users/0772396d1f411000/logs - self: /api/v2/users/0772396d1f411000 - name: USER_NAME - role: owner - status: active - schema: - $ref: '#/components/schemas/ResourceOwner' - description: | - Created. The task `owner` role is assigned to the user. - The response body contains the resource owner with - role and user detail. - '401': - $ref: '#/components/responses/AuthorizationError' - '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: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner for a task - tags: - - Tasks - /api/v2/tasks/{taskID}/owners/{userID}: - delete: - deprecated: true - description: | - **Deprecated**: Tasks don't use `owner` and `member` roles. - Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions. - - Removes an owner from a [task](/influxdb/latest/reference/glossary/#task). - operationId: DeleteTasksIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A user ID. Specifies the owner to remove from the [task](/influxdb/latest/reference/glossary/#task). - in: path - name: userID - required: true - schema: - type: string - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to remove the owner from. - in: path - name: taskID - required: true - schema: - type: string - responses: - '204': - description: Success. The owner is removed. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a task - tags: - - Tasks - /api/v2/tasks/{taskID}/runs: - get: - description: | - Lists runs for the specified [task](/influxdb/latest/process-data/). - - To limit which task runs are returned, pass query parameters in your request. - If you don't pass query parameters, InfluxDB returns all runs for the task - up to the default `limit`. - operationId: GetTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to - to list runs for. - in: path - name: taskID - required: true - schema: - type: string - - description: A task run ID. Only returns runs created after the specified run. - in: query - name: after - schema: - type: string - - description: | - Limits the number of task runs returned. Default is `100`. - in: query - name: limit - schema: - default: 100 - maximum: 500 - minimum: 1 - type: integer - - description: | - A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled after the specified time. - in: query - name: afterTime - schema: - format: date-time - type: string - - description: | - A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)). - Only returns runs scheduled before the specified time. - in: query - name: beforeTime - schema: - format: date-time - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Runs' - description: Success. The response body contains the list of task runs. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List runs for a task - tags: - - Tasks - post: - description: | - Schedules a task run to start immediately, ignoring scheduled runs. - - Use this endpoint to manually start a task run. - Scheduled runs will continue to run as scheduled. - This may result in concurrently running tasks. - - To _retry_ a previous run (and avoid creating a new run), - use the [`POST /api/v2/tasks/{taskID}/runs/{runID}/retry` endpoint](#operation/PostTasksIDRunsIDRetry). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. - operationId: PostTasksIDRuns - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to - to run. - in: path - name: taskID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/RunManually' - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Run' - description: Success. The run is scheduled to start. - '400': - content: - application/json: - examples: - inactiveTask: - summary: Can't run an inactive task - value: - code: invalid - message: 'failed to force run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: Bad request. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Start a task run, overriding the schedule - tags: - - Data I/O endpoints - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}: - delete: - description: | - Cancels a running [task](/influxdb/latest/reference/glossary/#task). - - Use this endpoint to cancel a running task. - - #### InfluxDB Cloud - - - Doesn't support this operation. - operationId: DeleteTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) to - to cancel. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A task run ID. - Specifies the task run to cancel. - in: path - name: runID - required: true - schema: - type: string - responses: - '204': - description: | - Success. The `DELETE` is accepted and the run will be cancelled. - - #### InfluxDB Cloud - - - Doesn't support this operation. - - Doesn't return this status. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '405': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Method not allowed. - - #### InfluxDB Cloud - - - Always returns this error; doesn't support cancelling tasks. - - #### InfluxDB OSS - - - Doesn't return this error. - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Cancel a running task - tags: - - Tasks - get: - description: | - Retrieves the specified run for the specified [task](/influxdb/latest/reference/glossary/#task). - - Use this endpoint to retrieve detail and logs for a specific task run. - operationId: GetTasksIDRunsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) - that the task run belongs to. - in: path - name: taskID - required: true - schema: - type: string - - description: A task run ID. Specifies the run to retrieve. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - runSuccess: - summary: A successful task run. - value: - finishedAt: '2022-07-18T14:46:07.308254Z' - id: 09b070dadaa7d000 - links: - logs: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs - retry: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry - self: /api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000 - task: /api/v2/tasks/0996e56b2f378000 - log: - - message: 'Started task from script: "option task = {name: \"task1\", every: 30m} from(bucket: \"iot_center\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \"environment\") |> aggregateWindow(every: 1h, fn: mean)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - requestedAt: '2022-07-18T14:46:06Z' - scheduledFor: '2022-07-18T14:46:06Z' - startedAt: '2022-07-18T14:46:07.16222Z' - status: success - taskID: 0996e56b2f378000 - schema: - $ref: '#/components/schemas/Run' - description: Success. The response body contains the task run. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retrieve a run for a task. - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/logs: - get: - description: | - Lists all logs for a task run. - A log is a list of run events with `runID`, `time`, and `message` properties. - - Use this endpoint to help analyze [task](/influxdb/latest/reference/glossary/#task) performance and troubleshoot failed task runs. - operationId: GetTasksIDRunsIDLogs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: A task ID. Specifies the [task](/influxdb/latest/reference/glossary/#task) that the run belongs to. - in: path - name: taskID - required: true - schema: - type: string - - description: A run ID. Specifies the task run to list logs for. - in: path - name: runID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - examples: - taskFailure: - summary: Events for a failed task. - value: - events: - - message: 'Started task from script: "option task = {name: \"test task\", every: 3d, offset: 0s}"' - runID: 09a946fc3167d000 - time: '2022-07-13T07:06:54.198167Z' - - message: Completed(failed) - runID: 09a946fc3167d000 - time: '2022-07-13T07:07:13.104037Z' - - message: 'error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a "yield" or invoking streaming functions directly, without performing an assignment' - runID: 09a946fc3167d000 - time: '2022-07-13T08:24:37.115323Z' - taskSuccess: - summary: Events for 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)"' - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.101231Z' - - message: Completed(success) - runID: 09b070dadaa7d000 - time: '2022-07-18T14:46:07.242859Z' - schema: - $ref: '#/components/schemas/Logs' - description: | - 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. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: List logs for a run - tags: - - Tasks - /api/v2/tasks/{taskID}/runs/{runID}/retry: - post: - description: | - Queues a [task](/influxdb/latest/reference/glossary/#task) run to - retry and then returns the scheduled run. - - To manually start a _new_ task run, use the - [`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns). - - #### Limitations - - - Queuing a task run requires that the task's `status` property be set to `active`. - operationId: PostTasksIDRunsIDRetry - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A task ID. - Specifies the [task](/influxdb/latest/reference/glossary/#task) that the task run belongs to. - in: path - name: taskID - required: true - schema: - type: string - - description: | - A 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 - schema: - type: string - requestBody: - content: - application/json; charset=utf-8: - schema: - type: object - responses: - '200': - content: - application/json: - examples: - retryTaskRun: - summary: A task run scheduled to retry - value: - id: 09d60ffe08738000 - links: - logs: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs - retry: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry - self: /api/v2/tasks/09a776832f381000/runs/09d60ffe08738000 - task: /api/v2/tasks/09a776832f381000 - requestedAt: '2022-08-16T20:05:11.84145Z' - scheduledFor: '2022-08-15T00:00:00Z' - status: scheduled - taskID: 09a776832f381000 - schema: - $ref: '#/components/schemas/Run' - description: Success. The response body contains the queued run. - '400': - content: - application/json: - examples: - inactiveTask: - summary: Can't retry an inactive task - value: - code: invalid - message: 'failed to retry run: inactive task' - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - - InfluxDB may return this error for the following reasons: - - - The task has `status: inactive`. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Retry a task run - tags: - - Tasks - /api/v2/telegraf/plugins: - get: - operationId: GetTelegrafPlugins - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The type of plugin desired. - in: query - name: type - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPlugins' - description: A list of Telegraf plugins. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf plugins - tags: - - Telegraf Plugins - /api/v2/telegrafs: - get: - operationId: GetTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID the Telegraf config belongs to. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegrafs' - description: A list of Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all Telegraf configurations - tags: - - Telegrafs - post: - operationId: PostTelegrafs - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPluginRequest' - description: Telegraf configuration to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: Telegraf configuration created - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Create a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}: - delete: - operationId: DeleteTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a Telegraf configuration - tags: - - Telegrafs - get: - operationId: GetTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - - in: header - name: Accept - required: false - schema: - default: application/toml - enum: - - application/toml - - application/json - - application/octet-stream - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - application/octet-stream: - example: |- - [agent] - interval = "10s" - schema: - type: string - application/toml: - example: |- - [agent] - interval = "10s" - schema: - type: string - description: Telegraf configuration details - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Retrieve a Telegraf configuration - tags: - - Telegrafs - put: - operationId: PutTelegrafsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/TelegrafPluginRequest' - description: Telegraf configuration update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Telegraf' - description: An updated Telegraf configurations - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Update a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels: - get: - operationId: GetTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The label added to the Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/labels/{labelID}: - delete: - operationId: DeleteTelegrafsIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - - description: The label ID. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Telegraf config not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members: - get: - operationId: GetTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMembers' - description: A list of Telegraf config members - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all users with member privileges for a Telegraf config - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDMembers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceMember' - description: Member added to Telegraf config - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a member to a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/members/{userID}: - delete: - operationId: DeleteTelegrafsIDMembersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Member removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove a member from a Telegraf config - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners: - get: - operationId: GetTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwners' - description: Returns Telegraf configuration owners as a ResourceOwners list - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all owners of a Telegraf configuration - tags: - - Telegrafs - post: - operationId: PostTelegrafsIDOwners - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The Telegraf configuration ID. - in: path - name: telegrafID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as owner - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/ResourceOwner' - description: Telegraf configuration owner was added. Returns a ResourceOwner that references the User. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add an owner to a Telegraf configuration - tags: - - Telegrafs - /api/v2/telegrafs/{telegrafID}/owners/{userID}: - delete: - operationId: DeleteTelegrafsIDOwnersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. - in: path - name: userID - required: true - schema: - type: string - - description: The Telegraf config ID. - in: path - name: telegrafID - required: true - schema: - type: string - responses: - '204': - description: Owner removed - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Remove an owner from a Telegraf config - tags: - - Telegrafs - /api/v2/templates/apply: - post: - description: | - Applies a template to - create or update a [stack](/influxdb/latest/influxdb-templates/stacks/) of InfluxDB - [resources](/influxdb/latest/reference/cli/influx/export/all/#resources). - The response contains the diff of changes and the stack ID. - - Use this endpoint to install an InfluxDB template to an organization. - Provide template URLs or template objects in your request. - To customize which template resources are installed, use the `actions` - parameter. - - By default, when you apply a template, InfluxDB installs the template to - create and update stack resources and then generates a diff of the changes. - If you pass `dryRun: true` in the request body, InfluxDB validates the - template and generates the resource diff, but doesnโ€™t make any - changes to your instance. - - #### Custom values for templates - - - Some templates may contain [environment references](/influxdb/latest/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata. - To provide custom values for environment references, pass the _`envRefs`_ - property in the request body. - For more information and examples, see how to - [define environment references](/influxdb/latest/influxdb-templates/use/#define-environment-references). - - - Some templates may contain queries that use - [secrets](/influxdb/latest/security/secrets/). - To provide custom secret values, pass the _`secrets`_ property - in the request body. - Don't expose secret values in templates. - For more information, see [how to pass secrets when installing a template](/influxdb/latest/influxdb-templates/use/#pass-secrets-when-installing-a-template). - - #### Required permissions - - - `write` permissions for resource types in the template. - - #### Rate limits (with InfluxDB Cloud) - - - Adjustable service quotas apply. - For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Use templates](/influxdb/latest/influxdb-templates/use/) - - [Stacks](/influxdb/latest/influxdb-templates/stacks/) - operationId: ApplyTemplate - requestBody: - content: - application/json: - examples: - skipKindAction: - summary: Skip all bucket and task resources in the provided templates - value: - actions: - - action: skipKind - properties: - kind: Bucket - - action: skipKind - properties: - kind: Task - orgID: INFLUX_ORG_ID - templates: - - contents: - - '[object Object]': null - skipResourceAction: - summary: Skip specific resources in the provided templates - value: - actions: - - action: skipResource - properties: - kind: Label - resourceTemplateName: foo-001 - - action: skipResource - properties: - kind: Bucket - resourceTemplateName: bar-020 - - action: skipResource - properties: - kind: Bucket - resourceTemplateName: baz-500 - orgID: INFLUX_ORG_ID - templates: - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Bucket - metadata: - name: baz-500 - templateObjectEnvRefs: - summary: envRefs for template objects - value: - envRefs: - docker-bucket: MY_DOCKER_BUCKET - docker-spec-1: MY_DOCKER_SPEC - linux-cpu-label: MY_CPU_LABEL - orgID: INFLUX_ORG_ID - templates: - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Label - metadata: - name: - envRef: - key: linux-cpu-label - spec: - color: '#326BBA' - name: inputs.cpu - - contents: - - apiVersion: influxdata.com/v2alpha1 - kind: Bucket - metadata: - name: - envRef: - key: docker-bucket - schema: - $ref: '#/components/schemas/TemplateApply' - application/x-jsonnet: - schema: - $ref: '#/components/schemas/TemplateApply' - text/yml: - schema: - $ref: '#/components/schemas/TemplateApply' - description: | - Parameters for applying templates. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: | - Success. - The template dry run succeeded. - The response body contains a resource diff of changes that the - template would have made if installed. - No resources were created or updated. - The diff and summary won't contain IDs for resources - that didn't exist at the time of the dry run. - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/TemplateSummary' - description: | - Success. - The template applied successfully. - The response body contains the stack ID, a diff, and a summary. - The diff compares the initial state to the state after the template installation. - The summary contains newly created resources. - '422': - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/TemplateSummary' - - properties: - code: - type: string - message: - type: string - required: - - message - - code - type: object - description: | - Unprocessable entity. - - - The error may indicate one of the following problems: - - - The template failed validation. - - You passed a parameter combination that InfluxDB doesn't support. - '500': - content: - application/json: - examples: - createExceedsQuota: - summary: 'InfluxDB Cloud: Creating resource would exceed quota.' - value: - code: internal error - message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\"" - schema: - $ref: '#/components/schemas/Error' - description: | - Internal server error. - - #### InfluxDB Cloud - - - Returns this error if creating one of the template - resources (bucket, dashboard, task, user) exceeds your planโ€™s - adjustable service quotas. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Apply or dry-run a template - tags: - - Templates - x-codeSamples: - - label: 'cURL: Dry run with a remote template' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF - { - "dryRun": true, - "orgID": "INFLUX_ORG_ID", - "remotes": [ - { - "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml" - } - ] - } - EOF - - label: 'cURL: Apply with secret values' - lang: Shell - source: | - curl "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF | jq . - { - "orgID": "INFLUX_ORG_ID", - "secrets": { - "SLACK_WEBHOOK": "YOUR_SECRET_WEBHOOK_URL" - }, - "remotes": [ - { - "url": "https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml" - } - ] - } - EOF - - label: 'cURL: Apply template objects with environment references' - lang: Shell - source: | - curl --request POST "http://localhost:8086/api/v2/templates/apply" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --data @- << EOF - { "orgID": "INFLUX_ORG_ID", - "envRefs": { - "linux-cpu-label": "MY_CPU_LABEL", - "docker-bucket": "MY_DOCKER_BUCKET", - "docker-spec-1": "MY_DOCKER_SPEC" - }, - "templates": [ - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Label", - "metadata": { - "name": { - "envRef": { - "key": "linux-cpu-label" - } - } - }, - "spec": { - "color": "#326BBA", - "name": "inputs.cpu" - } - }] - }, - "templates": [ - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Label", - "metadata": { - "name": { - "envRef": { - "key": "linux-cpu-label" - } - } - }, - "spec": { - "color": "#326BBA", - "name": "inputs.cpu" - } - }] - }, - { "contents": [{ - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Bucket", - "metadata": { - "name": { - "envRef": { - "key": "docker-bucket" - } - } - } - }] - } - ] - } - EOF - /api/v2/templates/export: - post: - operationId: ExportTemplate - requestBody: - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/TemplateExportByID' - - $ref: '#/components/schemas/TemplateExportByName' - description: Export resources as an InfluxDB template. - required: false - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Template' - application/x-yaml: - schema: - $ref: '#/components/schemas/Template' - description: The template was created successfully. Returns the newly created template. - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Export a new template - tags: - - Templates - /api/v2/users: - get: - description: | - Lists [users](/influxdb/latest/reference/glossary/#user). - Default limit is `20`. - - 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` | | - - *`USER_ID`* is the ID of the user that you want to retrieve. - - #### Related guides - - - [View users](/influxdb/latest/users/view-users/). - operationId: GetUsers - parameters: - - $ref: '#/components/parameters/TraceSpan' - - $ref: '#/components/parameters/Offset' - - $ref: '#/components/parameters/Limit' - - $ref: '#/components/parameters/After' - - description: | - A user name. - Only lists the specified [user](/influxdb/latest/reference/glossary/#user). - in: query - name: name - schema: - type: string - - description: | - A user ID. - Only lists the specified [user](/influxdb/latest/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`. - '401': - content: - application/json: - examples: - tokenNotAuthorized: - summary: API token doesn't have `write:users` permission - value: - code: unauthorized - message: write:users/09d8462ce0764000 is unauthorized - 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 - summary: List users - tags: - - Security and access endpoints - - Users - post: - description: | - Creates a [user](/influxdb/latest/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`. The `name` property is required. - 2. Extract the user ID (`id` property) 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 - - | 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' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/User' - description: The user to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: | - Success. - The response body contains the user. - '401': - content: - application/json: - examples: - tokenNotAuthorized: - summary: API token doesn't have `write:users` permission - value: - code: unauthorized - message: write:users/09d8462ce0764000 is unauthorized - 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 - summary: Create a user - tags: - - Users - x-codeSamples: - - label: 'cURL: create a user and set a password' - lang: Shell - source: | - # The following steps show how to create a user and then set - # the user's password: - # - # 1. Send a request to this endpoint to create a user--for example: - - USER=$(curl --request POST \ - "INFLUX_URL/api/v2/users/" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header 'Content-type: application/json' \ - --data-binary @- << EOF - { - "name": "USER_NAME", - "status": "active" - } - EOF - ) - - # 2. Extract the id property from the response in step 1--for example: - - USER_ID=`echo $USER | jq -r '.id'` - - # 3. To set the user's password, set the password property in a request - # to the /api/v2/users/USER_ID/password endpoint--for example: - - curl request POST "INFLUX_URL/api/v2/users/$USER_ID/password/" \ - --header "Authorization: Token INFLUX_API_TOKEN" \ - --header 'Content-type: application/json' \ - --data '{ "password": "USER_PASSWORD" }' - /api/v2/users/{userID}: - delete: - description: | - Deletes a [user](/influxdb/latest/reference/glossary/#user). - - #### Required permissions - - | Action | Permission required | - |:------------|:-----------------------------------------------| - | Delete a user | `write-users` or `write-user USER_ID` | - - *`USER_ID`* is the ID of the user that you want to delete. - - #### Related guides - - - [Manage users](/influxdb/latest/organizations/users/) - operationId: DeleteUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Specifies the [user](/influxdb/latest/reference/glossary/#user) to delete. - in: path - name: userID - required: true - schema: - type: string - responses: - '204': - description: Success. The user is deleted. - '400': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: | - Bad request. - The response body contains detail about the error. - '401': - $ref: '#/components/responses/AuthorizationError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Delete a user - tags: - - Users - get: - description: | - Retrieves a [user](/influxdb/latest/reference/glossary/#user). - - #### Related guides - - - [Manage users](/influxdb/latest/organizations/users/) - operationId: GetUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Retrieves the specified [user](/influxdb/latest/reference/glossary/#user). - in: path - name: userID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: Success. The response body contains the user. - default: - $ref: '#/components/responses/GeneralServerError' - description: Unexpected error - summary: Retrieve a user - tags: - - Security and access endpoints - - Users - patch: - description: | - Updates a [user](/influxdb/latest/reference/glossary/#user) and returns the user. - - #### Required permissions - - | Action | Permission required | - |:------------|:-----------------------------------------------| - | Update a user | `write-users` or `write-user USER_ID` | - - *`USER_ID`* is the ID of the user that you want to update. - - #### Related guides - - - [Manage users](/influxdb/latest/organizations/users/) - operationId: PatchUsersID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Specifies the [user](/influxdb/latest/reference/glossary/#user) to update. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/User' - description: In the request body, provide the user properties to update. - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/UserResponse' - description: | - Success. - The response body contains the user. - '400': - $ref: '#/components/responses/BadRequestError' - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '500': - $ref: '#/components/responses/InternalServerError' - default: - $ref: '#/components/responses/GeneralServerError' - summary: Update a user - tags: - - Users - /api/v2/users/{userID}/password: - post: - description: | - Updates a user password. - - #### InfluxDB Cloud - - - Doesn't allow you to manage user passwords through the API. - Use the InfluxDB Cloud user interface (UI) to update a password. - - #### Related guides - - - [InfluxDB Cloud - Change your password](/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 ID of the user to set the password for. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: The new password to set for the user. - required: true - responses: - '204': - description: Success. The password is updated. - '400': - 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: | - 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 - summary: Update a password - tags: - - Security and access endpoints - - Users - x-codeSamples: - - label: 'cURL: use HTTP POST 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' \ - --header "Authorization: Token INFLUX_TOKEN" \ - --data-binary @- << EOF - {"password": "NEW_USER_PASSWORD"} - EOF - put: - description: | - Updates a user password. - - Use this endpoint to let a user authenticate with - [Basic authentication credentials](#section/Authentication/BasicAuthentication) - and set a new password. - - #### InfluxDB Cloud - - - Doesn't allow you to manage user passwords through the API. - Use the InfluxDB Cloud user interface (UI) to update a password. - - #### Related guides - - - [InfluxDB Cloud - Change your password](/influxdb/cloud/account-management/change-password/) - - [InfluxDB OSS - Change your password](/influxdb/latest/users/change-password/) - operationId: PutUsersIDPassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the user to set the password for. - in: path - name: userID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/PasswordResetBody' - description: The new password to set for the user. - required: true - responses: - '204': - description: Success. The password is updated. - '400': - 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: | - 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 -c ./cookie-file.tmp --request POST \ - "http://localhost:8086/api/v2/signin" \ - --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}" - - curl -b ./cookie-file.tmp --request PUT \ - "http://localhost:8086/api/v2/users/USER_ID/password" \ - --header 'Content-type: application/json' \ - --data-binary @- << EOF - {"password": "NEW_USER_PASSWORD"} - EOF - /api/v2/variables: - get: - operationId: GetVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The name of the organization. - in: query - name: org - schema: - type: string - - description: The organization ID. - in: query - name: orgID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variables' - description: A list of variables for an organization - '400': - $ref: '#/components/responses/GeneralServerError' - description: Invalid request - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: List all variables - tags: - - Variables - post: - operationId: PostVariables - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to create - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable created - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Create a variable - tags: - - Variables - /api/v2/variables/{variableID}: - delete: - operationId: DeleteVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '204': - description: Variable deleted - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Delete a variable - tags: - - Variables - get: - operationId: GetVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable found - '404': - $ref: '#/components/responses/GeneralServerError' - description: Variable not found - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Retrieve a variable - tags: - - Variables - patch: - operationId: PatchVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable update to apply - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Update a variable - tags: - - Variables - put: - operationId: PutVariablesID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable to replace - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Variable' - description: Variable updated - default: - $ref: '#/components/responses/GeneralServerError' - description: Internal server error - summary: Replace a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels: - get: - operationId: GetVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelsResponse' - description: A list of all labels for a variable - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: List all labels for a variable - tags: - - Variables - post: - operationId: PostVariablesIDLabels - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LabelMapping' - description: Label to add - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/LabelResponse' - description: The newly added label - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Add a label to a variable - tags: - - Variables - /api/v2/variables/{variableID}/labels/{labelID}: - delete: - operationId: DeleteVariablesIDLabelsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The variable ID. - in: path - name: variableID - required: true - schema: - type: string - - description: The label ID to delete. - in: path - name: labelID - required: true - schema: - type: string - responses: - '204': - description: Delete has been accepted - '404': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Variable not found - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Unexpected error - summary: Delete a label from a variable - tags: - - Variables - /api/v2/write: - post: - description: | - Writes data to a bucket. - - Use this endpoint to send data in [line protocol](/influxdb/latest/reference/syntax/line-protocol/) format to InfluxDB. - - #### InfluxDB Cloud - - - Does the following when you send a write request: - - 1. Validates the request and queues the write. - 2. If queued, responds with _success_ (HTTP `2xx` status code); _error_ otherwise. - 3. Handles the delete asynchronously and reaches eventual consistency. - - To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, - wait for a success response (HTTP `2xx` status code) before you send the next request. - - Because writes and deletes are asynchronous, your change might not yet be readable - when you receive the response. - - #### InfluxDB OSS - - - Validates the request and handles the write synchronously. - - If all points were written successfully, responds with HTTP `2xx` status code; - otherwise, returns the first line that failed. - - #### Required permissions - - - `write-buckets` or `write-bucket BUCKET_ID`. - - *`BUCKET_ID`* is the ID of the destination bucket. - - #### Rate limits (with InfluxDB Cloud) - - `write` rate limits apply. - For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/). - - #### Related guides - - - [Write data with the InfluxDB API](/influxdb/latest/write-data/developer-tools/api) - - [Optimize writes to InfluxDB](/influxdb/latest/write-data/best-practices/optimize-writes/) - - [Troubleshoot issues writing data](/influxdb/latest/write-data/troubleshoot/) - operationId: PostWrite - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - The compression applied to the line protocol in the request payload. - To send a GZIP payload, pass `Content-Encoding: gzip` header. - in: header - name: Content-Encoding - schema: - default: identity - description: | - Content coding. - Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - description: | - The format of the data in the request body. - 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. - enum: - - text/plain - - text/plain; charset=utf-8 - type: string - - description: | - The size of the entity-body, in bytes, sent to InfluxDB. - If the length is greater than the `max body` configuration option, - the server responds with status code `413`. - in: header - name: Content-Length - schema: - description: The length in decimal number of octets. - type: integer - - description: | - The content type that the client can understand. - Writes only return a response body if they fail--for example, - due to a formatting problem or quota limit. - - #### InfluxDB Cloud - - - Returns only `application/json` for format and limit errors. - - Returns only `text/html` for some quota limit errors. - - #### InfluxDB OSS - - - Returns only `application/json` for format and limit errors. - - #### Related guides - - - [Troubleshoot issues writing data](/influxdb/latest/write-data/troubleshoot/) - in: header - name: Accept - schema: - default: application/json - description: Error content type. - enum: - - application/json - type: string - - description: | - An organization name or ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Writes data to the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - If you pass both `orgID` and `org`, they must both be valid. - - Writes data to the bucket in the specified organization. - in: query - name: org - required: true - schema: - description: The organization name or ID. - type: string - - description: | - An organization ID. - - #### InfluxDB Cloud - - - Doesn't use the `org` parameter or `orgID` parameter. - - Writes data to the bucket in the organization - associated with the authorization (API token). - - #### InfluxDB OSS - - - Requires either the `org` parameter or the `orgID` parameter. - - If you pass both `orgID` and `org`, they must both be valid. - - Writes data to the bucket in the specified organization. - in: query - name: orgID - schema: - type: string - - description: | - A bucket name or ID. - InfluxDB writes all points in the batch to the specified bucket. - in: query - name: bucket - required: true - schema: - description: The bucket name or ID. - type: string - - description: The precision for unix timestamps in the line protocol batch. - in: query - name: precision - schema: - $ref: '#/components/schemas/WritePrecision' - requestBody: - content: - 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 - schema: - format: byte - type: string - description: | - In the request body, provide data in [line protocol format](/influxdb/latest/reference/syntax/line-protocol/). - - To send compressed data, do the following: - - 1. Use [GZIP](https://www.gzip.org/) to compress the line protocol data. - 2. In your request, send the compressed data and the - `Content-Encoding: gzip` header. - - #### Related guides - - - [Best practices for optimizing writes](/influxdb/latest/write-data/best-practices/optimize-writes/) - required: true - responses: - '204': - description: | - Success. - - #### InfluxDB Cloud - - - Validated and queued the request. - - Handles the write asynchronously - the write might not have completed yet. - - #### InfluxDB OSS - - - Successfully wrote all points in the batch. - - #### Related guides - - - [How to check for write errors](/influxdb/latest/write-data/troubleshoot/) - '400': - content: - application/json: - examples: - measurementSchemaFieldTypeConflict: - summary: (Cloud) field type conflict thrown by an explicit bucket schema - value: - code: invalid - message: 'partial write error (2 written): unable to parse ''air_sensor,service=S1,sensor=L1 temperature="90.5",humidity=70.0 1632850122'': schema: field type for field "temperature" not permitted by schema; got String but expected Float' - orgNotFound: - summary: (OSS) organization not found - value: - code: invalid - message: 'failed to decode request body: organization not found' - schema: - $ref: '#/components/schemas/LineProtocolError' - description: | - Bad request. The response body contains detail about the error. - - InfluxDB returns this error if the line protocol data in the request is malformed. - The response body contains the first malformed line in the data, and indicates what was expected. - For partial writes, the number of points written and the number of points rejected are also included. - For more information, check the `rejected_points` measurement in your `_monitoring` bucket. - - #### InfluxDB Cloud - - - Returns this error for bucket schema conflicts. - - #### InfluxDB OSS - - - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization. - '401': - $ref: '#/components/responses/AuthorizationError' - '404': - $ref: '#/components/responses/ResourceNotFoundError' - '413': - content: - application/json: - examples: - dataExceedsSizeLimitOSS: - summary: InfluxDB OSS response - value: | - {"code":"request too large","message":"unable to read data: points batch is too large"} - schema: - $ref: '#/components/schemas/LineProtocolLengthError' - text/html: - examples: - dataExceedsSizeLimit: - summary: InfluxDB Cloud response - value: | - - 413 Request Entity Too Large - -

413 Request Entity Too Large

-
-
nginx
- - - schema: - type: string - description: | - The request payload is too large. - InfluxDB rejected the batch and did not write any data. - - #### InfluxDB Cloud: - - - Returns this error if the payload exceeds the 50MB size limit. - - Returns `Content-Type: text/html` for this error. - - #### InfluxDB OSS: - - - Returns this error only if the [Go (golang) `ioutil.ReadAll()`](https://pkg.go.dev/io/ioutil#ReadAll) function raises an error. - - Returns `Content-Type: application/json` for this error. - '429': - description: | - Too many requests. - - #### InfluxDB Cloud - - - Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum [global limit](/influxdb/cloud/account-management/limits/#global-limits). - - For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again. - - For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header. - - Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. - Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets. - - #### InfluxDB OSS - - - Doesn't return this error. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - '500': - $ref: '#/components/responses/InternalServerError' - '503': - description: | - Service unavailable. - - - Returns this error if - the server is temporarily unavailable to accept writes. - - Returns a `Retry-After` header that describes when to try the write again. - headers: - Retry-After: - description: Non-negative decimal integer indicating seconds to wait before retrying the request. - schema: - format: int32 - type: integer - default: - $ref: '#/components/responses/GeneralServerError' - summary: Write data - tags: - - Data I/O endpoints - - Write + /api/v2/me: {} + /api/v2/me/password: {} + /metrics: {} + /api/v2/notificationEndpoints: {} + /api/v2/notificationEndpoints/{endpointID}: {} + /api/v2/notificationEndpoints/{endpointID}/labels: {} + /api/v2/notificationEndpoints/{endpointID}/labels/{labelID}: {} + /api/v2/notificationRules: {} + /api/v2/notificationRules/{ruleID}: {} + /api/v2/notificationRules/{ruleID}/labels: {} + /api/v2/notificationRules/{ruleID}/labels/{labelID}: {} + /api/v2/notificationRules/{ruleID}/query: {} + /api/v2/orgs: {} + /api/v2/orgs/{orgID}: {} + /api/v2/orgs/{orgID}/members: {} + /api/v2/orgs/{orgID}/members/{userID}: {} + /api/v2/orgs/{orgID}/owners: {} + /api/v2/orgs/{orgID}/owners/{userID}: {} + /api/v2/orgs/{orgID}/secrets: {} + /api/v2/orgs/{orgID}/secrets/{secretID}: {} + /api/v2/orgs/{orgID}/secrets/delete: {} + /ping: {} + /api/v2/query: {} + /api/v2/query/analyze: {} + /api/v2/query/ast: {} + /api/v2/query/suggestions: {} + /api/v2/query/suggestions/{name}: {} + /ready: {} + /api/v2/remotes: {} + /api/v2/remotes/{remoteID}: {} + /api/v2/replications: {} + /api/v2/replications/{replicationID}: {} + /api/v2/replications/{replicationID}/validate: {} + /api/v2/resources: {} + /api/v2/restore/bucket/{bucketID}: {} + /api/v2/restore/bucketMetadata: {} + /api/v2/restore/kv: {} + /api/v2/restore/shards/{shardID}: {} + /api/v2/restore/sql: {} + /api/v2/scrapers: {} + /api/v2/scrapers/{scraperTargetID}: {} + /api/v2/scrapers/{scraperTargetID}/labels: {} + /api/v2/scrapers/{scraperTargetID}/labels/{labelID}: {} + /api/v2/scrapers/{scraperTargetID}/members: {} + /api/v2/scrapers/{scraperTargetID}/members/{userID}: {} + /api/v2/scrapers/{scraperTargetID}/owners: {} + /api/v2/scrapers/{scraperTargetID}/owners/{userID}: {} + /api/v2/setup: {} + /api/v2/signin: {} + /api/v2/signout: {} + /api/v2/sources: {} + /api/v2/sources/{sourceID}: {} + /api/v2/sources/{sourceID}/buckets: {} + /api/v2/sources/{sourceID}/health: {} + /api/v2/stacks: {} + /api/v2/stacks/{stack_id}: {} + /api/v2/stacks/{stack_id}/uninstall: {} + /api/v2/tasks: {} + /api/v2/tasks/{taskID}: {} + /api/v2/tasks/{taskID}/labels: {} + /api/v2/tasks/{taskID}/labels/{labelID}: {} + /api/v2/tasks/{taskID}/logs: {} + /api/v2/tasks/{taskID}/members: {} + /api/v2/tasks/{taskID}/members/{userID}: {} + /api/v2/tasks/{taskID}/owners: {} + /api/v2/tasks/{taskID}/owners/{userID}: {} + /api/v2/tasks/{taskID}/runs: {} + /api/v2/tasks/{taskID}/runs/{runID}: {} + /api/v2/tasks/{taskID}/runs/{runID}/logs: {} + /api/v2/tasks/{taskID}/runs/{runID}/retry: {} + /api/v2/telegraf/plugins: {} + /api/v2/telegrafs: {} + /api/v2/telegrafs/{telegrafID}: {} + /api/v2/telegrafs/{telegrafID}/labels: {} + /api/v2/telegrafs/{telegrafID}/labels/{labelID}: {} + /api/v2/telegrafs/{telegrafID}/members: {} + /api/v2/telegrafs/{telegrafID}/members/{userID}: {} + /api/v2/telegrafs/{telegrafID}/owners: {} + /api/v2/telegrafs/{telegrafID}/owners/{userID}: {} + /api/v2/templates/apply: {} + /api/v2/templates/export: {} + /api/v2/users: {} + /api/v2/users/{userID}: {} + /api/v2/users/{userID}/password: {} + /api/v2/variables: {} + /api/v2/variables/{variableID}: {} + /api/v2/variables/{variableID}/labels: {} + /api/v2/variables/{variableID}/labels/{labelID}: {} + /api/v2/write: {} /legacy/authorizations: - get: - operationId: GetLegacyAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: | - A user ID. - Only returns legacy authorizations scoped to the specified [user](/influxdb/v2.6/reference/glossary/#user). - in: query - name: userID - schema: - type: string - - description: | - A user name. - Only returns legacy authorizations scoped to the specified [user](/influxdb/v2.6/reference/glossary/#user). - in: query - name: user - schema: - type: string - - description: | - An organization ID. - Only returns legacy authorizations that belong to the specified [organization](/influxdb/v2.6/reference/glossary/#organization). - in: query - name: orgID - schema: - type: string - - description: | - An organization name. - Only returns legacy authorizations that belong to the specified [organization](/influxdb/v2.6/reference/glossary/#organization). - in: query - name: org - schema: - type: string - - description: | - An authorization name token. - Only returns legacy authorizations with the specified name. - in: query - name: token - schema: - type: string - - description: | - An authorization ID. - Returns the specified legacy authorization. - in: query - name: authID - schema: - type: string - responses: - '200': - content: - application/json: - schema: - properties: - authorizations: - items: - $ref: '#/components/schemas/Authorization' - type: array - links: - $ref: '#/components/schemas/Links' - readOnly: true - type: object - description: Success. The response body contains a list of legacy `authorizations`. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: List all legacy authorizations - tags: - - Legacy Authorizations - post: - 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. - - *`USER_ID`* is the ID of the user that you want to scope the authorization to. - operationId: PostLegacyAuthorizations - parameters: - - $ref: '#/components/parameters/TraceSpan' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/LegacyAuthorizationPostRequest' - description: The legacy authorization to create. - required: true - responses: - '201': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: | - Created. The legacy authorization is created. - The response body contains the newly created legacy authorization. - '400': - $ref: '#/components/responses/ServerError' - description: Invalid request - '401': - content: - application/json: - examples: - unauthorizedWriteUsers: - summary: The token doesn't have the write:user permission - value: - code: unauthorized - message: write:users/08028e90933bf000 is unauthorized - schema: - properties: - code: - 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. - readOnly: true - type: string - description: | - Unauthorized. - The API token passed doesn't have the permissions necessary for the - request. - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Create a legacy authorization - tags: - - Legacy Authorizations servers: - url: /private /legacy/authorizations/{authID}: - delete: - operationId: DeleteLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to delete. - in: path - name: authID - required: true - schema: - type: string - responses: - '204': - description: Legacy authorization deleted - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Delete a legacy authorization - tags: - - Legacy Authorizations - get: - operationId: GetLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to get. - in: path - name: authID - required: true - schema: - type: string - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: Legacy authorization details - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Retrieve a legacy authorization - tags: - - Legacy Authorizations - patch: - operationId: PatchLegacyAuthorizationsID - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/AuthorizationUpdateRequest' - description: Legacy authorization to update - required: true - responses: - '200': - content: - application/json: - schema: - $ref: '#/components/schemas/Authorization' - description: The active or inactive legacy authorization - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Update a legacy authorization to be active or inactive - tags: - - Legacy Authorizations servers: - url: /private /legacy/authorizations/{authID}/password: - post: - operationId: PostLegacyAuthorizationsIDPassword - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the legacy authorization to update. - in: path - name: authID - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - properties: - password: - type: string - required: - - password - description: New password - required: true - responses: - '204': - description: Legacy authorization password set - default: - $ref: '#/components/responses/ServerError' - description: Unexpected error - summary: Set a legacy authorization password - tags: - - Legacy Authorizations servers: - url: /private - /query: - get: - description: Queries InfluxDB using InfluxQL. - operationId: GetLegacyQuery - parameters: - - $ref: '#/components/parameters/TraceSpan' - - in: header - name: Accept - schema: - default: application/json - description: | - Media type that the client can understand. - - **Note**: With `application/csv`, query results include [**unix timestamps**](/influxdb/v2.6/reference/glossary/#unix-timestamp) instead of [RFC3339 timestamps](/influxdb/v2.6/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. - in: header - name: Accept-Encoding - schema: - default: identity - description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - - in: header - name: Content-Type - schema: - enum: - - application/json - type: string - - description: The InfluxDB 1.x username to authenticate the request. - in: query - name: u - schema: - type: string - - description: The InfluxDB 1.x password to authenticate the request. - in: query - name: p - schema: - type: string - - description: | - The database to query data from. - This is mapped to an InfluxDB [bucket](/influxdb/v2.6/reference/glossary/#bucket). - For more information, see [Database and retention policy mapping](/influxdb/v2.6/api/influxdb-1x/dbrp/). - in: query - name: db - required: true - schema: - type: string - - description: | - The retention policy to query data from. - This is mapped to an InfluxDB [bucket](/influxdb/v2.6/reference/glossary/#bucket). - For more information, see [Database and retention policy mapping](/influxdb/v2.6/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 (`;`). - in: query - name: q - required: true - schema: - type: string - - description: | - A unix timestamp precision. - Formats timestamps as [unix (epoch) timestamps](/influxdb/v2.6/reference/glossary/#unix-timestamp) the specified precision - instead of [RFC3339 timestamps](/influxdb/v2.6/reference/glossary/#rfc3339-timestamp) with nanosecond precision. - in: query - name: epoch - schema: - enum: - - ns - - u - - ยต - - ms - - s - - m - - h - type: string - responses: - '200': - content: - application/csv: - schema: - $ref: '#/components/schemas/InfluxqlCsvResponse' - application/json: - schema: - $ref: '#/components/schemas/InfluxqlJsonResponse' - application/x-msgpack: - schema: - format: binary - type: string - text/csv: - schema: - $ref: '#/components/schemas/InfluxqlCsvResponse' - description: Query results - headers: - Content-Encoding: - description: Lists encodings (usually compression algorithms) that have been applied to the response payload. - schema: - default: identity - description: | - The content coding: - - `gzip`: compressed data - - `identity`: unmodified, uncompressed data. - enum: - - gzip - - identity - type: string - Trace-Id: - description: The trace ID, if generated, of the request. - schema: - description: Trace ID of a request. - type: string - '429': - description: | - #### InfluxDB Cloud: - - returns this error if a **read** or **write** request exceeds your - plan's [adjustable service quotas](/influxdb/v2.6/account-management/limits/#adjustable-service-quotas) - or if a **delete** request exceeds the maximum - [global limit](/influxdb/v2.6/account-management/limits/#global-limits) - - returns `Retry-After` header that describes when to try the write again. - - #### InfluxDB OSS: - - doesn't return this error. - headers: - Retry-After: - description: A non-negative decimal integer indicating the seconds to delay after the response is received. - schema: - format: int32 - type: integer - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Error processing query - summary: Query with the 1.x compatibility API - tags: - - Legacy Query - /write: - post: - operationId: PostLegacyWrite - parameters: - - $ref: '#/components/parameters/TraceSpan' - - description: The InfluxDB 1.x username to authenticate the request. - in: query - name: u - schema: - type: string - - description: The InfluxDB 1.x password to authenticate the request. - in: query - name: p - schema: - type: string - - 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 - schema: - type: string - - description: Retention policy name. - in: query - name: rp - schema: - type: string - - description: Write precision. - in: query - name: precision - schema: - type: string - - 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. - enum: - - gzip - - identity - type: string - requestBody: - content: - text/plain: - schema: - type: string - description: Line protocol body - required: true - responses: - '204': - 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. - '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. - '403': - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: No token was sent and they are required. - '413': - content: - 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. - '429': - 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. - 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. - headers: - Retry-After: - description: A non-negative decimal integer indicating the seconds to delay after the response is received. - schema: - format: int32 - type: integer - default: - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - description: Internal server error - summary: Write time series data into InfluxDB in a V1-compatible format - tags: - - Legacy Write + /query: {} + /write: {} security: - TokenAuthentication: [] servers: @@ -20092,17 +7215,14 @@ tags: Write time series data to [buckets](/influxdb/latest/reference/glossary/#bucket). name: Write x-tagGroups: - - name: Overview + - name: Using the InfluxDB HTTP API tags: - Quick start - Authentication - Supported operations - Headers - - Common parameters - Pagination - Response codes - - name: '' - tags: - Data I/O endpoints - Security and access endpoints - System information endpoints diff --git a/api-docs/v2.6/swaggerV1Compat.yml b/api-docs/v2.6/swaggerV1Compat.yml index 741123163..869dd5af3 100644 --- a/api-docs/v2.6/swaggerV1Compat.yml +++ b/api-docs/v2.6/swaggerV1Compat.yml @@ -429,4 +429,3 @@ tags: x-traitTag: true - name: Query - name: Write -x-tagGroups: []