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

[Download InfluxDB 3 Core API Spec](/openapi/influxdb3-core-openapi.yml)

Create, list, and delete databases in InfluxDB 3 Core.

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.

#### Related

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