-
Notifications
You must be signed in to change notification settings - Fork 295
/
Copy pathref.yml
14831 lines (14286 loc) · 484 KB
/
ref.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.0
info:
title: InfluxDB Cloud Serverless API Service
description: |
The InfluxDB v2 HTTP API lets you use `/api/v2` endpoints for managing retention policy mappings and writing data stored in an InfluxDB v3 instance.
This documentation is generated from the
[InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/ref/cloud.yml).
license:
name: MIT
url: https://opensource.org/licenses/MIT
summary: |
The InfluxDB v2 HTTP API for InfluxDB Cloud Serverless provides a programmatic interface for writing data stored in an InfluxDB Cloud Serverless bucket.
version: ''
servers:
- url: /
security:
- TokenAuthentication: []
tags:
- description: |
### Write data
InfluxDB Cloud Serverless provides the following HTTP API endpoints for writing data:
- **Recommended**: [`/api/v2/write` endpoint](#operation/PostWrite)
for new write workloads or for bringing existing InfluxDB v2 write workloads to v3.
- [`/write` endpoint](#operation/PostLegacyWrite) for bringing existing InfluxDB v1 write workloads to v3.
Both endpoints accept the same line protocol format and process data in the same way.
### Query data
InfluxDB Cloud Serverless provides the following protocols for executing a query:
- **Recommended**: _Flight+gRPC_ request that contains an SQL or InfluxQL query. See how to [get started querying InfluxDB using Flight and SQL](/influxdb/cloud-serverless/get-started/query/).
- HTTP API [`/query` request](/influxdb/cloud-serverless/api/#operation/GetLegacyQuery) that contains an InfluxQL query.
Use this protocol when bringing existing InfluxDB v1 query workloads to v3.
### InfluxDB v2 compatibility
The HTTP API [`/api/v2/write` endpoint](#operation/PostWrite) works with the [`Token` authentication scheme](#section/Authentication/TokenAuthentication) and existing InfluxDB 2.x tools and code for [writing data](/influxdb/cloud-serverless/write-data/).
See how to [use the InfluxDB v2 HTTP API with InfluxDB Cloud Serverless](/influxdb/cloud-serverless/guides/api-compatibility/v2/).
### InfluxDB v1 compatibility
The HTTP API [`/write` endpoint](#operation/PostLegacyWrite) and [`/query` endpoint](#operation/GetLegacyQuery) work with InfluxDB 1.x username/password [authentication schemes](#section/Authentication/) and existing InfluxDB 1.x tools and code.
See how to [use the InfluxDB v1 HTTP API with InfluxDB Cloud Serverless](/influxdb/cloud-serverless/guides/api-compatibility/v1/).
name: API compatibility
x-traitTag: true
- 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 the following for managing your tokens:
- Create a generic user to create and manage tokens for writing data.
- Store your tokens in a secure password vault for future access.
### User sessions with authorizations
Optionally, when creating an authorization, you can scope it to a specific user.
If the user signs in with username and password, creating a _user session_,
the session carries the permissions granted by all the user's authorizations.
For more information, see [how to assign a token to a specific user](/influxdb/cloud-serverless/security/tokens/create-token/).
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
### Related endpoints
- [Signin](#tag/Signin)
- [Signout](#tag/Signout)
### Related guides
- [Authorize API requests](/influxdb/cloud-serverless/api-guide/api_intro/#authentication)
- [Manage API tokens](/influxdb/cloud-serverless/security/tokens/)
- [Assign a token to a specific user](/influxdb/cloud-serverless/security/tokens/create-token/)
name: Authorizations (API tokens)
- name: Bucket Schemas
- description: |
Store your data in InfluxDB [buckets](/influxdb/cloud-serverless/reference/glossary/#bucket).
A bucket is a named location where time series data is stored. All buckets
have a [retention period](/influxdb/cloud-serverless/reference/glossary/#retention-period),
a duration of time that each data point persists. InfluxDB drops all
points with timestamps older than the bucket’s retention period.
A bucket belongs to an organization.
### Related guides
- [Manage buckets](/influxdb/cloud-serverless/admin/buckets/)
name: Buckets
- name: Cells
- name: Checks
- description: |
To specify resources, some InfluxDB API endpoints require parameters or
properties in the request--for example,
writing to a `bucket` resource in an `org` (_organization_ resource).
### Common parameters
| Query parameter | Value type | Description |
|:------------------------ |:--------------------- |:-------------------------------------------|
| `bucket` | string | The bucket name or ID ([find your bucket](/influxdb/cloud-serverless/admin/buckets/view-buckets/). |
| `bucketID` | string | The bucket ID ([find your bucket](/influxdb/cloud-serverless/admin/buckets/view-buckets/). |
| `org` | string | The organization name or ID ([find your organization](/influxdb/cloud-serverless/organizations/view-orgs/). |
| `orgID` | 16-byte string | The organization ID ([find your organization](/influxdb/cloud-serverless/organizations/view-orgs/). |
name: Common parameters
x-traitTag: true
- name: Config
- name: Dashboards
- name: Data I/O endpoints
- description: |
The InfluxDB 1.x data model includes [databases](/influxdb/v1.8/concepts/glossary/#database)
and [retention policies](/influxdb/v1.8/concepts/glossary/#retention-policy-rp).
InfluxDB 2.x replaces databases and retention policies with buckets.
To support InfluxDB 1.x query and write patterns in InfluxDB 2.x,
databases and retention policies are mapped to buckets using the
database and retention policy (DBRP) mapping service.
The DBRP mapping service uses the database and retention policy
specified in 1.x compatibility API requests to route operations to a bucket.
### Related guides
- [Database and retention policy mapping](/influxdb/cloud-serverless/reference/api/influxdb-1x/dbrp/)
name: DBRPs
- 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. |
| `Content-Type` | string | The format of the data in the request body. |
name: Headers
x-traitTag: true
- description: |
Store, manage, and execute scripts in InfluxDB.
A script stores your custom Flux script and provides an invokable
endpoint that accepts runtime parameters.
In a script, you can specify custom runtime parameters
(`params`)--for example, `params.myparameter`.
Once you create a script, InfluxDB generates an
[`/api/v2/scripts/SCRIPT_ID/invoke` endpoint](#operation/PostScriptsIDInvoke)
for your organization.
You can run the script from API requests and tasks, defining parameter
values for each run.
When the script runs, InfluxDB replaces `params` references in the
script with the runtime parameter values you define.
Use the `/api/v2/scripts` endpoints to create and manage scripts.
See related guides to learn how to define parameters and execute scripts.
<!-- TSM-only -->
name: Invokable Scripts
- name: Labels
- name: Legacy Authorizations
- name: Limits
- name: NotificationEndpoints
- name: NotificationRules
- description: |
Manage your [organization](/influxdb/cloud-serverless/reference/glossary/#organization).
An organization is a workspace for a group of users. Organizations can be
used to separate different environments, projects, teams or users within
InfluxDB.
Use the `/api/v2/orgs` endpoints to view and manage organizations.
name: Organizations
- description: |
Some InfluxDB API [list operations](#tag/SupportedOperations) may support the following query parameters for paginating results:
| Query parameter | Value type | Description |
|:------------------------ |:--------------------- |:-------------------------------------------|
| `limit` | integer | The maximum number of records to return (after other parameters are applied). |
| `offset` | integer | The number of records to skip (before `limit`, after other parameters are applied). |
| `after` | string (resource ID) | Only returns resources created after the specified resource. |
### Limitations
- For specific endpoint parameters and examples, see the endpoint definition.
- If you specify an `offset` parameter value greater than the total number of records,
then InfluxDB returns an empty list in the response
(given `offset` skips the specified number of records).
The following example passes `offset=50` to skip the first 50 results,
but the user only has 10 buckets:
```sh
curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \
--header "Authorization: Token INFLUX_API_TOKEN"
```
The response contains the following:
```json
{
"links": {
"prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID",
"self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID"
},
"buckets": []
}
```
name: Pagination
x-traitTag: true
- name: Ping
- description: |
Query data stored in a bucket.
- HTTP clients can query the v1 [`/query` endpoint](/influxdb/cloud-serverless/api/#operation/GetLegacyQuery)
using **InfluxQL** and retrieve data in **CSV** or **JSON** format.
- _Flight + gRPC_ clients can query using **SQL** or **InfluxQL** and retrieve data in **Arrow** format.
#### Related guides
- [Get started querying InfluxDB](/influxdb/cloud-serverless/get-started/query/)
- [Execute queries](/influxdb/cloud-serverless/query-data/execute-queries/)
name: Query
- description: |
See the [**Get started**](/influxdb/cloud-serverless/get-started/) tutorial
to get up and running authenticating with tokens, writing to buckets, and querying data.
[**InfluxDB API client libraries and Flight clients**](/influxdb/cloud-serverless/reference/client-libraries/)
are available to integrate InfluxDB with your application.
name: Quick start
x-traitTag: true
- 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:
| Code | Status | Description |
|:-----------:|:------------------------ |:--------------------- |
| `200` | Success | |
| `201` | Created | Successfully created a resource. The response body may contain details, for example [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) response bodies contain details of partial write failures. |
| `204` | No content | The request succeeded. |
| `400` | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected.</li><li>The batch contains a point with the same series as other points, but one of the field values has a different data type.<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/cloud-serverless/security/tokens/)</li></ul> |
| `404` | Not found | Requested resource was not found. `message` in the response body provides details about the requested resource. |
| `405` | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a `POST` request to an endpoint that only allows `GET`. |
| `413` | Request entity too large | Request payload exceeds the size limit. |
| `422` | Unprocessable entity | Request data is invalid. `code` and `message` in the response body provide details about the problem. |
| `429` | Too many requests | API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again. |
| `500` | Internal server error | |
| `503` | Service unavailable | Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again. |
name: Response codes
x-traitTag: true
- name: Routes
- name: Rules
- name: Secrets
- name: Security and access endpoints
- name: Setup
- name: Signin
- name: Signout
- description: "The following table shows the most common operations that the InfluxDB `/api/v2` API supports.\nSome resources may support other operations that perform functions more specific to those resources.\nFor example, you can use the `PATCH /api/v2/scripts` endpoint to update properties of a script\nresource.\n\n| Operation | |\n|:----------|:-----------------------------------------------------------------------|\n| Write | Writes (`POST`) data to a bucket. |\n| Run | Executes (`POST`) a query or script and returns the result. |\n| List |\tRetrieves (`GET`) a list of zero or more resources. |\n| Create |\tCreates (`POST`) a new resource and returns the resource. |\n| Update |\tModifies (`PUT`) an existing resource to reflect data in your request. |\n| Delete |\tRemoves (`DELETE`) a specific resource. |\n"
name: Supported operations
x-traitTag: true
- name: System information endpoints
- description: |
Process and analyze your data with tasks
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 this object:
<SchemaDefinition schemaRef="#/components/schemas/Task" />
<!-- TSM-only -->
name: Tasks
- name: Telegraf Plugins
- name: Telegrafs
- description: |
Export and apply InfluxDB **templates**.
Manage **stacks** of templated InfluxDB resources.
InfluxDB templates are prepackaged configurations for resources.
Use InfluxDB templates to configure a fresh instance of InfluxDB,
back up your dashboard configuration, or share your configuration.
Use the `/api/v2/templates` endpoints to export templates and apply templates.
**InfluxDB stacks** are stateful InfluxDB templates that let you
add, update, and remove installed template resources over time, avoid duplicating
resources when applying the same or similar templates more than once, and
apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
Use the `/api/v2/stacks` endpoints to manage installed template resources.
<!-- TSM-only -->
name: Templates
- name: Usage
- description: |
Retrieve specific users.
InfluxDB Cloud lets you invite and collaborate with multiple users in your organization.
To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI);
you can't use the InfluxDB API to manage users in InfluxDB Cloud.
Once a user is added to your organization, you can use the
`GET /api/v2/users` and `GET /api/v2/users/USER_ID` API endpoints to
view specific members.
### User sessions with authorizations
Optionally, you can scope an authorization (and its API token) to a user.
If a user signs in with username and password, creating a _user session_,
the session carries the permissions granted by all the user's authorizations.
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
### Related guides
- [Manage users](/influxdb/cloud-serverless/organizations/users/)
name: Users
- name: Variables
- name: Views
- description: |
Write time series data to [buckets](/influxdb/cloud-serverless/reference/glossary/#bucket) using InfluxDB v1 or v2 endpoints.
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 Serverless doesn't expose [API token](/influxdb/cloud-serverless/reference/glossary/#token)
values in `GET /api/v2/authorizations` responses;
returns `token: redacted` for all authorizations.
#### Required permissions
To retrieve an authorization, the request must use an API token that has the
following permissions:
- `read-authorizations`
- `read-user` for the user that the authorization is scoped to
#### Related guides
- [View tokens](/influxdb/cloud-serverless/security/tokens/view-tokens/)
operationId: GetAuthorizations
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: |
A user ID.
Only returns authorizations scoped to the specified [user](/influxdb/cloud-serverless/reference/glossary/#user).
in: query
name: userID
schema:
type: string
- description: |
A user name.
Only returns authorizations scoped to the specified [user](/influxdb/cloud-serverless/reference/glossary/#user).
in: query
name: user
schema:
type: string
- description: An organization ID. Only returns authorizations that belong to the specified [organization](/influxdb/cloud-serverless/reference/glossary/#organization).
in: query
name: orgID
schema:
type: string
- description: |
An organization name.
Only returns authorizations that belong to the specified [organization](/influxdb/cloud-serverless/reference/glossary/#organization).
in: query
name: org
schema:
type: string
- description: |
An API [token](/influxdb/cloud-serverless/reference/glossary/#token) value.
Specifies an authorization by its `token` property value
and returns the authorization.
#### InfluxDB OSS
- Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,
applies other parameters, and then returns the result.
#### Limitations
- The parameter is non-repeatable. If you specify more than one,
only the first one is used. If a resource with the specified
property value doesn't exist, then the response body contains an empty list.
in: query
name: token
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Authorizations'
description: |
Success. The response body contains a list of authorizations.
If the response body is missing authorizations that you expect, check that the API
token used in the request has `read-user` permission for the users (`userID` property value)
in those authorizations.
#### InfluxDB OSS
- **Warning**: The response body contains authorizations with their
[API token](/influxdb/cloud-serverless/reference/glossary/#token) values in clear text.
- If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_,
InfluxDB OSS returns authorizations for all organizations in the instance.
'400':
$ref: '#/components/responses/GeneralServerError'
description: Invalid request
'401':
$ref: '#/components/responses/AuthorizationError'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/GeneralServerError'
description: Unexpected error
summary: List authorizations
tags:
- Authorizations (API tokens)
- Security and access endpoints
post:
description: |
Creates an authorization and returns the authorization with the
generated API [token](/influxdb/cloud-serverless/reference/glossary/#token).
Use this endpoint to create an authorization, which generates an API token
with permissions to `read` or `write` to a specific resource or `type` of resource.
The API token is the authorization's `token` property value.
To follow best practices for secure API token generation and retrieval,
InfluxDB enforces access restrictions on API tokens.
- InfluxDB allows access to the API token value immediately after the authorization is created.
- You can’t change access (read/write) permissions for an API token after it’s created.
- Tokens stop working when the user who created the token is deleted.
We recommend the following for managing your tokens:
- Create a generic user to create and manage tokens for writing data.
- Store your tokens in a secure password vault for future access.
#### Required permissions
- `write-authorizations`
- `write-user` for the user that the authorization is scoped to
#### Related guides
- [Create a token](/influxdb/cloud-serverless/security/tokens/create-token/)
operationId: PostAuthorizations
parameters:
- $ref: '#/components/parameters/TraceSpan'
requestBody:
content:
application/json:
examples:
AuthorizationPostRequest:
$ref: '#/components/examples/AuthorizationPostRequest'
AuthorizationWithResourcePostRequest:
$ref: '#/components/examples/AuthorizationWithResourcePostRequest'
AuthorizationWithUserPostRequest:
$ref: '#/components/examples/AuthorizationWithUserPostRequest'
schema:
$ref: '#/components/schemas/AuthorizationPostRequest'
description: The authorization to create.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Authorization'
description: |
Success. The authorization is created. The response body contains the
authorization.
'400':
$ref: '#/components/responses/GeneralServerError'
description: Invalid request
'401':
$ref: '#/components/responses/AuthorizationError'
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/GeneralServerError'
description: Unexpected error
summary: Create an authorization
tags:
- Authorizations (API tokens)
- Security and access endpoints
/api/v2/authorizations/{authID}:
delete:
description: |
Deletes an authorization.
Use the endpoint to delete an API token.
If you want to disable an API token instead of delete it,
[update the authorization's status to `inactive`](#operation/PatchAuthorizationsID).
operationId: DeleteAuthorizationsID
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: An authorization ID. Specifies the authorization to delete.
in: path
name: authID
required: true
schema:
type: string
responses:
'204':
description: Success. The authorization is deleted.
'400':
content:
application/json:
examples:
notFound:
summary: |
The specified resource ID is invalid.
value:
code: invalid
message: id must have a length of 16 bytes
schema:
$ref: '#/components/schemas/Error'
description: |
Bad request.
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
content:
application/json:
examples:
notFound:
summary: |
The requested authorization doesn't exist.
value:
code: not found
message: authorization not found
schema:
$ref: '#/components/schemas/Error'
description: |
Not found.
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/GeneralServerError'
description: Unexpected error
summary: Delete an authorization
tags:
- Authorizations (API tokens)
- Security and access endpoints
get:
description: |
Retrieves an authorization.
Use this endpoint to retrieve information about an API token, including
the token's permissions and the user that the token is scoped to.
#### InfluxDB OSS
- InfluxDB OSS returns
[API token](/influxdb/cloud-serverless/reference/glossary/#token) values in authorizations.
- If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_,
InfluxDB OSS returns authorizations for all organizations in the instance.
#### Related guides
- [View tokens](/influxdb/cloud-serverless/security/tokens/view-tokens/)
operationId: GetAuthorizationsID
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: An authorization ID. Specifies the authorization to retrieve.
in: path
name: authID
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Authorization'
description: Success. The response body contains the authorization.
'400':
content:
application/json:
examples:
notFound:
summary: |
The specified resource ID is invalid.
value:
code: invalid
message: id must have a length of 16 bytes
schema:
$ref: '#/components/schemas/Error'
description: |
Bad request.
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
content:
application/json:
examples:
notFound:
summary: |
The requested authorization doesn't exist.
value:
code: not found
message: authorization not found
schema:
$ref: '#/components/schemas/Error'
description: |
Not found.
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/GeneralServerError'
description: Unexpected error
summary: Retrieve an authorization
tags:
- Authorizations (API tokens)
- Security and access endpoints
patch:
description: |
Updates an authorization.
Use this endpoint to set an API token's status to be _active_ or _inactive_.
InfluxDB rejects requests that use inactive API tokens.
operationId: PatchAuthorizationsID
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: An authorization ID. Specifies the authorization to update.
in: path
name: authID
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizationUpdateRequest'
description: In the request body, provide the authorization properties to update.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Authorization'
description: Success. The response body contains the updated authorization.
default:
$ref: '#/components/responses/GeneralServerError'
description: Unexpected error
summary: Update an API token to be active or inactive
tags:
- Authorizations (API tokens)
- Security and access endpoints
/api/v2/buckets:
get:
description: |
Lists [buckets](/influxdb/cloud-serverless/reference/glossary/#bucket).
InfluxDB retrieves buckets owned by the
[organization](/influxdb/cloud-serverless/reference/glossary/#organization)
associated with the authorization
([API token](/influxdb/cloud-serverless/reference/glossary/#token)).
To limit which buckets are returned, pass query parameters in your request.
If no query parameters are passed, InfluxDB returns all buckets up to the
default `limit`.
#### InfluxDB OSS
- If you use an _[operator token](/influxdb/cloud-serverless/security/tokens/#operator-token)_
to authenticate your request, InfluxDB retrieves resources for _all
organizations_ in the instance.
To retrieve resources for only a specific organization, use the
`org` parameter or the `orgID` parameter to specify the organization.
#### Required permissions
| Action | Permission required |
|:--------------------------|:--------------------|
| Retrieve _user buckets_ | `read-buckets` |
| Retrieve [_system buckets_](/influxdb/cloud-serverless/reference/internals/system-buckets/) | `read-orgs` |
#### Related Guides
- [Manage buckets](/influxdb/cloud-serverless/admin/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 Serverless
- Doesn't use the `org` parameter or `orgID` parameter.
- Lists buckets for the organization associated with the authorization (API token).
in: query
name: org
schema:
type: string
- description: |
An organization ID.
#### InfluxDB Cloud Serverless
- Doesn't use the `org` parameter or `orgID` parameter.
- Lists buckets for the organization associated with the authorization (API token).
in: query
name: orgID
schema:
type: string
- description: |
A bucket name.
Only returns buckets with the specified name.
in: query
name: name
schema:
type: string
- description: |
A bucket ID.
Only returns the bucket with the specified ID.
in: query
name: id
schema:
type: string
responses:
'200':
content:
application/json:
examples:
successResponse:
value:
buckets:
- createdAt: '2022-03-15T17:22:33.72617939Z'
description: System bucket for monitoring logs
id: 77ca9dace40a9bfc
labels: []
links:
labels: /api/v2/buckets/77ca9dace40a9bfc/labels
members: /api/v2/buckets/77ca9dace40a9bfc/members
org: /api/v2/orgs/INFLUX_ORG_ID
owners: /api/v2/buckets/77ca9dace40a9bfc/owners
self: /api/v2/buckets/77ca9dace40a9bfc
write: /api/v2/write?org=ORG_ID&bucket=77ca9dace40a9bfc
name: _monitoring
orgID: INFLUX_ORG_ID
retentionRules:
- everySeconds: 604800
type: expire
schemaType: implicit
type: system
updatedAt: '2022-03-15T17:22:33.726179487Z'
links:
self: /api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID
schema:
$ref: '#/components/schemas/Buckets'
description: |
Success.
The response body contains a list of `buckets`.
'401':
$ref: '#/components/responses/AuthorizationError'
'500':
$ref: '#/components/responses/InternalServerError'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: List buckets
tags:
- Buckets
x-codeSamples:
- label: 'cURL: filter buckets by name'
lang: Shell
source: |
curl --request GET "http://localhost:8086/api/v2/buckets?name=_monitoring" \
--header "Authorization: Token INFLUX_TOKEN" \
--header "Accept: application/json" \
--header "Content-Type: application/json"
post:
description: |
Creates a [bucket](/influxdb/cloud-serverless/reference/glossary/#bucket)
and returns the bucket resource.
The default data
[retention period](/influxdb/cloud-serverless/reference/glossary/#retention-period)
is 30 days.
#### InfluxDB OSS
- A single InfluxDB OSS instance supports active writes or queries for
approximately 20 buckets across all organizations at a given time.
Reading or writing to more than 20 buckets at a time can adversely affect
performance.
#### Limitations
- InfluxDB Cloud Free Plan allows users to create up to two buckets.
Exceeding the bucket quota will result in an HTTP `403` status code.
For additional information regarding InfluxDB Cloud offerings, see
[InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/).
#### Related Guides
- [Create a bucket](/influxdb/cloud-serverless/admin/buckets/create-bucket/)
- [Create bucket CLI reference](/influxdb/cloud-serverless/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 Serverless
- 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.
#### Limitations
- Only one bucket can be deleted per request.