Cloudflare D1 D1 API
The D1 API from Cloudflare D1 — 8 operation(s) for d1.
Documentation
Documentation
https://developers.cloudflare.com/d1/
Authentication
https://developers.cloudflare.com/d1/get-started/
OpenAPI Specification
openapi: 3.0.3
info:
title: Cloudflare D1 API
description: REST API for managing and querying Cloudflare D1 serverless SQLite databases. Provides endpoints for database lifecycle management (create, list, get, delete), SQL query execution (query and raw modes), data import/export, and Time Travel point-in-time restore operations.
version: 4.0.0
contact:
name: Cloudflare Support
url: https://developers.cloudflare.com/support/
license:
name: BSD 3-Clause
url: https://github.com/cloudflare/cloudflare-python/blob/main/LICENSE
servers:
- url: https://api.cloudflare.com/client/v4
description: Cloudflare API v4
security:
- api_token: []
- api_key: []
api_email: []
tags:
- name: D1
paths:
/accounts/{account_id}/d1/database:
get:
description: Returns a list of D1 databases.
operationId: d1-list-databases
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: query
name: name
schema:
description: a database name to search for.
type: string
- in: query
name: page
schema:
default: 1
description: Page number of paginated results.
minimum: 1
type: number
- in: query
name: per_page
schema:
default: 1000
description: Number of items per page.
maximum: 10000
minimum: 10
type: number
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: List D1 databases response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
items:
$ref: '#/components/schemas/d1_database-response'
type: array
result_info:
properties:
count:
description: Total number of results for the requested service
example: 1
type: number
page:
description: Current page within paginated list of results
example: 1
type: number
per_page:
description: Number of results per page of results
example: 20
type: number
total_count:
description: Total results available without any search parameters
example: 2000
type: number
type: object
description: List D1 databases response
security:
- api_token: []
- api_email: []
api_key: []
summary: List D1 Databases
tags:
- D1
x-api-token-group:
- D1 Read
- D1 Write
post:
description: Returns the created D1 database.
operationId: d1-create-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
requestBody:
content:
application/json:
schema:
properties:
jurisdiction:
$ref: '#/components/schemas/d1_jurisdiction'
name:
$ref: '#/components/schemas/d1_database-name'
primary_location_hint:
$ref: '#/components/schemas/d1_primary-location-hint'
read_replication:
$ref: '#/components/schemas/d1_read-replication-details-for-request'
required:
- name
type: object
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Database details response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
$ref: '#/components/schemas/d1_database-details-response'
description: Returns the created D1 database's metadata
security:
- api_token: []
- api_email: []
api_key: []
summary: Create D1 Database
tags:
- D1
x-api-token-group:
- D1 Write
/accounts/{account_id}/d1/database/{database_id}:
delete:
description: Deletes the specified D1 database.
operationId: d1-delete-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Delete D1 database response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
enum:
- null
nullable: true
type: object
description: Delete D1 database response
security:
- api_token: []
- api_email: []
api_key: []
summary: Delete D1 Database
tags:
- D1
x-api-token-group:
- D1 Write
get:
description: Returns the specified D1 database.
operationId: d1-get-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
oneOf:
- $ref: '#/components/schemas/d1_database-identifier'
- $ref: '#/components/schemas/d1_database-name'
- description: 'Comma-separated list of fields to include in the response. When omitted,
all fields are returned.
'
example: uuid,name,version
explode: false
in: query
name: fields
schema:
items:
enum:
- uuid
- name
- created_at
- version
- jurisdiction
- num_tables
- file_size
- running_in_region
- read_replication
type: string
type: array
style: form
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Database details response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
$ref: '#/components/schemas/d1_database-details-response'
description: Database details response
security:
- api_token: []
- api_email: []
api_key: []
summary: Get D1 Database
tags:
- D1
x-api-token-group:
- D1 Read
- D1 Write
patch:
description: Updates partially the specified D1 database.
operationId: d1-update-partial-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_database-update-partial-request-body'
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Update D1 database response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
$ref: '#/components/schemas/d1_database-details-response'
description: Database details response
security:
- api_token: []
- api_email: []
api_key: []
summary: Update D1 Database partially
tags:
- D1
x-api-token-group:
- D1 Write
put:
description: Updates the specified D1 database.
operationId: d1-update-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_database-update-request-body'
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Update D1 database response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
$ref: '#/components/schemas/d1_database-details-response'
description: Database details response
security:
- api_token: []
- api_email: []
api_key: []
summary: Update D1 Database
tags:
- D1
x-api-token-group:
- D1 Write
/accounts/{account_id}/d1/database/{database_id}/export:
post:
description: 'Returns a URL where the SQL contents of your D1 can be downloaded. Note: this process may take
some time for larger DBs, during which your D1 will be unavailable to serve queries. To avoid
blocking your DB unnecessarily, an in-progress export must be continually polled or will automatically cancel.
'
operationId: d1-export-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
requestBody:
content:
application/json:
schema:
properties:
current_bookmark:
description: To poll an in-progress export, provide the current bookmark (returned by your first polling response)
type: string
x-auditable: true
dump_options:
properties:
no_data:
description: Export only the table definitions, not their contents
type: boolean
x-auditable: true
no_schema:
description: Export only each table's contents, not its definition
type: boolean
x-auditable: true
tables:
description: 'Filter the export to just one or more tables. Passing an empty array is the same as not passing anything and means: export all tables.'
items:
type: string
x-auditable: true
type: array
type: object
output_format:
description: Specifies that you will poll this endpoint until the export completes
enum:
- polling
type: string
x-auditable: true
required:
- output_format
type: object
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Poll failed (API error)
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
properties:
at_bookmark:
description: The current time-travel bookmark for your D1, used to poll for updates. Will not change for the duration of the export task.
type: string
x-auditable: true
error:
description: Only present when status = 'error'. Contains the error message.
type: string
x-auditable: true
messages:
description: Logs since the last time you polled
items:
type: string
x-auditable: true
type: array
result:
description: Only present when status = 'complete'
properties:
filename:
description: The generated SQL filename.
type: string
x-auditable: true
signed_url:
description: The URL to download the exported SQL. Available for one hour.
type: string
type: object
status:
enum:
- complete
- error
type: string
x-auditable: true
success:
type: boolean
x-auditable: true
type:
enum:
- export
type: string
x-auditable: true
type: object
description: Polled successfully, task no longer running (errored or complete)
'202':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
properties:
at_bookmark:
description: The current time-travel bookmark for your D1, used to poll for updates. Will not change for the duration of the export task.
type: string
x-auditable: true
messages:
description: Logs since the last time you polled
items:
type: string
x-auditable: true
type: array
status:
enum:
- active
type: string
x-auditable: true
success:
type: boolean
x-auditable: true
type:
enum:
- export
type: string
x-auditable: true
type: object
description: Polled successfully, task is currently running
security:
- api_token: []
- api_email: []
api_key: []
summary: Export D1 Database as SQL
tags:
- D1
/accounts/{account_id}/d1/database/{database_id}/import:
post:
description: 'Generates a temporary URL for uploading an SQL file to, then instructing the D1 to import it
and polling it for status updates. Imports block the D1 for their duration.
'
operationId: d1-import-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
requestBody:
content:
application/json:
schema:
oneOf:
- properties:
action:
description: Indicates you have a new SQL file to upload.
enum:
- init
type: string
x-auditable: true
etag:
description: Required when action is 'init' or 'ingest'. An md5 hash of the file you're uploading. Used to check if it already exists, and validate its contents before ingesting.
type: string
x-auditable: true
required:
- action
- etag
title: init
type: object
- properties:
action:
description: Indicates you've finished uploading to tell the D1 to start consuming it
enum:
- ingest
type: string
x-auditable: true
etag:
description: An md5 hash of the file you're uploading. Used to check if it already exists, and validate its contents before ingesting.
type: string
x-auditable: true
filename:
description: The filename you have successfully uploaded.
type: string
x-auditable: true
required:
- action
- etag
- filename
title: ingest
type: object
- properties:
action:
description: Indicates you've finished uploading to tell the D1 to start consuming it
enum:
- poll
type: string
x-auditable: true
current_bookmark:
description: This identifies the currently-running import, checking its status.
type: string
x-auditable: true
required:
- action
- current_bookmark
title: poll
type: object
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Poll failed (API error)
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
properties:
at_bookmark:
description: The current time-travel bookmark for your D1, used to poll for updates. Will not change for the duration of the import. Only returned if an import process is currently running or recently finished.
type: string
x-auditable: true
error:
description: Only present when status = 'error'. Contains the error message that prevented the import from succeeding.
type: string
x-auditable: true
filename:
description: Derived from the database ID and etag, to use in avoiding repeated uploads. Only returned when for the 'init' action.
type: string
x-auditable: true
messages:
description: Logs since the last time you polled
items:
type: string
x-auditable: true
type: array
result:
description: Only present when status = 'complete'
properties:
final_bookmark:
description: The time-travel bookmark if you need restore your D1 to directly after the import succeeded.
type: string
x-auditable: true
meta:
$ref: '#/components/schemas/d1_query-meta'
num_queries:
description: The total number of queries that were executed during the import.
type: number
x-auditable: true
type: object
status:
enum:
- complete
- error
type: string
x-auditable: true
success:
type: boolean
x-auditable: true
type:
enum:
- import
type: string
x-auditable: true
upload_url:
description: The R2 presigned URL to use for uploading. Only returned when for the 'init' action.
type: string
type: object
description: Successful action. Import is either ready to start, under way, or finished (succeeded or failed).
'202':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
properties:
at_bookmark:
description: The current bookmark for your D1, used to poll for updates. Will not change for the duration of the import.
type: string
x-auditable: true
messages:
description: Logs since the last time you polled
items:
type: string
x-auditable: true
type: array
status:
enum:
- active
type: string
x-auditable: true
success:
type: boolean
x-auditable: true
type:
enum:
- import
type: string
x-auditable: true
type: object
description: Polled successfully, task is currently running
security:
- api_token: []
- api_email: []
api_key: []
summary: Import SQL into your D1 Database
tags:
- D1
/accounts/{account_id}/d1/database/{database_id}/query:
post:
description: Returns the query result as an object.
operationId: d1-query-database
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_batch-query'
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Query response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
items:
$ref: '#/components/schemas/d1_query-result-response'
type: array
description: Query response
security:
- api_token: []
- api_email: []
api_key: []
summary: Query D1 Database
tags:
- D1
x-api-token-group:
- D1 Read
- D1 Write
/accounts/{account_id}/d1/database/{database_id}/raw:
post:
description: Returns the query result rows as arrays rather than objects. This is a performance-optimized version of the /query endpoint.
operationId: d1-raw-database-query
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_batch-query'
required: true
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Query response failure
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
items:
$ref: '#/components/schemas/d1_raw-result-response'
type: array
description: Raw query response
security:
- api_token: []
- api_email: []
api_key: []
summary: Raw D1 Database query
tags:
- D1
x-api-token-group:
- D1 Read
- D1 Write
/accounts/{account_id}/d1/database/{database_id}/time_travel/bookmark:
get:
description: 'Retrieves the current bookmark, or the nearest bookmark at or before a provided timestamp.
Bookmarks can be used with the restore endpoint to revert the database to a previous point in time.
'
operationId: d1-time-travel-get-bookmark
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
- description: An optional ISO 8601 timestamp. If provided, returns the nearest available bookmark at or before this timestamp. If omitted, returns the current bookmark.
in: query
name: timestamp
schema:
$ref: '#/components/schemas/d1_time-travel-timestamp'
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Failed to retrieve bookmark
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
properties:
bookmark:
$ref: '#/components/schemas/d1_time-travel-bookmark'
type: object
description: Bookmark retrieved successfully
security:
- api_token: []
- api_email: []
api_key: []
summary: Get D1 database bookmark
tags:
- D1
x-api-token-group:
- D1 Read
- D1 Write
/accounts/{account_id}/d1/database/{database_id}/time_travel/restore:
post:
description: 'Restores a D1 database to a previous point in time either via a bookmark or a timestamp.
'
operationId: d1-time-travel-restore
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/d1_account-identifier'
- in: path
name: database_id
required: true
schema:
$ref: '#/components/schemas/d1_database-identifier'
- description: A bookmark to restore the database to. Required if `timestamp` is not provided.
in: query
name: bookmark
schema:
$ref: '#/components/schemas/d1_time-travel-bookmark'
- description: An ISO 8601 timestamp to restore the database to. Required if `bookmark` is not provided.
in: query
name: timestamp
schema:
$ref: '#/components/schemas/d1_time-travel-timestamp'
responses:
4XX:
content:
application/json:
schema:
$ref: '#/components/schemas/d1_api-response-common-failure'
description: Restore operation failed
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/d1_api-response-common'
- properties:
result:
$ref: '#/components/schemas/d1_time-travel-restore-response'
description: Database restored successfully
security:
- api_token: []
- api_email: []
api_key: []
summary: Restore D1 Database to a bookmark or point in time
tags:
- D1
components:
schemas:
d1_messages:
example: []
items:
properties:
code:
minimum: 1000
type: integer
message:
type: string
required:
- code
- message
type: object
uniqueItems: true
type: array
d1_database-name:
description: D1 database name.
example: my-database
pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$
type: string
x-auditable: true
d1_database-details-response:
description: The details of the D1 database.
properties:
created_at:
$ref: '#/components/schemas/d1_created-at'
file_size:
$ref: '#/components/schemas/d1_file-size'
jurisdiction:
$ref: '#/components/schemas/d1_jurisdiction-nullable'
name:
$ref: '#/components/schemas/d1_database-name'
num_tables:
$ref: '#/components/schemas/d1_table-count'
read_replication:
$ref: '#/components/schemas/d1_read-replication-details-for-response'
uuid:
$ref: '#/components/schemas/d1_database-identifie
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cloudflare-d1/refs/heads/main/openapi/cloudflare-d1-d1-api-openapi.yml