openapi: 3.1.0
info:
  title: Cloudflare D1 API
  description: >-
    The Cloudflare D1 API provides endpoints for managing serverless SQL
    databases on Cloudflare's network. Developers can create, list, and delete
    databases, execute raw queries, import and export database contents, and
    use time travel to restore databases to previous states.
  version: '4.0'
  contact:
    name: Cloudflare Support
    url: https://support.cloudflare.com/
  termsOfService: https://www.cloudflare.com/terms/
externalDocs:
  description: Cloudflare D1 API Documentation
  url: https://developers.cloudflare.com/api/resources/d1/
servers:
- url: https://api.cloudflare.com/client/v4
  description: Cloudflare API v4 Production Server
tags:
- name: Databases
  description: >-
    Create, list, update, and delete D1 serverless SQL databases.
- name: Import/Export
  description: >-
    Import SQL into and export SQL from D1 databases.
- name: Queries
  description: >-
    Execute SQL queries against D1 databases.
- name: Time Travel
  description: >-
    Browse and restore D1 databases to previous points in time.
security:
- bearerAuth: []
paths:
  /accounts/{account_id}/d1/database:
    get:
      operationId: listD1Databases
      summary: Cloudflare List D1 Databases
      description: >-
        Returns a paginated list of all D1 databases for the account.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: page
        in: query
        description: Page number of results.
        schema:
          type: integer
          minimum: 1
        example: 10
      - name: per_page
        in: query
        description: Number of results per page.
        schema:
          type: integer
        example: 10
      - name: name
        in: query
        description: Filter databases by name.
        schema:
          type: string
        example: Example Title
      responses:
        '200':
          description: List of D1 databases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/D1DatabaseListResponse'
              examples:
                Listd1databases200Example:
                  summary: Default listD1Databases 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - uuid: '500123'
                      name: Example Title
                      version: example_value
                      num_tables: 10
                      file_size: 10
                      created_at: '2026-01-15T10:30:00Z'
                    success: true
                    result_info:
                      page: 10
                      per_page: 10
                      count: 10
                      total_count: 10
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createD1Database
      summary: Cloudflare Create D1 Database
      description: >-
        Create a new D1 serverless SQL database.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the database.
                primary_location_hint:
                  type: string
                  description: >-
                    Hint for the primary location of the database. Specify a
                    Cloudflare region.
            examples:
              Created1databaseRequestExample:
                summary: Default createD1Database request
                x-microcks-default: true
                value:
                  name: Example Title
                  primary_location_hint: example_value
      responses:
        '200':
          description: Database created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/D1DatabaseResponse'
              examples:
                Created1database200Example:
                  summary: Default createD1Database 200 response
                  x-microcks-default: true
                  value:
                    result:
                      uuid: '500123'
                      name: Example Title
                      version: example_value
                      num_tables: 10
                      file_size: 10
                      created_at: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}:
    get:
      operationId: getD1Database
      summary: Cloudflare Get D1 Database
      description: >-
        Retrieve details of a specific D1 database.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      responses:
        '200':
          description: Database details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/D1DatabaseResponse'
              examples:
                Getd1database200Example:
                  summary: Default getD1Database 200 response
                  x-microcks-default: true
                  value:
                    result:
                      uuid: '500123'
                      name: Example Title
                      version: example_value
                      num_tables: 10
                      file_size: 10
                      created_at: '2026-01-15T10:30:00Z'
                    success: true
                    errors:
                    - {}
                    messages:
                    - {}
        '401':
          description: Unauthorized.
        '404':
          description: Database not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateD1Database
      summary: Cloudflare Update D1 Database
      description: >-
        Update a D1 database configuration.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new name for the database.
            examples:
              Updated1databaseRequestExample:
                summary: Default updateD1Database request
                x-microcks-default: true
                value:
                  name: Example Title
      responses:
        '200':
          description: Database updated successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Database not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteD1Database
      summary: Cloudflare Delete D1 Database
      description: >-
        Delete a D1 database and all its contents.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      responses:
        '200':
          description: Database deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Database not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}/query:
    post:
      operationId: queryD1Database
      summary: Cloudflare Query D1 Database
      description: >-
        Execute a SQL query against the D1 database. Returns results with
        metadata about the execution.
      tags:
      - Queries
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sql
              properties:
                sql:
                  type: string
                  description: The SQL query to execute.
                params:
                  type: array
                  items:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                    - type: 'null'
                  description: Bound parameters for the query.
            examples:
              Queryd1databaseRequestExample:
                summary: Default queryD1Database request
                x-microcks-default: true
                value:
                  sql: example_value
                  params:
                  - {}
      responses:
        '200':
          description: Query executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/D1QueryResponse'
              examples:
                Queryd1database200Example:
                  summary: Default queryD1Database 200 response
                  x-microcks-default: true
                  value:
                    result:
                    - results:
                      - {}
                      success: true
                      meta:
                        changed_db: true
                        changes: 10
                        duration: 42.5
                        last_row_id: '500123'
                        rows_read: 10
                        rows_written: 10
                        size_after: 10
                    success: true
        '400':
          description: Bad request or SQL error.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}/raw:
    post:
      operationId: rawQueryD1Database
      summary: Cloudflare Raw Query D1 Database
      description: >-
        Execute a raw SQL query optimized for performance. Returns results as
        arrays instead of objects.
      tags:
      - Queries
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - sql
              properties:
                sql:
                  type: string
                  description: The SQL query to execute.
                params:
                  type: array
                  items:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                    - type: 'null'
                  description: Bound parameters for the query.
            examples:
              Rawqueryd1databaseRequestExample:
                summary: Default rawQueryD1Database request
                x-microcks-default: true
                value:
                  sql: example_value
                  params:
                  - {}
      responses:
        '200':
          description: Raw query executed successfully.
        '400':
          description: Bad request or SQL error.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}/export:
    post:
      operationId: exportD1Database
      summary: Cloudflare Export D1 Database
      description: >-
        Export the database contents as SQL. Returns a URL for downloading the
        SQL dump.
      tags:
      - Import/Export
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      responses:
        '200':
          description: Export initiated successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}/import:
    post:
      operationId: importD1Database
      summary: Cloudflare Import Sql Into D1 Database
      description: >-
        Import SQL into the database. Returns a temporary upload URL and import
        status.
      tags:
      - Import/Export
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      responses:
        '200':
          description: Import initiated successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}/time_travel/bookmark:
    get:
      operationId: getD1Bookmark
      summary: Cloudflare Get D1 Database Bookmark
      description: >-
        Retrieve the current or a historical bookmark for the database, which
        represents a point-in-time snapshot.
      tags:
      - Time Travel
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      responses:
        '200':
          description: Bookmark retrieved.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /accounts/{account_id}/d1/database/{database_id}/time_travel/restore:
    post:
      operationId: restoreD1Database
      summary: Cloudflare Restore D1 Database
      description: >-
        Restore the database to a previous state using a bookmark from time
        travel.
      tags:
      - Time Travel
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/DatabaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - bookmark
              properties:
                bookmark:
                  type: string
                  description: The bookmark identifier to restore to.
            examples:
              Restored1databaseRequestExample:
                summary: Default restoreD1Database request
                x-microcks-default: true
                value:
                  bookmark: example_value
      responses:
        '200':
          description: Database restored successfully.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token with D1 permissions.
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: The unique identifier of the Cloudflare account.
      schema:
        type: string
    DatabaseId:
      name: database_id
      in: path
      required: true
      description: The unique identifier of the D1 database.
      schema:
        type: string
  schemas:
    D1Database:
      type: object
      properties:
        uuid:
          type: string
          description: The unique identifier of the database.
          example: '500123'
        name:
          type: string
          description: The name of the database.
          example: Example Title
        version:
          type: string
          description: The version of the database.
          example: example_value
        num_tables:
          type: integer
          description: Number of tables in the database.
          example: 10
        file_size:
          type: integer
          description: Size of the database file in bytes.
          example: 10
        created_at:
          type: string
          format: date-time
          description: When the database was created.
          example: '2026-01-15T10:30:00Z'
    D1DatabaseResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/D1Database'
        success:
          type: boolean
          example: true
        errors:
          type: array
          items:
            type: object
          example: []
        messages:
          type: array
          items:
            type: object
          example: []
    D1DatabaseListResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/D1Database'
          example: []
        success:
          type: boolean
          example: true
        result_info:
          type: object
          properties:
            page:
              type: integer
            per_page:
              type: integer
            count:
              type: integer
            total_count:
              type: integer
          example: example_value
    D1QueryResponse:
      type: object
      properties:
        result:
          type: array
          items:
            type: object
            properties:
              results:
                type: array
                items:
                  type: object
              success:
                type: boolean
              meta:
                type: object
                properties:
                  changed_db:
                    type: boolean
                  changes:
                    type: integer
                  duration:
                    type: number
                    description: Query duration in milliseconds.
                  last_row_id:
                    type: integer
                  rows_read:
                    type: integer
                  rows_written:
                    type: integer
                  size_after:
                    type: integer
          example: []
        success:
          type: boolean
          example: true