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

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

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.

#### Related

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