The open source InfluxDB v2 HTTP API (self-hosted). Same /api/v2 surface as InfluxDB Cloud for writing, querying, and managing time series data, buckets, organizations, tasks, and authorizations.
openapi: 3.0.0
info:
title: InfluxDB OSS API Service
version: 2.0.0
description: |
The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'
servers:
- url: /api/v2
tags:
- name: Authorizations (API tokens)
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](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/#authentication)
- [Manage API tokens](https://docs.influxdata.com/influxdb/latest/security/tokens/)
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/latest/security/tokens/create-token/)
- name: Buckets
description: |
Store your data in InfluxDB [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket).
A bucket is a named location where time series data is stored. All buckets
have a [retention period](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/latest/organizations/buckets/)
- name: DBRPs
description: |
The InfluxDB 1.x data model includes [databases](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#database)
and [retention policies](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/latest/reference/api/influxdb-1x/dbrp/)
- name: Debug
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: Delete
description: |
Delete data from an InfluxDB bucket.
- name: Organizations
description: |
Create and manage your [organizations](https://docs.influxdata.com/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: Query
description: |
Retrieve data, analyze queries, and get query suggestions.
- name: Tasks
description: |
Process and analyze your data with [tasks](https://docs.influxdata.com/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](https://docs.influxdata.com/influxdb/latest/process-data/get-started/)
- [Common data processing tasks](https://docs.influxdata.com/influxdb/latest/process-data/common-tasks/)
- name: Templates
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](https://docs.influxdata.com/influxdb/latest/influxdb-templates/stacks/)
- [InfluxDB templates](https://docs.influxdata.com/influxdb/latest/influxdb-templates/)
- name: Users
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](https://docs.influxdata.com/influxdb/latest/influxdb/latest/users/)
- [Create a token scoped to a user](https://docs.influxdata.com/influxdb/latest/latest/security/tokens/create-token/#create-a-token-scoped-to-a-user)
- name: Write
description: |
Write time series data to [buckets](https://docs.influxdata.com/influxdb/latest/reference/glossary/#bucket).
- name: Authentication
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> -->
x-traitTag: true
- name: Quick start
x-traitTag: true
description: |
See the [**API Quick Start**](https://docs.influxdata.com/influxdb/latest/api-guide/api_intro/)
to get up and running authenticating with tokens, writing to buckets, and querying data.
[**InfluxDB API client libraries**](https://docs.influxdata.com/influxdb/latest/api-guide/client-libraries/)
are available for popular languages and ready to import into your application.
- name: Supported operations
x-traitTag: true
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: Headers
x-traitTag: true
description: |
InfluxDB `/api/v2` API endpoints use standard HTTP request and response headers.
The following table shows common headers used by many InfluxDB API endpoints.
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
the `POST /api/v2/write` endpoint accepts the `Content-Encoding` header to indicate the compression applied to line protocol in the request body.
| Header | Value type | Description |
|:------------------------ |:--------------------- |:-------------------------------------------|
| `Accept` | string | The content type that the client can understand. |
| `Authorization` | string | The authorization scheme and credential. |
| `Content-Length` | integer | The size of the entity-body, in bytes, sent to the database. |
| `Content-Type` | string | The format of the data in the request body. |
- name: Common parameters
x-traitTag: true
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](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). |
| `bucketID` | string | The bucket ID ([find your bucket](https://docs.influxdata.com/influxdb/latest/organizations/buckets/view-buckets/). |
| `org` | string | The organization name or ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). |
| `orgID` | 16-byte string | The organization ID ([find your organization](https://docs.influxdata.com/influxdb/latest/organizations/view-orgs/). |
- name: Pagination
x-traitTag: true
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: Response codes
x-traitTag: true
description: |
InfluxDB `/api/v2` API endpoints use standard HTTP status codes for success and failure responses.
The response body may include additional details.
For details about a specific operation's response,
see **Responses** and **Response Samples** for that operation.
API operations may return the following HTTP status codes:
| Code | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `204` | No content | For a `POST` request, `204` indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as `write`, might not have completed yet. |
| `400` | Bad request | 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](https://docs.influxdata.com/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. |
x-tagGroups:
- name: Overview
tags:
- Quick start
- Authentication
- Supported operations
- Headers
- Common parameters
- Pagination
- Response codes
- name: Popular endpoints
tags:
- Data I/O endpoints
- Security and access endpoints
- System information endpoints
- name: All endpoints
tags: []
paths:
/signin:
post:
operationId: PostSignin
summary: Create a user session.
description: |
Authenticates [Basic authentication credentials](#section/Authentication/BasicAuthentication)
for a [user](https://docs.influxdata.com/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)
tags:
- Security and access endpoints
- Signin
security:
- BasicAuthentication: []
parameters:
- $ref: '#/components/parameters/TraceSpan'
responses:
'204':
description: |
Success.
The user is authenticated.
The `Set-Cookie` response header contains the session cookie.
'401':
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.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden. The user account is disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Unsuccessful authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-codeSamples:
- lang: Shell
label: 'cURL: signin with --user option encoding'
source: |
curl --request POST http://localhost:8086/api/v2/signin \
--user "USERNAME:PASSWORD"
/signout:
post:
operationId: PostSignout
summary: Expire a user session
tags:
- Security and access endpoints
- Signout
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)
parameters:
- $ref: '#/components/parameters/TraceSpan'
responses:
'204':
description: Success. The session is expired.
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: The session expiry is unsuccessful.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-codeSamples:
- lang: Shell
label: 'cURL: sign in a user, verify the user session, and then end the session'
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.
/ping:
get:
operationId: GetPing
summary: Get the status of the instance
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](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/)
servers:
- url: ''
tags:
- Ping
- System information endpoints
responses:
'204':
description: |
Success.
Headers contain InfluxDB version information.
headers:
X-Influxdb-Build:
schema:
type: string
description: |
The type of InfluxDB build.
X-Influxdb-Version:
schema:
type: integer
description: |
The version of InfluxDB.
#### InfluxDB Cloud
- Doesn't return version.
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl --request GET "http://localhost:8086/ping"
head:
operationId: HeadPing
summary: Get the status of the instance
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](https://docs.influxdata.com/influxdb/latest/reference/cli/influx/ping/)
servers:
- url: ''
tags:
- Ping
responses:
'204':
description: |
Success.
Headers contain InfluxDB version information.
headers:
X-Influxdb-Build:
schema:
type: string
description: The type of InfluxDB build.
X-Influxdb-Version:
schema:
type: integer
description: |
The version of InfluxDB.
#### InfluxDB Cloud
- Doesn't return version.
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl --request HEAD "http://localhost:8086/ping"
/:
get:
operationId: GetRoutes
summary: List all top level routes
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/...`).
tags:
- Routes
- System information endpoints
parameters:
- $ref: '#/components/parameters/TraceSpan'
responses:
'200':
description: |
Success.
The response body contains key-value pairs with the resource name and
top-level route.
content:
application/json:
schema:
$ref: '#/components/schemas/Routes'
/dbrps:
get:
operationId: GetDBRPs
tags:
- DBRPs
summary: List database retention policy mappings
description: |
Lists database retention policy (DBRP) mappings.
#### Related guide
- [Database and retention policy mapping](https://docs.influxdata.com/influxdb/latest/reference/api/influxdb-1x/dbrp/)
parameters:
- $ref: '#/components/parameters/TraceSpan'
- in: query
name: orgID
description: |
An organization ID.
Only returns DBRP mappings for the specified organization.
schema:
type: string
- in: query
name: org
description: |
An organization name.
Only returns DBRP mappings for the specified organization.
schema:
type: string
- in: query
name: id
description: |
A DBPR mapping ID.
Only returns the specified DBRP mapping.
schema:
type: string
- in: query
name: bucketID
description: |
A bucket ID.
Only returns DBRP mappings that belong to the specified bucket.
schema:
type: string
- in: query
name: default
description: Specifies filtering on default
schema:
type: boolean
- in: query
name: db
description: |
A database.
Only returns DBRP mappings that belong to the 1.x database.
schema:
type: string
- in: query
name: rp
description: |
A [retention policy](https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#retention-policy-rp).
Specifies the 1.x retention policy to filter on.
schema:
type: string
responses:
'200':
description: Success. The response body contains a list of database retention policy mappings.
content:
application/json:
schema:
$ref: '#/components/schemas/DBRPs'
examples:
successResponse:
value:
content:
- id: 0a3cbb5dd526a000
database: example_database_1
retention_policy: autogen
default: true
orgID: bea7ea952287f70d
bucketID: 4d4d9d5b61dee751
- id: 0a3cbcde20e38000
database: example_database_2
retention_policy: example_retention_policy
default: false
orgID: bea7ea952287f70d
bucketID: 4d4d9d5b61dee751
'400':
description: Bad request. The request has one or more invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidRequest:
description: |
The query parameters contain invalid values.
value:
code: invalid
message: invalid ID
'401':
$ref: '#/components/responses/AuthorizationError'
'500':
$ref: '#/components/responses/InternalServerError'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: PostDBRP
tags:
- DBRPs
summary: Add a database retention policy mapping
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](https://docs.influxdata.com/influxdb/latest/reference/api/influxdb-1x/dbrp/)
parameters:
- $ref: '#/components/parameters/TraceSpan'
requestBody:
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](https://docs.influxdata.com/influxdb/latest/reference/glossary/#retention-policy-rp)
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DBRPCreate'
# --- truncated at 32 KB (636 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/influxdata/refs/heads/main/openapi/influxdata-oss-openapi-original.yml