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

# Backblaze B2

> Sync files from Backblaze B2 Cloud Storage into Mixpeek buckets using the S3-compatible API.

> [!NOTE]
>
> Backblaze B2 is an S3-compatible object storage service. Mixpeek auto-discovers your regional endpoint — you only need your application key ID and application key.

## Overview

The Backblaze B2 integration lets Mixpeek sync objects from any B2 bucket into your Mixpeek buckets for processing. Each file becomes a bucket object with its metadata, ready for feature extraction in your collections.

Mixpeek uses Backblaze's S3-compatible API via the standard AWS SDK. On connection creation, it calls the B2 authorization API to discover your account's correct regional endpoint (e.g., `s3.us-east-005.backblazeb2.com`) automatically.

## Prerequisites

* An active [Backblaze](https://www.backblaze.com/b2/cloud-storage.html) account with B2 Cloud Storage enabled.
* An application key with at minimum: `listBuckets`, `listFiles`, and `readFiles` capabilities.
* The key ID and application key (shown once at creation — copy it immediately).

## Configuration

### Connection-Level Fields

| Field | Required | Description |
| - | - | - |
| `key_id` | Yes | Backblaze B2 application key ID |
| `application_key` | Yes | Backblaze B2 application key (secret) — encrypted at rest |

### Sync-Level Fields

| Field | Required | Description |
| - | - | - |
| `source_path` | Yes | `b2://bucket-name/optional/prefix` or `bucket-name/prefix` |
| `sync_mode` | No | `continuous` (default) or `initial_only` |
| `polling_interval_seconds` | No | Seconds between polls in `continuous` mode |
| `include_patterns` | No | Glob patterns to include (e.g., `["*.mp4", "*.jpg"]`) |
| `exclude_patterns` | No | Glob patterns to exclude (e.g., `["*.tmp"]`) |
| `modified_since` | No | Only sync files modified after this ISO 8601 timestamp |

## Setup

**1. Create a Backblaze application key**

1. Log in to the [Backblaze Console](https://secure.backblaze.com/b2_buckets.htm).
2. Go to **App Keys** in the left sidebar.
3. Click **Add a New Application Key**.
4. Set a name (e.g., `mixpeek-sync`) and choose the buckets to grant access to.
5. Enable: **Read and Write Files**, **List Buckets**, **List Files**, **Read Files**.
6. Click **Create New Key** and **copy both the keyID and applicationKey immediately** — the key is shown only once.

> [!WARNING]
>
> The application key is shown only once at creation. If you lose it, you must create a new key.

**2. Create the storage connection in Mixpeek**

```python Python theme={null}
from mixpeek import Mixpeek

client = Mixpeek(api_key="your-mixpeek-api-key")

connection = client.organizations.connections.create(
    name="Backblaze B2 Production",
    provider_type="backblaze",
    provider_config={
        "credentials": {
            "type": "application_key",
            "key_id": "005870eff85b6c60000000001",
            "application_key": "K005...",
        },
    },
)
print(f"Created connection: {connection['connection_id']}")
```

```javascript JavaScript theme={null}
import { Mixpeek } from 'mixpeek-sdk'

const client = new Mixpeek({ apiKey: 'your-mixpeek-api-key' })

const connection = await client.organizations.connections.create({
  name: 'Backblaze B2 Production',
  provider_type: 'backblaze',
  provider_config: {
    credentials: {
      type: 'application_key',
      key_id: '005870eff85b6c60000000001',
      application_key: 'K005...',
    },
  },
})
console.log('Created connection:', connection.connection_id)
```

```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/organizations/connections \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backblaze B2 Production",
    "provider_type": "backblaze",
    "provider_config": {
      "credentials": {
        "type": "application_key",
        "key_id": "005870eff85b6c60000000001",
        "application_key": "K005..."
      }
    }
  }'
```

**3. Create a sync configuration on your bucket**

```python Python theme={null}
sync = client.buckets.syncs.create(
    bucket_id="bkt_your_bucket_id",
    connection_id=connection["connection_id"],
    source_path="b2://my-backblaze-bucket/videos/",
    sync_mode="continuous",
    polling_interval_seconds=3600,  # Hourly
)
print(f"Sync created: {sync['sync_config_id']}")
```

```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/buckets/bkt_your_bucket_id/syncs \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_your_connection_id",
    "source_path": "b2://my-backblaze-bucket/videos/",
    "sync_mode": "continuous",
    "polling_interval_seconds": 3600
  }'
```

**4. Trigger your first sync**

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/buckets/bkt_your_bucket_id/syncs/SYNC_CONFIG_ID/trigger \
  -H "Authorization: Bearer YOUR_MIXPEEK_API_KEY" \
  -H "X-Namespace: ns_your_namespace_id"
```

## Advanced Configuration

### Scoped Key (Recommended)

For production, create a key scoped to a specific bucket:

1. In Backblaze Console → App Keys → Add New Key
2. Under **Allow access to Bucket(s)**, select a single bucket
3. This limits the key's blast radius if it's ever compromised

### File Filtering

Filter which files are synced using glob patterns:

```python theme={null}
sync = client.buckets.syncs.create(
    bucket_id="bkt_your_bucket_id",
    connection_id=connection["connection_id"],
    source_path="b2://my-bucket/",
    sync_mode="continuous",
    polling_interval_seconds=86400,
    include_patterns=["*.mp4", "*.mov", "*.jpg"],
    exclude_patterns=["*_thumbnail.*", "*.tmp"],
)
```

### Incremental Sync

Only sync files added or modified after a specific date:

```python theme={null}
from datetime import datetime, timezone

sync = client.buckets.syncs.create(
    bucket_id="bkt_your_bucket_id",
    connection_id=connection["connection_id"],
    source_path="b2://my-bucket/",
    sync_mode="continuous",
    polling_interval_seconds=300,
    modified_since="2024-01-01T00:00:00Z",
)
```

## Source Path Format

The `source_path` supports multiple formats:

| Format | Example | Description |
| - | - | - |
| `b2://bucket/prefix` | `b2://my-videos/2024/` | Preferred — explicit B2 scheme |
| `s3://bucket/prefix` | `s3://my-videos/2024/` | S3-style URI also accepted |
| `bucket/prefix` | `my-videos/2024/` | Bare bucket + prefix |
| `bucket` | `my-videos` | Entire bucket |

## Sync Modes

| Mode | Description | When to Use |
| - | - | - |
| `continuous` | Polls every `polling_interval_seconds` | Real-time monitoring, active uploads. Set a longer interval for regular batch processing |
| `initial_only` | Single import, then completes | Historical backfills, migrations |

## Troubleshooting

> [accordion] Connection test returns 401 Unauthorized
>
> Your key ID or application key is incorrect:
>
> 1. In the Backblaze Console → App Keys, verify the keyID column matches what you entered.
> 2. The application key is only shown once — if you lost it, create a new key.
> 3. Ensure the key has not expired or been deleted.

> [accordion] No files synced from a bucket that has objects
>
> * Verify the `source_path` matches the correct bucket name (case-sensitive).
> * Check that your application key has **listFiles** and **readFiles** capabilities.
> * If the key is scoped to a specific bucket, ensure the bucket name in `source_path` matches exactly.
> * Check `include_patterns` — make sure they match your file extensions.

> [accordion] Connection test succeeds but sync returns Access Denied
>
> Your application key may have **listBuckets** but not **listFiles** on a specific bucket:
>
> 1. Create a new key with **List Files** and **Read Files** enabled for the target bucket.
> 2. Update the connection with the new key.

> [accordion] Files in sub-folders are not being synced
>
> Backblaze B2 uses flat key namespacing (like S3). Folders are just key prefixes.
>
> * Use `b2://bucket/` (trailing slash) to sync all files recursively.
> * Use `b2://bucket/subfolder/` to scope to a specific prefix.

## Related

* [Bucket Syncs](https://docs.mixpeek.com/docs/api-reference/bucket-syncs/create-sync-configuration.md)
* [Storage Connections](https://docs.mixpeek.com/docs/api-reference/organization-connections/create-storage-connection.md)
* [Amazon S3 Integration](https://docs.mixpeek.com/docs/integrations/object-storage/s3.md)
* [Tigris Integration](https://docs.mixpeek.com/docs/integrations/object-storage/tigris.md)


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