--- title: Database description: Create, list, and delete databases in InfluxDB 3 Enterprise. url: https://docs.influxdata.com/influxdb3/enterprise/api/database/ estimated_tokens: 7289 product: InfluxDB 3 Enterprise version: enterprise --- [Download InfluxDB 3 Enterprise API Spec](/openapi/influxdb3-enterprise-openapi.yml) Create, list, and delete databases in InfluxDB 3 Enterprise. GET `/api/v3/configure/database` ### List databases Retrieves a list of databases. #### Parameters ##### Query parameters `format` required string `show_deleted` boolean Include soft-deleted databases in the response. By default, only active databases are returned. Example request [Ask AI about this](#) ```sh curl --request GET \ "https://localhost:8181/api/v3/configure/database?format=FORMAT" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains the list of databases. `databases` string\[\] 400 Bad request. 401 Unauthorized access. `data` object `error` string 404 Database not found. POST `/api/v3/configure/database` ### Create a database Creates a new database in the system. #### Request body required Content-Type: `application/json` `db` required string The database name. Database names cannot contain underscores (\_). Names must start and end with alphanumeric characters and can contain hyphens (-) in the middle. `retention_period` string The retention period for the database. Specifies how long data should be retained. Use duration format (for example, “1d”, “1h”, “30m”, “7d”). Example: `"7d"` Example request [Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/configure/database" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "db": "DB", "retention_period": "7d" }' ``` #### Responses 200 Success. Database created. 400 Bad request. 401 Unauthorized access. `data` object `error` string 409 Database already exists. PUT `/api/v3/configure/database` ### Update a database Updates database configuration, such as retention period. #### Request body required Content-Type: `application/json` `retention_period` string The retention period for the database. Specifies how long data should be retained. Use duration format (for example, “1d”, “1h”, “30m”, “7d”). Example: `"7d"` Example request [Ask AI about this](#) ```sh curl --request PUT \ "https://localhost:8181/api/v3/configure/database" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "retention_period": "7d" }' ``` #### Responses 200 Success. The database has been updated. 400 Bad request. 401 Unauthorized access. `data` object `error` string 404 Database not found. DELETE `/api/v3/configure/database` ### Delete a database Soft deletes a database. The database is scheduled for deletion and unavailable for querying. Use the `hard_delete_at` parameter to schedule a hard deletion. Use the `data_only` parameter to delete data while preserving the database schema and resources. #### Parameters ##### Query parameters `db` required string The name of the database. `data_only` boolean Delete only data while preserving the database schema and all associated resources (tokens, triggers, last value caches, distinct value caches, processing engine configurations). When `false` (default), the entire database is deleted. `remove_tables` boolean Used with `data_only=true` to remove table resources (caches) while preserving database-level resources (tokens, triggers, processing engine configurations). Has no effect when `data_only=false`. `hard_delete_at` string Schedule the database for hard deletion at the specified time. If not provided, the database will be soft deleted. Use ISO 8601 date-time format (for example, “2025-12-31T23:59:59Z”). #### Deleting a database cannot be undone Deleting a database is a destructive action. Once a database is deleted, data stored in that database cannot be recovered. Also accepts special string values: - `now` — hard delete immediately - `never` — soft delete only (default behavior) - `default` — use the system default hard deletion time Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/database?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. Database deleted. 401 Unauthorized access. `data` object `error` string 404 Database not found. DELETE `/api/v3/configure/database/retention_period` ### Remove database retention period Removes the retention period from a database, setting it to infinite retention. #### Parameters ##### Query parameters `db` required string The name of the database. Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/configure/database/retention_period?db=DB" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Success. The database retention period has been removed. 401 Unauthorized access. `data` object `error` string 404 Database not found. POST `/api/v3/enterprise/configure/file_index` ### Create a file index Creates a file index for a database or table. A file index improves query performance by indexing data files based on specified columns, enabling the query engine to skip irrelevant files during query execution. This endpoint is only available in InfluxDB 3 Enterprise. #### Request body required Content-Type: `application/json` `columns` required string\[\] The columns to use for the file index. `db` required string The database name. `table` string The table name. If omitted, the file index applies to the database. Example request body ```json { "columns": [ "tag1", "tag2" ], "db": "mydb", "table": "mytable" } ``` Example request [Ask AI about this](#) ```sh curl --request POST \ "https://localhost:8181/api/v3/enterprise/configure/file_index" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"columns":["tag1","tag2"],"db":"mydb","table":"mytable"}' ``` #### Responses 200 Success. The file index has been created. 400 Bad request. 401 Unauthorized access. `data` object `error` string 404 Database or table not found. DELETE `/api/v3/enterprise/configure/file_index` ### Delete a file index Deletes a file index from a database or table. This endpoint is only available in InfluxDB 3 Enterprise. #### Request body required Content-Type: `application/json` `db` required string The database name. `table` string The table name. If omitted, deletes the database-level file index. Example request body ```json { "db": "mydb", "table": "mytable" } ``` Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://localhost:8181/api/v3/enterprise/configure/file_index" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{"db":"mydb","table":"mytable"}' ``` #### Responses 200 Success. The file index has been deleted. 400 Bad request. 401 Unauthorized access. `data` object `error` string 404 Database, table, or file index not found. #### Related - [Manage databases](/influxdb3/enterprise/admin/databases/) - [InfluxDB 3 API client libraries](/influxdb3/enterprise/reference/client-libraries/v3/)