Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/api-docs/v2/ref.yml

20083 lines
655 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

openapi: 3.0.0
info:
title: InfluxDB OSS API Service
version: 2.x
description: |
The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. Access the InfluxDB API using `/api/v2/` and InfluxDB v1-compatible endpoints.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://github.com/influxdata/openapi/blob/influxdb-oss-v2.7.0/contracts/ref/oss.yml).
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance.
servers:
- url: /
security:
- TokenAuthentication: []
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)
<!-- ReDoc-Inject: <security-definitions> -->
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 creating a generic user to create and manage tokens for writing data.
### User sessions with authorizations
Optionally, when creating an authorization, you can scope it to a specific user.
If a user signs in with username and password, creating a _user session_,
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/latest/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/latest/api-guide/api_intro/#authentication)
- [Manage API tokens](/influxdb/latest/security/tokens/)
- [Assign a token to a specific user](/influxdb/latest/security/tokens/create-token/)
name: Authorizations (API tokens)
- name: Backup
- description: |
Store your data in InfluxDB [buckets](/influxdb/latest/reference/glossary/#bucket).
A bucket is a named location where time series data is stored. All buckets
have a [retention period](/influxdb/latest/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/latest/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/latest/organizations/buckets/view-buckets/). |
| `bucketID` | string | The bucket ID ([find your bucket](/influxdb/latest/organizations/buckets/view-buckets/). |
| `org` | string | The organization name or ID ([find your organization](/influxdb/latest/organizations/view-orgs/). |
| `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/latest/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/latest/reference/api/influxdb-1x/dbrp/)
name: DBRPs
- description: |
Generate profiling and trace reports.
Use routes under `/debug/pprof` to analyze the Go runtime of InfluxDB.
These endpoints generate [Go runtime profiles](https://pkg.go.dev/runtime/pprof)
and **trace** reports.
**Profiles** are collections of stack traces that show call sequences
leading to instances of a particular event, such as allocation.
For more information about **pprof profile** and **trace** reports,
see the following resources:
- [Google pprof tool](https://github.com/google/pprof)
- [Golang diagnostics](https://go.dev/doc/diagnostics)
name: Debug
- description: |
Delete data from an InfluxDB bucket.
name: Delete
- description: |
InfluxDB HTTP 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
- name: Health
- name: Labels
- name: Legacy Authorizations
- name: Legacy Query
- name: Legacy Write
- name: Metrics
- name: NotificationEndpoints
- name: NotificationRules
- description: |
Create and manage your [organizations](/influxdb/latest/reference/glossary/#organization).
An organization is a workspace for a group of users. Organizations can be
used to separate different environments, projects, teams or users within
InfluxDB.
Use the `/api/v2/orgs` endpoints to create, view, and manage organizations.
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/latest/api-guide/api_intro/)
to get up and running authenticating with tokens, writing to buckets, and querying data.
[**InfluxDB API client libraries**](/influxdb/latest/api-guide/client-libraries/)
are available for popular languages and ready to import into your application.
name: Quick start
x-traitTag: true
- name: Ready
- name: RemoteConnections
- name: Replications
- name: Resources
- description: |
InfluxDB HTTP 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:
| &nbsp;Code&nbsp; | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | Success. No content | InfluxDB doesn't return data for the request. |
| `400` | Bad request | May indicate one of the following: <ul><li>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.</li><li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
| `401` | Unauthorized | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/latest/security/tokens/)</li></ul> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
name: Response codes
x-traitTag: true
- name: Restore
- name: Routes
- name: Rules
- name: Scraper Targets
- name: Secrets
- name: Security and access endpoints
- name: Setup
- name: Signin
- name: Signout
- name: Sources
- 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/latest/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).
<span id="tasks-schemaref-task" />
### Properties
A `task` object contains information about an InfluxDB task resource.
The following table defines the properties that appear in a `task` object:
<SchemaDefinition schemaRef="#/components/schemas/Task" />
### Related guides
- [Get started with tasks](/influxdb/latest/process-data/get-started/)
- [Common data processing tasks](/influxdb/latest/process-data/common-tasks/)
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
everything from dashboards and Telegraf to notifications and alerts.
Use InfluxDB templates to quickly configure a fresh instance of InfluxDB,
back up your dashboard configuration, or share your configuration with the
InfluxData community.
Use the `/api/v2/templates` endpoints to export templates and apply templates.
**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/latest/influxdb-templates/stacks/)
- [InfluxDB templates](/influxdb/latest/influxdb-templates/)
name: Templates
- description: |
Manage users for your organization.
Users are those with access to InfluxDB.
To grant a user permission to access data, add them as a member of an
organization and provide them with an API token.
### User sessions with authorizations
Optionally, you can scope an authorization (and its API token) to a user.
If a user signs in with username and password, creating a _user session_,
the session carries the permissions granted by all the user's authorizations.
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
### Related guides
- [Manage users](/influxdb/latest/influxdb/latest/users/)
- [Create a token scoped to a user](/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)
name: Users
- name: Variables
- name: Views
- description: |
Write time series data to [buckets](/influxdb/latest/reference/glossary/#bucket).
name: Write
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/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:
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.7/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: |
<a href="/api/v2/query/suggestions?orgID=INFLUX_ORG_ID">Moved Permanently</a>
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-compressed 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: |
Retrieves a list of [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](/influxdb/latest/reference/glossary/#task) name.
Only returns tasks with the specified name.
Different tasks may have the same name.
in: query
name: name
schema:
type: string
- description: |
A [task](/influxdb/latest/reference/glossary/#task) ID.
Only returns tasks created after the specified task.
in: query
name: after
schema:
type: string
- description: |
A [user](/influxdb/latest/reference/glossary/#user) ID.
Only returns tasks owned by the specified user.
in: query
name: user
schema:
type: string
- description: |
An [organization](/influxdb/latest/reference/glossary/#organization) name.
Only returns tasks owned by the specified organization.
in: query
name: org
schema:
type: string
- description: |
An [organization](/influxdb/latest/reference/glossary/#organization) ID.
Only returns tasks owned by the specified organization.
in: query
name: orgID
schema:
type: string
- description: |
A [task](/influxdb/latest/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/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](/influxdb/latest/reference/glossary/#task) type (`basic` or `system`).
Default is `system`.
Specifies the level of detail for tasks in the response.
The default (`system`) response contains all the metadata properties for tasks.
To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).
in: query
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.
#### 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:
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 task.
'400':
content:
application/json:
examples:
missingFluxError:
summary: Task in request body is missing Flux query
value:
code: invalid
message: 'failed to decode request: missing flux'
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 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
x-codeSamples:
- label: 'cURL: create a task'
lang: Shell
source: |
curl http://localhost:8086/api/v2/tasks \
--header "Content-type: application/json" \
--header "Authorization: Token INFLUX_API_TOKEN" \
--data-binary @- << EOF
{
"orgID": "INFLUX_ORG_ID",
"description": "IoT Center 30d environment average.",
"flux": "option task = {name: \"iot-center-task-1\", every: 30m}\
from(bucket: \"iot_center\")\
|> range(start: -30d)\
|> filter(fn: (r) => r._measurement == \"environment\")\
|> aggregateWindow(every: 1h, fn: mean)"
}
EOF
/api/v2/tasks/{taskID}:
delete:
description: |
Deletes a task and associated records.
Use this endpoint to delete a task and all associated records (task runs, logs, and labels).
Once the task is deleted, InfluxDB cancels all scheduled runs of the task.
If you want to disable a task instead of delete it, [update the task status to `inactive`](#operation/PatchTasksID).
operationId: DeleteTasksID
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The ID of the 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 a [task](/influxdb/latest/reference/glossary/#task).
operationId: GetTasksID
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The ID of 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 and then cancels all scheduled runs of the task.
Use this endpoint to set, modify, and clear task properties (for example: `cron`, `name`, `flux`, `status`).
Once InfluxDB applies the update, it cancels all previously scheduled runs of the task.
To update a task, pass an object that contains the updated key-value pairs.
To activate or inactivate a task, set the `status` property.
_`"status": "inactive"`_ cancels scheduled runs and prevents manual runs of the task.
operationId: PatchTasksID
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The ID of the task to update.
in: path
name: taskID
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TaskUpdateRequest'
description: An object that contains updated task properties 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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/latest/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/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: 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/latest/reference/glossary/#task) run to
retry and returns the scheduled run.
To manually start a _new_ task run, use the
[`POST /api/v2/tasks/{taskID}/runs` endpoint](#operation/PostTasksIDRuns).
#### Limitations
- The task must be _active_ (`status: "active"`).
operationId: PostTasksIDRunsIDRetry
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: |
A [task](/influxdb/latest/reference/glossary/#task) ID.
Specifies the task to retry.
in: path
name: taskID
required: true
schema:
type: string
- description: |
A [task](/influxdb/latest/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:
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.
#### 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: |
<html>
<head><title>413 Request Entity Too Large</title></head>
<body>
<center><h1>413 Request Entity Too Large</h1></center>
<hr>
<center>nginx</center>
</body>
</html>
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:
get:
operationId: GetLegacyAuthorizations
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: |
A user ID.
Only returns legacy authorizations scoped to the specified [user](/influxdb/v2.7/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.7/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.7/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.7/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.7/reference/glossary/#unix-timestamp) instead of [RFC3339 timestamps](/influxdb/v2.7/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.7/reference/glossary/#bucket).
For more information, see [Database and retention policy mapping](/influxdb/v2.7/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.7/reference/glossary/#bucket).
For more information, see [Database and retention policy mapping](/influxdb/v2.7/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.7/reference/glossary/#unix-timestamp) the specified precision
instead of [RFC3339 timestamps](/influxdb/v2.7/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'
examples:
influxql-chunk_size_2:
value: |
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]}
{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]}
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.7/account-management/limits/#adjustable-service-quotas)
or if a **delete** request exceeds the maximum
[global limit](/influxdb/v2.7/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
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
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/latest/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/latest/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/v2.7/reference/glossary/#organization)
that the token is scoped to.
readOnly: true
type: string
orgID:
description: |
The organization ID.
Specifies the [organization](/influxdb/v2.7/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/v2.7/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/v2.7/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/v2.7/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
BucketMetadataManifest:
properties:
bucketID:
type: string
bucketName:
type: string
defaultRetentionPolicy:
type: string
description:
type: string
organizationID:
type: string
organizationName:
type: string
retentionPolicies:
$ref: '#/components/schemas/RetentionPolicyManifests'
required:
- organizationID
- organizationName
- bucketID
- bucketName
- defaultRetentionPolicy
- retentionPolicies
type: object
BucketMetadataManifests:
items:
$ref: '#/components/schemas/BucketMetadataManifest'
type: array
BucketShardMapping:
properties:
newId:
format: int64
type: integer
oldId:
format: int64
type: integer
required:
- oldId
- newId
type: object
BucketShardMappings:
items:
$ref: '#/components/schemas/BucketShardMapping'
type: array
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/latest/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
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
Config:
properties:
config:
type: object
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/latest/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/latest/reference/glossary/#organization) that owns the mapping.
type: string
orgID:
description: |
An organization ID.
Identifies the [organization](/influxdb/latest/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/latest/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/latest/reference/syntax/delete-predicate/).
example: tag1="value1" and (tag2="value2" and tag3!="value3")
type: string
start:
description: |
A timestamp ([RFC3339 date/time format](/influxdb/latest/reference/glossary/#rfc3339-timestamp)).
The earliest time to delete from.
format: date-time
type: string
stop:
description: |
A timestamp ([RFC3339 date/time format](/influxdb/latest/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/latest/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/latest/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/latest/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: |
The JSON response for an InfluxQL query.
A response contains the collection of results for a query.
`results` is an array of resultset objects.
If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object.
properties:
results:
description: |
A resultset object that contains the `statement_id` and the `series` array.
Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`.
items:
properties:
error:
type: string
partial:
description: |
True if the resultset is not complete--the response data is chunked; otherwise, false or omitted.
type: boolean
series:
description: |
An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement.
If a property is not present, it is assumed to be `null`.
items:
properties:
columns:
description: An array of column names
items:
type: string
type: array
name:
description: The name of the series
type: string
partial:
description: |
True if the series is not complete--the response data is chunked; otherwise, false or omitted.
type: boolean
tags:
additionalProperties:
type: string
description: |
A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`.
type: object
values:
description: |
An array of rows, where each row is an array of values.
items:
items: {}
type: array
type: array
type: object
type: array
statement_id:
description: |
An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results.
type: integer
type: object
oneOf:
- required:
- statement_id
- error
- required:
- statement_id
- series
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
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/latest/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
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
MetadataBackup:
properties:
buckets:
$ref: '#/components/schemas/BucketMetadataManifests'
kv:
format: binary
type: string
sql:
format: binary
type: string
required:
- kv
- sql
- buckets
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/latest/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 <limit> times every <limitEvery> seconds. If set, limitEvery cannot be empty.
type: integer
limitEvery:
description: Don't notify me more than <limit> times every <limitEvery> 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
org:
type: string
password:
type: string
retentionPeriodHrs:
deprecated: true
description: |
Retention period *in nanoseconds* for the new bucket. This key's name has been misleading since OSS 2.0 GA, please transition to use `retentionPeriodSeconds`
type: integer
retentionPeriodSeconds:
format: int64
type: integer
token:
description: |
Authentication token to set on the initial user. If not specified, the server will generate a token.
type: string
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
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/latest/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/latest/reference/internals/shards/#shard-group-duration).
#### Related guides
- InfluxDB [shards and shard groups](/influxdb/latest/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/latest/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 v2
- 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
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
RemoteConnection:
properties:
allowInsecureTLS:
default: false
type: boolean
description:
type: string
id:
type: string
name:
type: string
orgID:
type: string
remoteOrgID:
type: string
remoteURL:
format: uri
type: string
required:
- id
- name
- orgID
- remoteURL
- allowInsecureTLS
type: object
RemoteConnectionCreationRequest:
properties:
allowInsecureTLS:
default: false
type: boolean
description:
type: string
name:
type: string
orgID:
type: string
remoteAPIToken:
type: string
remoteOrgID:
type: string
remoteURL:
format: uri
type: string
required:
- name
- orgID
- remoteURL
- remoteAPIToken
- allowInsecureTLS
type: object
RemoteConnectionUpdateRequest:
properties:
allowInsecureTLS:
default: false
type: boolean
description:
type: string
name:
type: string
remoteAPIToken:
type: string
remoteOrgID:
type: string
remoteURL:
format: uri
type: string
type: object
RemoteConnections:
properties:
remotes:
items:
$ref: '#/components/schemas/RemoteConnection'
type: array
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
Replication:
properties:
currentQueueSizeBytes:
format: int64
type: integer
description:
type: string
dropNonRetryableData:
type: boolean
id:
type: string
latestErrorMessage:
type: string
latestResponseCode:
type: integer
localBucketID:
type: string
maxQueueSizeBytes:
format: int64
type: integer
name:
type: string
orgID:
type: string
remainingBytesToBeSynced:
format: int64
type: integer
remoteBucketID:
type: string
remoteBucketName:
type: string
remoteID:
type: string
required:
- id
- name
- remoteID
- orgID
- localBucketID
- maxQueueSizeBytes
type: object
ReplicationCreationRequest:
properties:
description:
type: string
dropNonRetryableData:
default: false
type: boolean
localBucketID:
type: string
maxAgeSeconds:
default: 604800
format: int64
minimum: 0
type: integer
maxQueueSizeBytes:
default: 67108860
format: int64
minimum: 33554430
type: integer
name:
type: string
orgID:
type: string
remoteBucketID:
type: string
remoteBucketName:
type: string
remoteID:
type: string
required:
- name
- orgID
- remoteID
- localBucketID
- maxQueueSizeBytes
- maxAgeSeconds
type: object
ReplicationUpdateRequest:
properties:
description:
type: string
dropNonRetryableData:
type: boolean
maxAgeSeconds:
format: int64
minimum: 0
type: integer
maxQueueSizeBytes:
format: int64
minimum: 33554430
type: integer
name:
type: string
remoteBucketID:
type: string
remoteBucketName:
type: string
remoteID:
type: string
type: object
Replications:
properties:
replications:
items:
$ref: '#/components/schemas/Replication'
type: array
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
RestoredBucketMappings:
properties:
id:
description: New ID of the restored bucket
type: string
name:
type: string
shardMappings:
$ref: '#/components/schemas/BucketShardMappings'
required:
- id
- name
- shardMappings
type: object
RetentionPolicyManifest:
properties:
duration:
format: int64
type: integer
name:
type: string
replicaN:
type: integer
shardGroupDuration:
format: int64
type: integer
shardGroups:
$ref: '#/components/schemas/ShardGroupManifests'
subscriptions:
$ref: '#/components/schemas/SubscriptionManifests'
required:
- name
- replicaN
- duration
- shardGroupDuration
- shardGroups
- subscriptions
type: object
RetentionPolicyManifests:
items:
$ref: '#/components/schemas/RetentionPolicyManifest'
type: array
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/latest/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/latest/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/latest/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/latest/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/latest/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
ScraperTargetRequest:
properties:
allowInsecure:
default: false
description: Skip TLS verification on endpoint.
type: boolean
bucketID:
description: The ID of the bucket to write to.
type: string
name:
description: The name of the scraper target.
type: string
orgID:
description: The organization ID.
type: string
type:
description: The type of the metrics to be parsed.
enum:
- prometheus
type: string
url:
description: The URL of the metrics endpoint.
example: http://localhost:9090/metrics
type: string
type: object
ScraperTargetResponse:
allOf:
- $ref: '#/components/schemas/ScraperTargetRequest'
- properties:
bucket:
description: The bucket name.
type: string
id:
readOnly: true
type: string
links:
example:
bucket: /api/v2/buckets/1
members: /api/v2/scrapers/1/members
organization: /api/v2/orgs/1
owners: /api/v2/scrapers/1/owners
self: /api/v2/scrapers/1
properties:
bucket:
$ref: '#/components/schemas/Link'
members:
$ref: '#/components/schemas/Link'
organization:
$ref: '#/components/schemas/Link'
owners:
$ref: '#/components/schemas/Link'
self:
$ref: '#/components/schemas/Link'
readOnly: true
type: object
org:
description: The name of the organization.
type: string
type: object
type: object
ScraperTargetResponses:
properties:
configurations:
items:
$ref: '#/components/schemas/ScraperTargetResponse'
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
ShardGroupManifest:
properties:
deletedAt:
format: date-time
type: string
endTime:
format: date-time
type: string
id:
format: int64
type: integer
shards:
$ref: '#/components/schemas/ShardManifests'
startTime:
format: date-time
type: string
truncatedAt:
format: date-time
type: string
required:
- id
- startTime
- endTime
- shards
type: object
ShardGroupManifests:
items:
$ref: '#/components/schemas/ShardGroupManifest'
type: array
ShardManifest:
properties:
id:
format: int64
type: integer
shardOwners:
$ref: '#/components/schemas/ShardOwners'
required:
- id
- shardOwners
type: object
ShardManifests:
items:
$ref: '#/components/schemas/ShardManifest'
type: array
ShardOwner:
properties:
nodeID:
description: The ID of the node that owns the shard.
format: int64
type: integer
required:
- nodeID
type: object
ShardOwners:
items:
$ref: '#/components/schemas/ShardOwner'
type: array
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
Source:
properties:
default:
type: boolean
defaultRP:
type: string
id:
type: string
insecureSkipVerify:
type: boolean
languages:
items:
enum:
- flux
- influxql
type: string
readOnly: true
type: array
links:
properties:
buckets:
type: string
health:
type: string
query:
type: string
self:
type: string
type: object
metaUrl:
format: uri
type: string
name:
type: string
orgID:
type: string
password:
type: string
sharedSecret:
type: string
telegraf:
type: string
token:
type: string
type:
enum:
- v1
- v2
- self
type: string
url:
format: uri
type: string
username:
type: string
type: object
Sources:
properties:
links:
properties:
self:
format: uri
type: string
type: object
sources:
items:
$ref: '#/components/schemas/Source'
type: array
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
SubscriptionManifest:
properties:
destinations:
items:
type: string
type: array
mode:
type: string
name:
type: string
required:
- name
- mode
- destinations
type: object
SubscriptionManifests:
items:
$ref: '#/components/schemas/SubscriptionManifest'
type: array
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/latest/reference/glossary/#rfc3339-timestamp)) at which the task runs. `every` also determines when the task first runs, depending on the specified time.
format: duration
type: string
flux:
description: The Flux script that the task executes.
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/latest/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/latest/reference/glossary/#organization) name.
Specifies the organization that owns the task.
type: string
orgID:
description: |
An [organization](/influxdb/latest/reference/glossary/#organization) ID.
Specifies the organization that owns the task.
type: string
ownerID:
description: |
A [user](/influxdb/latest/reference/glossary/#user) ID.
Specifies the owner of the task.
To find a user ID, you can use the
[`GET /api/v2/users` endpoint](#operation/GetUsers) to
list users.
type: string
status:
$ref: '#/components/schemas/TaskStatusType'
updatedAt:
format: date-time
readOnly: true
type: string
required:
- id
- name
- orgID
- flux
type: object
TaskCreateRequest:
properties:
description:
description: An optional description of the task.
type: string
flux:
description: The Flux script to run for this task.
type: string
org:
description: The name of the organization that owns this Task.
type: string
orgID:
description: The ID of the organization that owns this Task.
type: string
status:
$ref: '#/components/schemas/TaskStatusType'
required:
- flux
type: object
TaskStatusType:
description: |
`inactive` cancels scheduled runs and prevents manual runs of the task.
enum:
- active
- inactive
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: 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
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:
labels: /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/latest/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/latest/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/latest/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/latest/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/latest/influxdb-templates/stacks/)
- [View stacks](/influxdb/latest/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:
description: The user ID.
readOnly: true
type: string
name:
description: The user name.
type: string
status:
default: active
description: |
If `inactive`, the user is inactive.
Default is `active`.
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
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:
- **`USERNAME`**: InfluxDB username
- **`PASSWORD`**: InfluxDB [API token](/influxdb/latest/reference/glossary/#token)
- **`INFLUX_URL`**: your InfluxDB 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 "USERNAME":"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('USERNAME: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 URL
- *`INFLUX_API_TOKEN`*: your [InfluxDB API token](/influxdb/latest/reference/glossary/#token)
### Related endpoints
- [`/authorizations` endpoints](#tag/Authorizations-(API-tokens))
### Related guides
- [Authorize API requests](/influxdb/latest/api-guide/api_intro/#authentication)
- [Manage API tokens](/influxdb/latest/security/tokens/)
in: header
name: Authorization
type: apiKey
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)
- Backup
- Buckets
- Cells
- Checks
- Config
- Dashboards
- DBRPs
- Debug
- Delete
- Health
- Labels
- Legacy Authorizations
- Legacy Query
- Legacy Write
- Metrics
- NotificationEndpoints
- NotificationRules
- Organizations
- Ping
- Query
- Ready
- RemoteConnections
- Replications
- Resources
- Restore
- Routes
- Rules
- Scraper Targets
- Secrets
- Setup
- Signin
- Signout
- Sources
- Tasks
- Telegraf Plugins
- Telegrafs
- Templates
- Users
- Variables
- Views
- Write
Reference in New Issue View Git Blame Copy Permalink