Database

Download InfluxDB 3 Core API Spec
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
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
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
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
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
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.

Was this page helpful?

Thank you for your feedback!