---
title: Database
description: Create, list, and delete databases in InfluxDB 3 Enterprise.
url: https://docs.influxdata.com/influxdb3/enterprise/api/database/
estimated_tokens: 1803
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/api/database/
---

[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`requiredstring

`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

200Success. The response body contains the list of databases.

`databases`string[]

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database not found.

POST`/api/v3/configure/database`

### Create a database

Creates a new database in the system.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

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

200Success. Database created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

409Database already exists.

PUT`/api/v3/configure/database`

### Update a database

Updates database configuration, such as retention period.

#### Request bodyrequired

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

200Success. The database has been updated.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database 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`requiredstring

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 \<date-time\>

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

200Success. Database deleted.

401Unauthorized access.

`data`object

`error`string

404Database 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`requiredstring

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

204Success. The database retention period has been removed.

401Unauthorized access.

`data`object

`error`string

404Database 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 bodyrequired

Content-Type:`application/json`

`columns`requiredstring[]

The columns to use for the file index.

`db`requiredstring

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

200Success. The file index has been created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database 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 bodyrequired

Content-Type:`application/json`

`db`requiredstring

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

200Success. The file index has been deleted.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database, table, or file index not found.

#### Related

* [Manage databases](/influxdb3/enterprise/admin/databases/)
* [InfluxDB 3 API client libraries](/influxdb3/enterprise/reference/client-libraries/v3/)