Indexing

Backblaze B2 Indexing API

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

ValueWhat it is
access_key_idThe application key’s keyID.
secret_access_keyThe applicationKey itself. Shown once at creation; used per job, never stored.
endpoint_urlYour bucket’s S3-compatible endpoint, https://s3.<region>.backblazeb2.com.
regionThe region in that endpoint, e.g. us-west-004.
bucket_nameThe bucket to index.

One-time setup

  1. Sign in at 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).

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

$curl -X POST "https://api.runcaptain.com/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)

$curl -X POST "https://api.runcaptain.com/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

$curl -X POST "https://api.runcaptain.com/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/collections/{name}/jobs/{job_id} for progress, then query the collection with POST /v2/collections/{name}/query.

Troubleshooting

SymptomCause & fix
Signature or authorization errorsThe 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 errorsThe 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 skippedThose 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.
© 2026 Captain