> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turso.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Database

Upload a SQLite database file to a database created with `seed.type = "database_upload"`.

<Note>
  This endpoint is on the **database hostname** (e.g., `my-db-my-org.turso.io`), not `api.turso.tech`.
</Note>

<Note>
  You must first [create a database](/api-reference/databases/create) with `seed.type = "database_upload"`.
</Note>

<Note>
  This endpoint requires a **database token**, not a platform API token. You can [create a database token](/api-reference/databases/create-token) after creating the database.
</Note>

## Headers

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | Bearer token for the database |
| `Content-Length` | Yes | Size of the database file in bytes |
| `x-turso-encryption-key` | No | Base64-encoded encryption key (32 bytes for 256-bit ciphers, 16 bytes for 128-bit ciphers) |
| `x-turso-encryption-cipher` | No | Encryption cipher. See table below for options. |

## Request Body

The raw binary SQLite database file.

## Database File Requirements

The SQLite database file must meet these requirements:

* **Journal mode**: WAL (`PRAGMA journal_mode = WAL`)
* **Page size**: 4096 bytes (`PRAGMA page_size = 4096`)
* **Auto vacuum**: Disabled (`PRAGMA auto_vacuum = 0`)
* **Encoding**: UTF-8 (`PRAGMA encoding = 'UTF-8'`)

For encrypted databases, you must also set the reserved bytes to match the cipher:

| Cipher | Reserved Bytes |
| - | - |
| `aes256gcm` | 28 |
| `aes128gcm` | 28 |
| `chacha20poly1305` | 28 |
| `aegis128l` | 32 |
| `aegis128x2` | 32 |
| `aegis128x4` | 32 |
| `aegis256` | 48 |
| `aegis256x2` | 48 |
| `aegis256x4` | 48 |

## Responses

### Success

Returns an empty response with status `200 OK` on success.

### Errors

| Status | Description |
| - | - |
| `400` | Invalid database file (wrong format, settings, or corruption) |
| `401` | Invalid or missing authorization token |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://{database_hostname}/v1/upload' \
    -H 'Authorization: Bearer DATABASE_TOKEN' \
    -H 'Content-Length: FILE_SIZE' \
    --data-binary '@/path/to/database.db'
  ```

  ```bash cURL (with encryption) theme={null}
  curl -X POST 'https://{database_hostname}/v1/upload' \
    -H 'Authorization: Bearer DATABASE_TOKEN' \
    -H 'Content-Length: FILE_SIZE' \
    -H 'x-turso-encryption-key: BASE64_ENCRYPTION_KEY' \
    -H 'x-turso-encryption-cipher: aes256gcm' \
    --data-binary '@/path/to/database.db'
  ```
</RequestExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.