--- title: Setup description: Configure an initial InfluxDB Cloud instance, including creating the initial user, organization, and bucket. url: https://docs.influxdata.com/influxdb/cloud/api/setup/ estimated_tokens: 3182 product: InfluxDB Cloud (TSM) version: cloud publisher: InfluxData canonical: https://docs.influxdata.com/influxdb/cloud/api/setup/ --- [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Configure an initial InfluxDB Cloud instance, including creating the initial user, organization, and bucket. GET`/api/v2/setup` ### Retrieve setup status Check if setup is allowed. Returns `true` if no default user, organization, or bucket have been created. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context Example request[Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/setup" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200Setup is allowed, true or false `allowed`boolean If `true`, the InfluxDB instance hasn’t had initial setup;`false` otherwise. POST`/api/v2/setup` ### Create an initial user, organization, and bucket Post an onboarding request to create an initial user, organization, and bucket. #### Parameters ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Source to create Content-Type:`application/json` `bucket`requiredstring `limit`object These are org limits similar to those configured in/by quartz. `bucket`requiredobject `maxBuckets`requiredinteger `maxRetentionDuration`requiredinteger Max bucket retention duration in nanoseconds. 0 is unlimited. `check`requiredobject `maxChecks`requiredinteger `dashboard`requiredobject `maxDashboards`requiredinteger `features`object `allowDelete`boolean allow delete predicate endpoint `ioxQuery`object `parquetFiles`requiredinteger `partitions`requiredinteger `notificationEndpoint`requiredobject `blockedNotificationEndpoints`string comma separated list of notification endpoints Example:`"http,pagerduty"` `notificationRule`requiredobject `blockedNotificationRules`string comma separated list of notification rules Example:`"http,pagerduty"` `maxNotifications`requiredinteger `orgID`string `rate`requiredobject `cardinality`requiredinteger Allowed organization total cardinality. 0 is unlimited. `concurrentDeleteRequests`integer Allowed organization concurrent outstanding delete requests. `concurrentReadRequests`requiredinteger Allowed concurrent queries. 0 is unlimited. `concurrentWriteRequests`requiredinteger Allowed concurrent writes. 0 is unlimited. `deleteRequestsPerSecond`integer Allowed organization delete request rate. `queryTime`requiredinteger Query Time in nanoseconds `readKBs`requiredinteger Query limit in kb/sec. 0 is unlimited. `writeKBs`requiredinteger Write limit in kb/sec. 0 is unlimited. `stack`object `enabled`requiredboolean `task`requiredobject `maxTasks`requiredinteger `timeout`object `queryUnconditionalTimeoutSeconds`requiredinteger `queryidleWriteTimeoutSeconds`requiredinteger `org`requiredstring `password`string `retentionPeriodHrs`integer `retentionPeriodSeconds`integer `username`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/setup" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucket": "BUCKET", "limit": { "bucket": { "maxBuckets": 0, "maxRetentionDuration": 0 }, "check": { "maxChecks": 0 }, "dashboard": { "maxDashboards": 0 }, "features": { "allowDelete": false }, "ioxQuery": { "parquetFiles": 0, "partitions": 0 }, "notificationEndpoint": { "blockedNotificationEndpoints": "http,pagerduty" }, "notificationRule": { "blockedNotificationRules": "http,pagerduty", "maxNotifications": 0 }, "orgID": "ORGID", "rate": { "cardinality": 0, "concurrentDeleteRequests": 0, "concurrentReadRequests": 0, "concurrentWriteRequests": 0, "deleteRequestsPerSecond": 0, "queryTime": 0, "readKBs": 0, "writeKBs": 0 }, "stack": { "enabled": false }, "task": { "maxTasks": 0 }, "timeout": { "queryUnconditionalTimeoutSeconds": 0, "queryidleWriteTimeoutSeconds": 0 } }, "org": "ORG", "password": "PASSWORD", "retentionPeriodHrs": 0, "retentionPeriodSeconds": 0, "username": "USERNAME" }' ``` #### Responses 201The created default user, bucket, and organization `auth`object `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/influxdb/cloud/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). `updatedAt`string \ `user`string The user name. Specifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the authorization. If the authorization is *scoped* to a user, the user; otherwise, the creator of the authorization. `userID`string The user ID. Specifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the authorization. If *scoped*, the user that the authorization is scoped to; otherwise, the creator of the authorization. `bucket`string `org`string `user`string defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging. POST`/api/v2/setup/user` ### Create a new user, organization, and bucket Post an onboarding request to create a new user, organization, and bucket. #### Request bodyrequired Source to create Content-Type:`application/json` `bucket`requiredstring `limit`object These are org limits similar to those configured in/by quartz. `bucket`requiredobject `maxBuckets`requiredinteger `maxRetentionDuration`requiredinteger Max bucket retention duration in nanoseconds. 0 is unlimited. `check`requiredobject `maxChecks`requiredinteger `dashboard`requiredobject `maxDashboards`requiredinteger `features`object `allowDelete`boolean allow delete predicate endpoint `ioxQuery`object `parquetFiles`requiredinteger `partitions`requiredinteger `notificationEndpoint`requiredobject `blockedNotificationEndpoints`string comma separated list of notification endpoints Example:`"http,pagerduty"` `notificationRule`requiredobject `blockedNotificationRules`string comma separated list of notification rules Example:`"http,pagerduty"` `maxNotifications`requiredinteger `orgID`string `rate`requiredobject `cardinality`requiredinteger Allowed organization total cardinality. 0 is unlimited. `concurrentDeleteRequests`integer Allowed organization concurrent outstanding delete requests. `concurrentReadRequests`requiredinteger Allowed concurrent queries. 0 is unlimited. `concurrentWriteRequests`requiredinteger Allowed concurrent writes. 0 is unlimited. `deleteRequestsPerSecond`integer Allowed organization delete request rate. `queryTime`requiredinteger Query Time in nanoseconds `readKBs`requiredinteger Query limit in kb/sec. 0 is unlimited. `writeKBs`requiredinteger Write limit in kb/sec. 0 is unlimited. `stack`object `enabled`requiredboolean `task`requiredobject `maxTasks`requiredinteger `timeout`object `queryUnconditionalTimeoutSeconds`requiredinteger `queryidleWriteTimeoutSeconds`requiredinteger `org`requiredstring `password`string `retentionPeriodHrs`integer `retentionPeriodSeconds`integer `username`requiredstring Example request[Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/setup/user" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "bucket": "BUCKET", "limit": { "bucket": { "maxBuckets": 0, "maxRetentionDuration": 0 }, "check": { "maxChecks": 0 }, "dashboard": { "maxDashboards": 0 }, "features": { "allowDelete": false }, "ioxQuery": { "parquetFiles": 0, "partitions": 0 }, "notificationEndpoint": { "blockedNotificationEndpoints": "http,pagerduty" }, "notificationRule": { "blockedNotificationRules": "http,pagerduty", "maxNotifications": 0 }, "orgID": "ORGID", "rate": { "cardinality": 0, "concurrentDeleteRequests": 0, "concurrentReadRequests": 0, "concurrentWriteRequests": 0, "deleteRequestsPerSecond": 0, "queryTime": 0, "readKBs": 0, "writeKBs": 0 }, "stack": { "enabled": false }, "task": { "maxTasks": 0 }, "timeout": { "queryUnconditionalTimeoutSeconds": 0, "queryidleWriteTimeoutSeconds": 0 } }, "org": "ORG", "password": "PASSWORD", "retentionPeriodHrs": 0, "retentionPeriodSeconds": 0, "username": "USERNAME" }' ``` #### Responses 201The created default user, bucket, and organization. `auth`object `createdAt`string \ `description`string A description of the token. `id`string The authorization ID. `links`object Example:`{"self":"/api/v2/authorizations/1","user":"/api/v2/users/12"}` `self`string \ URI of resource. `user`string \ URI of resource. `org`string The organization name. Specifies the [organization](/influxdb/cloud/reference/glossary/#organization)that the token is scoped to. `orgID`requiredstring The organization ID. Specifies the [organization](/influxdb/cloud/reference/glossary/#organization) that the authorization is scoped to. `permissions`requiredobject[] The list of permissions. An authorization must have at least one permission. `action`requiredstring Allowed:`read`, `write` `resource`requiredobject `status`string Status of the token. If `inactive`, InfluxDB rejects requests that use the token. Allowed:`active`, `inactive` Default:`active` `token`string The API token. The token value is unique to the authorization.[API tokens](/influxdb/cloud/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). `updatedAt`string \ `user`string The user name. Specifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the authorization. If the authorization is *scoped* to a user, the user; otherwise, the creator of the authorization. `userID`string The user ID. Specifies the [user](/influxdb/cloud/reference/glossary/#user) that owns the authorization. If *scoped*, the user that the authorization is scoped to; otherwise, the creator of the authorization. `bucket`string `org`string `user`string defaultNon 2XX error response from server. `code`requiredstring code is the machine-readable error code. Allowed:`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` `err`string Stack of errors that occurred during processing of the request. Useful for debugging. `message`string Human-readable message. `op`string Describes the logical code operation when the error occurred. Useful for debugging.