684 lines
26 KiB
YAML
684 lines
26 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered
|
|
version: ''
|
|
description: |
|
|
The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database.
|
|
|
|
The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others.
|
|
|
|
This documentation is generated from the
|
|
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml).
|
|
|
|
#### Related
|
|
|
|
[InfluxDB `/api/v2` API for InfluxDB 3 Clustered](/influxdb3/clustered/api/v2/)
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
contact:
|
|
name: InfluxData
|
|
url: https://www.influxdata.com
|
|
email: support@influxdata.com
|
|
servers:
|
|
- url: /
|
|
security:
|
|
- TokenAuthentication: []
|
|
- BasicAuthentication: []
|
|
- QuerystringAuthentication: []
|
|
tags:
|
|
- name: Authentication
|
|
description: |
|
|
The InfluxDB 1.x API requires authentication for all requests.
|
|
InfluxDB Cloud uses InfluxDB API tokens to authenticate requests.
|
|
|
|
|
|
For more information, see the following:
|
|
- [Token authentication](#section/Authentication/TokenAuthentication)
|
|
- [Basic authentication](#section/Authentication/BasicAuthentication)
|
|
- [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
|
|
|
<!-- ReDoc-Inject: <security-definitions> -->
|
|
x-traitTag: true
|
|
- name: Query
|
|
- name: Write
|
|
paths:
|
|
/write:
|
|
post:
|
|
operationId: PostWriteV1
|
|
tags:
|
|
- Write
|
|
summary: Write time series data into InfluxDB in a V1-compatible format
|
|
requestBody:
|
|
description: Line protocol body
|
|
required: true
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
parameters:
|
|
- $ref: '#/components/parameters/TraceSpan'
|
|
- $ref: '#/components/parameters/AuthUserV1'
|
|
- $ref: '#/components/parameters/AuthPassV1'
|
|
- in: query
|
|
name: db
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: |
|
|
The database to write to.
|
|
|
|
**Database targeting:** In InfluxDB Clustered, databases can be named using the `database_name/retention_policy_name` convention for InfluxQL compatibility. InfluxDB Clustered does not use DBRP mappings. The db and rp parameters are used to construct the target database name following this naming convention.
|
|
|
|
**Auto-creation behavior:** InfluxDB Clustered requires databases to be created before writing data. The v1 `/write` API does not automatically create databases. If the specified
|
|
database does not exist, the write request will fail.
|
|
|
|
Authentication: Requires a valid API token with _write_ permissions for the target database.
|
|
|
|
### Related
|
|
|
|
- [Write data to InfluxDB Clustered](/influxdb3/clustered/write-data/)
|
|
- [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/)
|
|
- [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/)
|
|
- [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention)
|
|
- [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/)
|
|
- in: query
|
|
name: rp
|
|
schema:
|
|
type: string
|
|
description: Retention policy name.
|
|
- in: query
|
|
name: precision
|
|
schema:
|
|
type: string
|
|
description: Write precision.
|
|
- in: header
|
|
name: Content-Encoding
|
|
description: When present, its value indicates to the database that compression is applied to the line protocol body.
|
|
schema:
|
|
type: string
|
|
description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity.
|
|
default: identity
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
responses:
|
|
'204':
|
|
description: Write data is correctly formatted and accepted for writing to the bucket.
|
|
'400':
|
|
description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LineProtocolError'
|
|
'401':
|
|
description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'403':
|
|
description: No token was sent and they are required.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
'413':
|
|
description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LineProtocolLengthError'
|
|
'429':
|
|
description: Token is temporarily over quota. The Retry-After header describes when to try the write again.
|
|
headers:
|
|
Retry-After:
|
|
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
'503':
|
|
description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again.
|
|
headers:
|
|
Retry-After:
|
|
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
default:
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
/query:
|
|
get:
|
|
operationId: GetQueryV1
|
|
tags:
|
|
- Query
|
|
summary: Query using the InfluxDB v1 HTTP API
|
|
parameters:
|
|
- $ref: '#/components/parameters/TraceSpan'
|
|
- $ref: '#/components/parameters/AuthUserV1'
|
|
- $ref: '#/components/parameters/AuthPassV1'
|
|
- in: header
|
|
name: Accept
|
|
schema:
|
|
type: string
|
|
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/csv
|
|
- text/csv
|
|
- application/x-msgpack
|
|
- in: header
|
|
name: Accept-Encoding
|
|
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
|
schema:
|
|
type: string
|
|
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
|
default: identity
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
- in: query
|
|
name: chunked
|
|
description: |
|
|
If true, the response is divided into chunks of size `chunk_size`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- in: query
|
|
name: chunk_size
|
|
description: |
|
|
The number of records that will go into a chunk.
|
|
This parameter is only used if `chunked=true`.
|
|
schema:
|
|
type: integer
|
|
default: 10000
|
|
- in: query
|
|
name: db
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: The database to query from.
|
|
- in: query
|
|
name: pretty
|
|
description: |
|
|
If true, the JSON response is formatted in a human-readable format.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- in: query
|
|
name: q
|
|
description: Defines the InfluxQL query to run.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: rp
|
|
schema:
|
|
type: string
|
|
description: Retention policy name.
|
|
- name: epoch
|
|
description: |
|
|
Formats timestamps as unix (epoch) timestamps with the specified precision
|
|
instead of RFC3339 timestamps with nanosecond precision.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- h
|
|
- m
|
|
- s
|
|
- ms
|
|
- u
|
|
- µ
|
|
- ns
|
|
responses:
|
|
'200':
|
|
description: Query results
|
|
headers:
|
|
Content-Encoding:
|
|
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
|
schema:
|
|
type: string
|
|
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
|
default: identity
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
Trace-Id:
|
|
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
|
schema:
|
|
type: string
|
|
description: Specifies the request's trace ID.
|
|
content:
|
|
application/csv:
|
|
schema:
|
|
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
|
text/csv:
|
|
schema:
|
|
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InfluxQLResponse'
|
|
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:
|
|
type: string
|
|
format: binary
|
|
'429':
|
|
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
|
|
headers:
|
|
Retry-After:
|
|
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
default:
|
|
description: Error processing query
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
post:
|
|
operationId: PostQueryV1
|
|
tags:
|
|
- Query
|
|
summary: Query using the InfluxDB v1 HTTP API
|
|
requestBody:
|
|
description: InfluxQL query to execute.
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
db:
|
|
type: string
|
|
description: Database to query.
|
|
rp:
|
|
description: |
|
|
The retention policy name for InfluxQL compatibility
|
|
|
|
Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Clustered, databases can be named using the
|
|
database_name/retention_policy_name convention for InfluxQL compatibility.
|
|
|
|
When a request specifies both `db` and `rp`, InfluxDB Clustered combines them as `db/rp` to target the database--for example:
|
|
|
|
- If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen`
|
|
- If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb`
|
|
|
|
Unlike InfluxDB v1 and Cloud Serverless, InfluxDB Clustered does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API
|
|
compatibility and database naming conventions.
|
|
|
|
Note: The retention policy name does not control data retention in InfluxDB Clustered. Data retention is determined by the database's _retention period_ setting.
|
|
|
|
### Related
|
|
|
|
- [Use the v1 query API and InfluxQL to query data in InfluxDB Clustered](/influxdb3/clustered/query-data/execute-queries/influxdb-v1-api/)
|
|
- [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/)
|
|
- [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/)
|
|
- [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention)
|
|
- [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/)
|
|
type: string
|
|
q:
|
|
description: |
|
|
Defines the InfluxQL query to run.
|
|
type: string
|
|
chunked:
|
|
description: |
|
|
If true, the response is divided into chunks of size `chunk_size`.
|
|
type: boolean
|
|
chunk_size:
|
|
description: |
|
|
The number of records that will go into a chunk.
|
|
This parameter is only used if `chunked=true`.
|
|
type: integer
|
|
default: 10000
|
|
epoch:
|
|
description: |
|
|
A unix timestamp precision.
|
|
type: string
|
|
enum:
|
|
- h
|
|
- m
|
|
- s
|
|
- ms
|
|
- u
|
|
- µ
|
|
- ns
|
|
parameters:
|
|
- $ref: '#/components/parameters/TraceSpan'
|
|
- $ref: '#/components/parameters/AuthUserV1'
|
|
- $ref: '#/components/parameters/AuthPassV1'
|
|
- in: header
|
|
name: Accept
|
|
schema:
|
|
type: string
|
|
description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps.
|
|
default: application/json
|
|
enum:
|
|
- application/json
|
|
- application/csv
|
|
- text/csv
|
|
- application/x-msgpack
|
|
- in: header
|
|
name: Accept-Encoding
|
|
description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand.
|
|
schema:
|
|
type: string
|
|
description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity.
|
|
default: identity
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
- in: header
|
|
name: Content-Type
|
|
schema:
|
|
type: string
|
|
enum:
|
|
- application/vnd.influxql
|
|
- in: query
|
|
name: db
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: Bucket to query.
|
|
- in: query
|
|
name: rp
|
|
schema:
|
|
type: string
|
|
description: Retention policy name.
|
|
- in: query
|
|
name: q
|
|
description: Defines the influxql query to run.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Query results
|
|
headers:
|
|
Content-Encoding:
|
|
description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body
|
|
schema:
|
|
type: string
|
|
description: Specifies that the response in the body is encoded with gzip or not encoded with identity.
|
|
default: identity
|
|
enum:
|
|
- gzip
|
|
- identity
|
|
Trace-Id:
|
|
description: The Trace-Id header reports the request's trace ID, if one was generated.
|
|
schema:
|
|
type: string
|
|
description: Specifies the request's trace ID.
|
|
content:
|
|
application/csv:
|
|
schema:
|
|
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
|
text/csv:
|
|
schema:
|
|
$ref: '#/components/schemas/InfluxQLCSVResponse'
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InfluxQLResponse'
|
|
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:
|
|
type: string
|
|
format: binary
|
|
'429':
|
|
description: Token is temporarily over quota. The Retry-After header describes when to try the read again.
|
|
headers:
|
|
Retry-After:
|
|
description: A non-negative decimal integer indicating the seconds to delay after the response is received.
|
|
schema:
|
|
type: integer
|
|
format: int32
|
|
default:
|
|
description: Error processing query
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
components:
|
|
parameters:
|
|
TraceSpan:
|
|
in: header
|
|
name: Zap-Trace-Span
|
|
description: OpenTracing span context
|
|
example:
|
|
trace_id: '1'
|
|
span_id: '1'
|
|
baggage:
|
|
key: value
|
|
required: false
|
|
schema:
|
|
type: string
|
|
AuthUserV1:
|
|
in: query
|
|
name: u
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Username.
|
|
AuthPassV1:
|
|
in: query
|
|
name: p
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: User token.
|
|
schemas:
|
|
InfluxQLResponse:
|
|
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
|
|
InfluxQLCSVResponse:
|
|
type: string
|
|
example: |
|
|
name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value
|
|
Error:
|
|
properties:
|
|
code:
|
|
description: Code is the machine-readable error code.
|
|
readOnly: true
|
|
type: string
|
|
enum:
|
|
- internal error
|
|
- not found
|
|
- conflict
|
|
- invalid
|
|
- unprocessable entity
|
|
- empty value
|
|
- unavailable
|
|
- forbidden
|
|
- too many requests
|
|
- unauthorized
|
|
- method not allowed
|
|
message:
|
|
readOnly: true
|
|
description: Message is a human-readable message.
|
|
type: string
|
|
required:
|
|
- code
|
|
- message
|
|
LineProtocolError:
|
|
properties:
|
|
code:
|
|
description: Code is the machine-readable error code.
|
|
readOnly: true
|
|
type: string
|
|
enum:
|
|
- internal error
|
|
- not found
|
|
- conflict
|
|
- invalid
|
|
- empty value
|
|
- unavailable
|
|
message:
|
|
readOnly: true
|
|
description: Message is a human-readable message.
|
|
type: string
|
|
op:
|
|
readOnly: true
|
|
description: Op describes the logical code operation during error. Useful for debugging.
|
|
type: string
|
|
err:
|
|
readOnly: true
|
|
description: Err is a stack of errors that occurred during processing of the request. Useful for debugging.
|
|
type: string
|
|
line:
|
|
readOnly: true
|
|
description: First line within sent body containing malformed data
|
|
type: integer
|
|
format: int32
|
|
required:
|
|
- code
|
|
- message
|
|
- op
|
|
- err
|
|
LineProtocolLengthError:
|
|
properties:
|
|
code:
|
|
description: Code is the machine-readable error code.
|
|
readOnly: true
|
|
type: string
|
|
enum:
|
|
- invalid
|
|
message:
|
|
readOnly: true
|
|
description: Message is a human-readable message.
|
|
type: string
|
|
maxLength:
|
|
readOnly: true
|
|
description: Max length in bytes for a body of line-protocol.
|
|
type: integer
|
|
format: int32
|
|
required:
|
|
- code
|
|
- message
|
|
- maxLength
|
|
securitySchemes:
|
|
TokenAuthentication:
|
|
type: apiKey
|
|
name: Authorization
|
|
in: header
|
|
description: |
|
|
Use the [Token authentication](#section/Authentication/TokenAuthentication)
|
|
scheme to authenticate to the InfluxDB API.
|
|
|
|
|
|
In your API requests, send an `Authorization` header.
|
|
For the header value, provide the word `Token` followed by a space and an InfluxDB API token.
|
|
The word `Token` is case-sensitive.
|
|
|
|
|
|
### Syntax
|
|
|
|
`Authorization: Token YOUR_INFLUX_TOKEN`
|
|
|
|
|
|
For examples and more information, see the following:
|
|
- [`/authorizations`](#tag/Authorizations) endpoint.
|
|
- [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication).
|
|
- [Manage API tokens](/influxdb/cloud/security/tokens/).
|
|
BasicAuthentication:
|
|
type: http
|
|
scheme: basic
|
|
description: |
|
|
Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication)
|
|
scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme):
|
|
|
|
|
|
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|
|
QuerystringAuthentication:
|
|
type: apiKey
|
|
in: query
|
|
name: u=&p=
|
|
description: |
|
|
Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication)
|
|
scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
|
|
|
|
|
|
For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).
|