Stage restore upload (limited rollout)

curl --request POST \
  --url https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

api

databases

{id}

backups

restore-upload

init

Stage restore upload (limited rollout)

curl --request POST \
  --url https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/databases/{id}/backups/restore-upload/init")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

The staged upload contract sends dump bytes directly from the browser or CLI to an isolated S3 prefix. The file does not transit Vercel, Caddy, or the agent request body.

Limited availability: this is not a normal customer or published CLI workflow. Upload initialization requires the exact restore rollout binding and agent capability. Other databases receive FEATURE_NOT_AVAILABLE, and uploading an artifact does not by itself authorize or start a restore.

The historical multipart POST /api/v1/databases/{id}/backups/restore route remains only as a fail-closed compatibility endpoint. It never reads the upload body or calls the agent: exact rollout targets receive PRESIGNED_UPLOAD_REQUIRED, while all other targets receive FEATURE_NOT_AVAILABLE.

Supported files

Extension	Description
`.sql`	Plain SQL dump
`.sql.gz`	Gzip-compressed plain SQL dump
`.dump`	`pg_dump` custom format
`.backup`	`pg_dump` custom format with alternate extension

Maximum object size is 512 MB. The client supplies the exact size and SHA-256 checksum during initialization and completion. Plain .sql and .sql.gz input is limited to 512 MB after decompression and 16 MiB per physical SQL line, including one COPY row. Use custom-format .dump or .backup when a single value requires a larger line. Restore staging has a 30-minute execution deadline; the separate five-minute maintenance window starts only when a validated staging database is ready to swap.

1. Initialize upload

POST /api/v1/databases/{id}/backups/restore-upload/init Send a unique Idempotency-Key header and reuse it only when retrying this exact database, filename, size, and checksum binding. The CLI generates one for each new upload. The key must contain 8-128 characters.

{
  "filename": "mybackup.sql.gz",
  "sizeBytes": 1048576,
  "checksumSha256": "<64 lowercase hex characters>"
}

202 Accepted

{
  "message": "Restore upload initialized",
  "operation": {
    "id": "op_01J...",
    "type": "restore",
    "status": "running",
    "stage": "upload",
    "progress": 1
  },
  "object": {
    "id": "obj_01J...",
    "expiresAt": "2026-07-20T12:15:00Z",
    "maxSizeBytes": 536870912
  },
  "upload": {
    "method": "POST",
    "url": "<short-lived presigned URL>",
    "expiresInSeconds": 900,
    "fields": {
      "key": "<isolated operation/object key>",
      "policy": "<signed policy>",
      "x-amz-signature": "<signature>"
    }
  }
}

The presigned URL is bound to the operation, object ID, isolated prefix, size, checksum, content type, encryption policy, and a 15-minute expiry. Treat it as a temporary secret. Send every returned form field unchanged and append the file as the final multipart field named file.

2. Upload directly

Send the file bytes to the returned S3 URL using the exact method and form fields. Do not send the DBHost API key to S3. The dump never passes through a DBHost API, Vercel, Caddy, or agent request body.

3. Complete upload

POST /api/v1/databases/{id}/backups/restore-upload/complete

{
  "operationId": "op_01J...",
  "objectId": "obj_01J...",
  "sizeBytes": 1048576,
  "checksumSha256": "<64 lowercase hex characters>"
}

202 Accepted

{
  "message": "Restore artifact queued for validation",
  "operation": {
    "id": "op_01J...",
    "type": "restore",
    "status": "queued",
    "stage": "validate_artifact",
    "progress": 5
  }
}

Completion verifies the object binding, size and checksum before format/schema validation. Poll GET /api/v1/operations/{id} for further status.

Errors

Status	Code	Description
400	`INVALID_FILENAME`	Filename does not use a supported extension
400	`INVALID_CHECKSUM`	Checksum is missing or malformed
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Caller can view backups but cannot manage them
404	`DATABASE_NOT_FOUND`	Database is missing or outside key scope
409	`OPERATION_CONFLICT`	Another destructive operation is active
409	`UPLOAD_NOT_READY`	The uploaded object is not visible in storage yet
410	`UPLOAD_EXPIRED`	Presigned upload or operation has expired
413	`PAYLOAD_TOO_LARGE`	Declared or stored object exceeds 512 MB
413	`SIZE_MISMATCH`	Stored object size differs from initialization
422	`CHECKSUM_MISMATCH`	Stored object differs from declared checksum
404	`FEATURE_NOT_AVAILABLE`	The database is outside the approved restore rollout
503	`AGENT_CAPABILITY_UNAVAILABLE`	Staged upload is unavailable for this agent

Overview

Databases

Backups

Limited rollout

Operations

Health

Stage restore upload (limited rollout)

Supported files

1. Initialize upload

2. Upload directly

3. Complete upload

Errors

​Supported files

​1. Initialize upload

​2. Upload directly

​3. Complete upload

​Errors

Supported files

1. Initialize upload

2. Upload directly

3. Complete upload

Errors