openapi: 3.2.0
info:
  version: 2.57.0
  title: Netlify's API documentation Database API
  description: 'Netlify is a hosting service for the programmable web. It understands your documents and provides an API to handle atomic deploys of websites, manage form submissions, inject JavaScript snippets, and much more. This is a REST-style API that uses JSON for serialization and OAuth 2 for authentication.


    This document is an OpenAPI reference for the Netlify API that you can explore. For more detailed instructions for common uses, please visit the [online documentation](https://www.netlify.com/docs/api/). Visit our Community forum to join the conversation about [understanding and using Netlify''s API](https://community.netlify.com/t/common-issue-understanding-and-using-netlifys-api/160).


    Additionally, we have two API clients for your convenience:

    - [Go Client](https://github.com/netlify/open-api#go-client)

    - [JS Client](https://github.com/netlify/build/tree/main/packages/js-client)'
  termsOfService: https://www.netlify.com/legal/terms-of-use/
  x-logo:
    url: netlify-logo.png
    href: https://www.netlify.com/docs/
    altText: Netlify
servers:
- url: https://api.netlify.com/api/v1
security:
- netlifyAuth: []
tags:
- name: database
  x-displayName: Database
paths:
  /sites/{site_id}/database:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: createSiteDatabase
      tags:
      - database
      description: Creates a new database for the specified site. If a database already exists, returns the existing connection string. The database region defaults to the site's functions region if not specified.
      responses:
        '200':
          description: Database already exists
          content:
            application/json:
              schema:
                type: object
                description: Response containing the database connection string
                properties:
                  connection_string:
                    type: string
                    description: The connection string for the database
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                description: Response containing the database connection string
                properties:
                  connection_string:
                    type: string
                    description: The connection string for the database
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for creating a database
              properties:
                region:
                  type: string
                  description: The region where the database should be created. Defaults to the site's functions region if not specified.
    get:
      operationId: getSiteDatabase
      tags:
      - database
      description: Returns the database connection string for the specified site.
      parameters:
      - name: role
        in: query
        description: The database role to use for the connection string. Defaults to netlifydb_owner if not specified.
        schema:
          type: string
          enum:
          - netlifydb_owner
          - netlifydb_readonly
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Response containing the database connection string
                properties:
                  connection_string:
                    type: string
                    description: The connection string for the database
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
    delete:
      operationId: deleteSiteDatabase
      tags:
      - database
      description: Deletes the database and all associated branches and snapshots for the specified site.
      responses:
        '204':
          description: Deleted
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/branch:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: createSiteDatabaseBranch
      tags:
      - database
      description: Creates a new database branch. If a branch already exists for the specified branch ID, returns the existing connection string.
      responses:
        '200':
          description: Branch already exists
          content:
            application/json:
              schema:
                type: object
                description: Response containing the database branch connection string
                properties:
                  connection_string:
                    type: string
                    description: The connection string for the database branch
                  metadata:
                    type: object
                    description: Metadata associated with the branch
                    additionalProperties: true
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                description: Response containing the database branch connection string
                properties:
                  connection_string:
                    type: string
                    description: The connection string for the database branch
                  metadata:
                    type: object
                    description: Metadata associated with the branch
                    additionalProperties: true
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for creating a database branch
              required:
              - branch_id
              properties:
                parent_branch_id:
                  type: string
                  description: The ID of the parent branch to create the new branch from. Defaults to the production branch if not specified.
                branch_id:
                  type: string
                  description: The branch identifier
                metadata:
                  type: object
                  description: Arbitrary metadata to associate with the branch
                  additionalProperties: true
        required: true
  /sites/{site_id}/database/branches:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listSiteDatabaseBranches
      tags:
      - database
      description: Returns all branches for the site's database with compute status and metadata.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Response containing a list of database branches
                properties:
                  branches:
                    type: array
                    items:
                      type: object
                      description: Detailed information about a database branch
                      properties:
                        branch_id:
                          type: string
                          description: The branch identifier
                        name:
                          type: string
                          description: The branch name
                        connection_string:
                          type: string
                          description: The connection string for the branch
                        state:
                          type: string
                          description: The current state of the branch
                          enum:
                          - init
                          - creating
                          - resetting
                          - ready
                          - archived
                        logical_size_bytes:
                          type: integer
                          format: int64
                          description: The logical size of the branch in bytes
                        created_at:
                          type: string
                          format: dateTime
                          description: When the branch was created
                        updated_at:
                          type: string
                          format: dateTime
                          description: When the branch was last updated
                        last_active_at:
                          type: string
                          format: dateTime
                          description: When the branch was last active
                        compute:
                          type: object
                          description: Compute endpoint status for a branch
                          properties:
                            current_state:
                              type: string
                              description: The current state of the compute endpoint
                              enum:
                              - active
                              - idle
                            autoscaling_limit_min_cu:
                              type: number
                              format: double
                              description: Minimum compute units for autoscaling
                            autoscaling_limit_max_cu:
                              type: number
                              format: double
                              description: Maximum compute units for autoscaling
                            suspend_timeout_seconds:
                              type: integer
                              format: int64
                              description: Seconds of inactivity before the compute endpoint is suspended
                            last_active:
                              type: string
                              format: dateTime
                              description: When the compute endpoint was last active
                        metadata:
                          type: object
                          description: Metadata associated with the branch
                          additionalProperties: true
                    description: List of database branches
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/branch/{branch_id}:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: branch_id
      in: path
      required: true
      description: The branch ID
      schema:
        type: string
    get:
      operationId: getSiteDatabaseBranch
      tags:
      - database
      description: Returns the database branch connection string for a specific branch.
      parameters:
      - name: role
        in: query
        description: The database role to use for the connection string. Defaults to netlifydb_owner if not specified.
        schema:
          type: string
          enum:
          - netlifydb_owner
          - netlifydb_readonly
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Response containing the database branch connection string
                properties:
                  connection_string:
                    type: string
                    description: The connection string for the database branch
                  metadata:
                    type: object
                    description: Metadata associated with the branch
                    additionalProperties: true
        '404':
          description: Branch not found
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
    delete:
      operationId: deleteSiteDatabaseBranch
      tags:
      - database
      description: Deletes a database branch.
      responses:
        '204':
          description: Deleted
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/branch/{branch_id}/reset:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: branch_id
      in: path
      required: true
      description: The branch ID to reset
      schema:
        type: string
    post:
      operationId: resetSiteDatabaseBranch
      tags:
      - database
      description: Resets a non-production database branch by re-forking it from a source branch (defaults to the production branch). If the target branch is already in sync with the source, returns the existing connection string without performing a reset, unless `force=true` is passed. The production branch cannot be reset.
      parameters:
      - name: force
        in: query
        description: If true, resets the branch even when it is already in sync with the source.
        schema:
          type: boolean
      - name: role
        in: query
        description: The database role to use for the returned connection string. Defaults to netlifydb_owner if not specified.
        schema:
          type: string
          enum:
          - netlifydb_owner
          - netlifydb_readonly
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Response for a database branch reset
                properties:
                  reset:
                    type: boolean
                    description: Whether the branch was actually re-forked. False when the target was already in sync with the source and `force=true` was not set.
                  connection_string:
                    type: string
                    description: The connection string for the reset (or unchanged) branch
                  metadata:
                    type: object
                    description: Metadata associated with the branch
                    additionalProperties: true
        '400':
          description: Invalid request — for example, the target is the production branch or the source branch is the same as the target.
        '404':
          description: Database or branch not found
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for resetting a database branch
              properties:
                source_branch_id:
                  type: string
                  description: The ID of the branch to re-fork the target branch from. Defaults to "production" if not specified.
  /sites/{site_id}/database/branch/{branch_id}/compute/settings:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: branch_id
      in: path
      required: true
      description: The branch ID
      schema:
        type: string
    put:
      operationId: setSiteDatabaseBranchComputeSettings
      tags:
      - database
      description: Sets compute settings for a specific database branch, overriding project-level settings. Requires a Pro or higher plan.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Compute settings for a database or branch
                properties:
                  min_cu:
                    type: number
                    format: double
                    description: Minimum compute units
                  max_cu:
                    type: number
                    format: double
                    description: Maximum compute units
                  sleep_timeout_seconds:
                    type: integer
                    format: int64
                    description: Seconds of inactivity before suspension
        '403':
          description: Compute customization requires a Pro or higher plan
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for setting compute settings. All fields are optional; only provided fields are updated.
              properties:
                min_cu:
                  type:
                  - number
                  - 'null'
                  format: double
                  minimum: 0.25
                  maximum: 16
                  description: Minimum compute units (0.25 to 16.0). Must be less than or equal to max_cu.
                max_cu:
                  type:
                  - number
                  - 'null'
                  format: double
                  minimum: 0.25
                  maximum: 16
                  description: Maximum compute units (0.25 to 16.0). Must be greater than or equal to min_cu. max_cu - min_cu must not exceed 8.0.
                sleep_timeout_seconds:
                  type:
                  - integer
                  - 'null'
                  format: int64
                  minimum: -1
                  description: Seconds of inactivity before the compute endpoint is suspended. Use -1 for always on, or a non-negative value.
        required: true
  /sites/{site_id}/database/compute/settings:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    put:
      operationId: setSiteDatabaseComputeSettings
      tags:
      - database
      description: Sets project-level compute settings for the database. Applied to new branches. Can be overridden per-branch. Requires a Pro or higher plan.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Compute settings for a database or branch
                properties:
                  min_cu:
                    type: number
                    format: double
                    description: Minimum compute units
                  max_cu:
                    type: number
                    format: double
                    description: Maximum compute units
                  sleep_timeout_seconds:
                    type: integer
                    format: int64
                    description: Seconds of inactivity before suspension
        '403':
          description: Compute customization requires a Pro or higher plan
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for setting compute settings. All fields are optional; only provided fields are updated.
              properties:
                min_cu:
                  type:
                  - number
                  - 'null'
                  format: double
                  minimum: 0.25
                  maximum: 16
                  description: Minimum compute units (0.25 to 16.0). Must be less than or equal to max_cu.
                max_cu:
                  type:
                  - number
                  - 'null'
                  format: double
                  minimum: 0.25
                  maximum: 16
                  description: Maximum compute units (0.25 to 16.0). Must be greater than or equal to min_cu. max_cu - min_cu must not exceed 8.0.
                sleep_timeout_seconds:
                  type:
                  - integer
                  - 'null'
                  format: int64
                  minimum: -1
                  description: Seconds of inactivity before the compute endpoint is suspended. Use -1 for always on, or a non-negative value.
        required: true
    get:
      operationId: getSiteDatabaseComputeSettings
      tags:
      - database
      description: Returns the project-level compute settings for the database. Returns effective settings (custom or tier defaults). Requires a Pro or higher plan.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Compute settings for a database or branch
                properties:
                  min_cu:
                    type: number
                    format: double
                    description: Minimum compute units
                  max_cu:
                    type: number
                    format: double
                    description: Maximum compute units
                  sleep_timeout_seconds:
                    type: integer
                    format: int64
                    description: Seconds of inactivity before suspension
        '403':
          description: Compute customization requires a Pro or higher plan
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
    delete:
      operationId: clearSiteDatabaseComputeSettings
      tags:
      - database
      description: Resets project-level compute settings to tier defaults. Requires a Pro or higher plan.
      responses:
        '204':
          description: Cleared
        '403':
          description: Compute customization requires a Pro or higher plan
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/migrations:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listSiteDatabaseMigrations
      tags:
      - database
      description: Returns the list of migrations available for the specified branch, indicating which ones have been applied to the database.
      parameters:
      - name: branch
        in: query
        description: The branch ID to list migrations for. Defaults to "production" if not specified.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Response containing the list of migrations for a branch
                properties:
                  migrations:
                    type: array
                    items:
                      type: object
                      description: A migration available to a database branch
                      properties:
                        version:
                          type: integer
                          format: int64
                          description: The migration version number
                        name:
                          type: string
                          description: The migration name
                        path:
                          type: string
                          description: The path to the migration file in the deploy bundle
                        applied:
                          type: boolean
                          description: Whether this migration has been applied to the branch
                    description: List of migrations
        '404':
          description: Database or branch not found
        '423':
          description: Database is disabled
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/migrations/{name}:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: name
      in: path
      required: true
      description: The migration name
      schema:
        type: string
    get:
      operationId: getSiteDatabaseMigration
      tags:
      - database
      description: Returns the contents of a named migration for the specified branch.
      parameters:
      - name: branch
        in: query
        description: The branch ID to look up the migration on. Defaults to the currently published deploy's branch.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: A migration with its file contents
                properties:
                  version:
                    type: integer
                    format: int64
                    description: The migration version number
                  name:
                    type: string
                    description: The migration name
                  path:
                    type: string
                    description: The path to the migration file in the deploy bundle
                  content:
                    type: string
                    description: The raw contents of the migration file
        '404':
          description: Migration, database, or branch not found
        '423':
          description: Database is disabled
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/migrations/{deploy_id}:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: deploy_id
      in: path
      required: true
      description: The deploy ID to run migrations for
      schema:
        type: string
    post:
      operationId: runSiteDatabaseMigrations
      tags:
      - database
      description: Runs database migrations for the specified deploy. Finds the deploy and determines the appropriate branch.
      responses:
        '200':
          description: OK
        '409':
          description: Migration conflict - migration modified or removed after being applied
        '422':
          description: Migration validation failed
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for running database migrations
              properties:
                dry_run:
                  type: boolean
                  description: If true, validates migrations without applying them.
  /sites/{site_id}/database/snapshot:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: createSiteDatabaseSnapshot
      tags:
      - database
      description: Creates a point-in-time snapshot of a database branch. Defaults to the production branch if no branch name is specified.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                description: A point-in-time snapshot of a database branch
                properties:
                  id:
                    type: string
                    description: The unique identifier of the snapshot
                  source_branch_id:
                    type: string
                    description: The ID of the branch that was snapshotted
                  manual:
                    type: boolean
                    description: Whether this snapshot was manually created
                  created_at:
                    type: string
                    format: dateTime
                    description: When the snapshot was created
                  expires_at:
                    type: string
                    format: dateTime
                    description: When the snapshot expires
                  timestamp:
                    type: string
                    format: dateTime
                    description: The point-in-time timestamp of the snapshot
                  metadata:
                    type: object
                    description: Metadata associated with a snapshot
                    properties:
                      deploy:
                        type: object
                        description: Deploy information associated with the snapshot
                        additionalProperties: true
                      source:
                        type: string
                        description: The source that created the snapshot
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for creating a database snapshot
              properties:
                branch_id:
                  type: string
                  description: The ID of the branch to snapshot. Defaults to "production" if not specified.
                name:
                  type: string
                  description: A name for the snapshot
                metadata:
                  type: object
                  description: Metadata associated with a snapshot
                  properties:
                    deploy:
                      type: object
                      description: Deploy information associated with the snapshot
                      additionalProperties: true
                    source:
                      type: string
                      description: The source that created the snapshot
  /sites/{site_id}/database/snapshots:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listSiteDatabaseSnapshots
      tags:
      - database
      description: Returns all snapshots for the site's database.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Response containing a list of database snapshots
                properties:
                  snapshots:
                    type: array
                    items:
                      type: object
                      description: A point-in-time snapshot of a database branch
                      properties:
                        id:
                          type: string
                          description: The unique identifier of the snapshot
                        source_branch_id:
                          type: string
                          description: The ID of the branch that was snapshotted
                        manual:
                          type: boolean
                          description: Whether this snapshot was manually created
                        created_at:
                          type: string
                          format: dateTime
                          description: When the snapshot was created
                        expires_at:
                          type: string
                          format: dateTime
                          description: When the snapshot expires
                        timestamp:
                          type: string
                          format: dateTime
                          description: The point-in-time timestamp of the snapshot
                        metadata:
                          type: object
                          description: Metadata associated with a snapshot
                          properties:
                            deploy:
                              type: object
                              description: Deploy information associated with the snapshot
                              additionalProperties: true
                            source:
                              type: string
                              description: The source that created the snapshot
                    description: List of database snapshots
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/snapshot/{snapshot_id}:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: snapshot_id
      in: path
      required: true
      description: The snapshot ID
      schema:
        type: string
    delete:
      operationId: deleteSiteDatabaseSnapshot
      tags:
      - database
      description: Deletes a database snapshot.
      responses:
        '204':
          description: Deleted
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
  /sites/{site_id}/database/snapshot/{snapshot_id}/restore:
    parameters:
    - name: site_id
      in: path
      required: true
      schema:
        type: string
    - name: snapshot_id
      in: path
      required: true
      description: The snapshot ID to restore
      schema:
        type: string
    post:
      operationId: restoreSiteDatabaseSnapshot
      tags:
      - database
      description: Restores a snapshot to a database branch. Defaults to the production branch if no branch_name is specified.
      responses:
        '200':
          description: OK
        default:
          description: error
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  code:
                    type: integer
                    format: int64
                  message:
                    type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Request body for restoring a database snapshot
              properties:
                branch_id:
                  type: string
                  description: The ID of the branch to restore the snapshot to. Defaults to "production" if not specified.
components:
  securitySchemes:
    netlifyAuth:
      type: oauth2
      flows:
        implicit:
          scopes: {}
          authorizationUrl: https://app.netlify.com/authorize
externalDocs:
  url: https://www.netlify.com/docs/api/
  description: Online documentation
x-tagGroups:
- name: OAuth
  tags:
  - ticket
  - accessToken
- name: User accounts
  tags:
  - user
  - accountMembership
  - member
  - accountType
  - paymentMethod
  - auditLog
- name: Site
  tags:
  - site
  - environmentVariables
  - file
  - metadata
  - purge
  - snippet
- name: Domain names
  tags:
  - dnsZone
  - sniCertificate
- name: Deploys
  tags:
  - deploy
  - deployedBranch
  - deployKey
- name: Builds
  tags:
  - build
  - buildLogMsg
- name: Dev servers
  tags:
  - devServer
- name: Webhooks and notifications
  tags:
  - hook
  - hookType
  - buildHook
  - devServerHook
- name: Services
  tags:
  - service
  - serviceInstance
- name: Functions
  tags:
  - function
- name: Database
  tags:
  - database
- name: Forms
  tags:
  - form
  - submission
- name: Split tests
  tags:
  - splitTest
- name: Large media
  tags:
  - asset
  - assetPublicSignature