> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Backblaze B2 Indexing API

> Index a Backblaze B2 bucket, a directory, or a single file using a read-only application key. Captain reads B2 through its S3-compatible API.

## Agent Quick Reference: Backblaze B2 indexing

* Auth = a Backblaze **application key** (keyID + applicationKey), used as S3-compatible credentials. The **master application key does not work** with the S3-compatible API; it must be a regular application key.
* One-time setup at secure.backblaze.com → Application Keys → Add a New Application Key: restrict it to the target bucket, set access to **Read Only**, copy the `applicationKey` immediately (shown once).
* Request fields (all endpoints): `access_key_id` (the keyID), `secret_access_key` (the applicationKey), `endpoint_url` (`https://s3.<region>.backblazeb2.com`, from the bucket's details page), `region` (e.g. `us-west-004`, matching the endpoint), `bucket_name`, `processing_type` ("advanced" | "basic" | "auto").
* Endpoints:
  * `POST /v2/collections/{name}/index/backblaze`: the whole bucket
  * `POST /v2/collections/{name}/index/backblaze/directory`: one directory (recursive), field `directory_path`
  * `POST /v2/collections/{name}/index/backblaze/file`: one file, field `file_uri` (object key)
* Common error: signature/authorization failures usually mean the master key was used, the endpoint region doesn't match the bucket, or the key is restricted to a different bucket.

Captain indexes Backblaze B2 through B2's S3-compatible API. You create one
read-only application key scoped to the bucket you want indexed, and Captain
uses it to read the whole bucket, a directory (recursively), or a single
file. No Backblaze account access beyond that key is involved.

## What you provide

| Value               | What it is                                                                         |
| ------------------- | ---------------------------------------------------------------------------------- |
| `access_key_id`     | The application key's **keyID**.                                                   |
| `secret_access_key` | The **applicationKey** itself. Shown once at creation; used per job, never stored. |
| `endpoint_url`      | Your bucket's S3-compatible endpoint, `https://s3.<region>.backblazeb2.com`.       |
| `region`            | The region in that endpoint, e.g. `us-west-004`.                                   |
| `bucket_name`       | The bucket to index.                                                               |

## One-time setup

1. Sign in at [secure.backblaze.com](https://secure.backblaze.com) and go to
   **Application Keys**.
2. Click **Add a New Application Key** and name it (for example
   `captain-indexing`).
3. Under **Allow access to Bucket(s)**, pick the one bucket you want
   indexed.
4. Set **Type of Access** to **Read Only**.
5. Click **Create New Key**. Copy both the **keyID** and the
   **applicationKey** right away; the applicationKey is shown only once.
6. Find your endpoint: open **Buckets**, and copy the **Endpoint** shown on
   the bucket (for example `s3.us-west-004.backblazeb2.com`). The region is
   the middle segment (`us-west-004`).

> **Warning**
>
> The account's **master application key does not work** with the
> S3-compatible API. Always create a regular application key as above.

## Indexing

All three endpoints take the same credential fields and differ only in
scope.

### A whole bucket

```bash
curl -X POST "https://api.filesearch.dev/v2/collections/{collection_name}/index/backblaze" \
  -H "Authorization: Bearer $CAPTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "<keyID>",
    "secret_access_key": "<applicationKey>",
    "endpoint_url": "https://s3.us-west-004.backblazeb2.com",
    "region": "us-west-004",
    "bucket_name": "company-documents",
    "processing_type": "advanced"
  }'
```

### A directory (recursively)

```bash
curl -X POST "https://api.filesearch.dev/v2/collections/{collection_name}/index/backblaze/directory" \
  -H "Authorization: Bearer $CAPTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "<keyID>",
    "secret_access_key": "<applicationKey>",
    "endpoint_url": "https://s3.us-west-004.backblazeb2.com",
    "region": "us-west-004",
    "bucket_name": "company-documents",
    "directory_path": "reports/2026",
    "processing_type": "advanced"
  }'
```

Subdirectories are indexed too.

### A single file

```bash
curl -X POST "https://api.filesearch.dev/v2/collections/{collection_name}/index/backblaze/file" \
  -H "Authorization: Bearer $CAPTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "<keyID>",
    "secret_access_key": "<applicationKey>",
    "endpoint_url": "https://s3.us-west-004.backblazeb2.com",
    "region": "us-west-004",
    "bucket_name": "company-documents",
    "file_uri": "reports/annual-review.pdf",
    "processing_type": "advanced"
  }'
```

`file_uri` is the object key within the bucket.

Every response is `{ "job_id": "...", "status": "pending" }`. Poll
`GET /v2/jobs/{job_id}` for progress, then query the
collection with `POST /v2/collections/{name}/query`.

## Troubleshooting

| Symptom                                | Cause & fix                                                                                                                                                                            |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Signature or authorization errors      | The master application key was used (it doesn't work with the S3-compatible API); create a regular application key. Or the key is restricted to a different bucket than `bucket_name`. |
| Connection or endpoint errors          | The `region` doesn't match the `endpoint_url`, or the endpoint isn't the one shown on the bucket's details page.                                                                       |
| A job finishes with some files skipped | Those object keys fall outside the key's file-name-prefix restriction, if you set one. Widen the prefix or move the files.                                                             |

## Security notes

* Create the key **Read Only** and scoped to the single bucket; Captain
  never needs write access.
* The applicationKey is a credential: treat it like a password. Revoke it
  any time from the Application Keys page.
* Captain uses the key per job; nothing durable is stored beyond the
  request.