# Backblaze B2 Native API v3 Reference

Verified spec for the methods used by this skill, against the live ACG B2
account (accountId `46f69bc61163`, region `us-west-001`). All facts below were
confirmed against the live API.

---

## Authorization (v3)

- **Authorize URL (fixed, global):**
  `https://api.backblazeb2.com/b2api/v3/b2_authorize_account`
- **Auth:** HTTP Basic. Username = key id, password = application key.
- **Method:** GET in the B2 docs; this skill issues it as an HTTPS POST with the
  Basic header, which the endpoint accepts.

### Authorize response (v3 shape)

```json
{
  "accountId": "46f69bc61163",
  "authorizationToken": "<token, valid 24h>",
  "apiInfo": {
    "storageApi": {
      "apiUrl": "https://api001.backblazeb2.com",
      "s3ApiUrl": "https://s3.us-west-001.backblazeb2.com",
      "downloadUrl": "https://f001.backblazeb2.com",
      "recommendedPartSize": 100000000,
      "absoluteMinimumPartSize": 5000000,
      "capabilities": ["listBuckets", "listFiles", "..."],
      "bucketId": null,
      "namePrefix": null
    }
  }
}
```

- **v3 nesting:** `apiUrl` / `s3ApiUrl` / `downloadUrl` / `capabilities` /
  `bucketId` / `namePrefix` live under `apiInfo.storageApi`. (v2 returned
  `apiUrl` / `downloadUrl` at the top level — do NOT parse them there for v3.)
- `bucketId == null` and `namePrefix == null` means an **account-wide** key;
  non-null means the key is scoped to one bucket / name prefix.
- The per-account `apiUrl` is dynamic and comes ONLY from this response — never
  from a config file.

### Cache model

The skill caches `authorizationToken` + `apiUrl` + `accountId` (plus the other
fields) in `.claude/skills/b2/.cache/auth.json` with an `authorized_at`
timestamp. It is treated as valid for ~23h (B2 tokens last 24h). A `401` with
code `expired_auth_token` or `bad_auth_token` triggers exactly one re-authorize
+ retry. **The cached token is a secret; the cache dir is gitignored.**

---

## Subsequent calls

- **URL:** `POST <apiUrl>/b2api/v3/<method>`
- **Header:** `Authorization: <authorizationToken>` (raw token, not Basic).
- **Body:** a JSON object.
- **Content-Type:** `application/json`.

### Error shape

B2 returns HTTP 4xx with a JSON body:

```json
{ "status": 400, "code": "<string>", "message": "<text>" }
```

The skill surfaces `status` / `code` / `message` verbatim. On `401` with
`expired_auth_token` / `bad_auth_token` it re-authorizes once and retries; all
other errors raise. Destructive calls are never retried automatically.

---

## Methods used

All POST to `<apiUrl>/b2api/v3/<method>`.

### b2_list_buckets

- **Body:** `{"accountId": "<acct>", "bucketId": <opt>}`
- **Returns:** `{"buckets": [{bucketName, bucketId, bucketType, revision,
  fileLockConfiguration:{isFileLockEnabled}, lifecycleRules, options}]}`
- Pass `bucketId` to scope the result to a single bucket.
- **`revision`** (int) is the bucket's optimistic-concurrency version. NOTE:
  this account's `b2_update_bucket` does NOT accept `ifRevisionMatch`, so this
  value is informational only — it is read but never sent back on a write.
- **`lifecycleRules`** (array) is the bucket's current lifecycle rule set (see
  the rule shape under `b2_update_bucket`). An empty array means no rules.

### b2_list_keys

- **Body:** `{"accountId": "<acct>", "maxKeyCount": 1000,
  "startApplicationKeyId": <opt>}`
- **Returns:** `{"keys": [{keyName, applicationKeyId, capabilities:[...],
  bucketId, namePrefix, expirationTimestamp}], "nextApplicationKeyId": <null
  when done>}`
- Paginate on `nextApplicationKeyId`.

### b2_list_file_names

- **Body:** `{"bucketId": "<id>", "maxFileCount": 10000, "prefix": <opt>,
  "startFileName": <opt>}`
- **Returns:** `{"files": [{fileName, contentLength, action, uploadTimestamp,
  ...}], "nextFileName": <null when done>}`
- Lists the **latest** name for each file. Use for quick listings; NOT for
  size/cost.

### b2_list_file_versions

- **Body:** `{"bucketId": "<id>", "maxFileCount": 10000, "prefix": <opt>,
  "startFileName": <opt>, "startFileId": <opt>}`
- **Returns:** `{"files": [{fileName, fileId, contentLength, action, ...}],
  "nextFileName": <null when done>, "nextFileId": ...}`
- **Pagination:** carry BOTH `nextFileName` AND `nextFileId` into the next
  request; stop when `nextFileName` is null.

#### action types

| action | meaning | billed? |
|---|---|---|
| `upload` | a real stored object | YES |
| `hide` | a hide marker (`contentLength` 0) | no |
| `start` | an unfinished large file | no |
| `folder` | a virtual folder placeholder | no |

**For size/cost, sum `contentLength` over ALL versions where
`action == "upload"`.** B2 bills every stored version, not just the latest, so
size MUST use `b2_list_file_versions`, never `b2_list_file_names`.

### b2_create_bucket (destructive — gated)

- **Body:** `{"accountId": "<acct>", "bucketName": "<name>", "bucketType":
  "allPrivate"}`
- `bucketType` defaults to `allPrivate`; the CLI allows `allPublic` via `--type`.

### b2_create_key (destructive — gated)

- **Body:** `{"accountId": "<acct>", "keyName": "<name>",
  "capabilities": [...], "bucketId": <opt>, "namePrefix": <opt>,
  "validDurationInSeconds": <opt>}`
- **Returns:** `{applicationKeyId, applicationKey, keyName, capabilities,
  bucketId, namePrefix}`.
- **`applicationKey` is the SECRET and is shown ONCE on creation** — it cannot be
  retrieved later. The CLI prints it with a prominent warning to store it in the
  vault immediately.
- `bucketId` scopes the key to one bucket (the CLI resolves a bucket name to its
  id via `b2_list_buckets`).

### b2_delete_bucket (destructive — gated)

- **Body:** `{"accountId": "<acct>", "bucketId": "<id>"}`
- B2 **refuses to delete a non-empty bucket**; that error is surfaced verbatim.

### b2_delete_key (destructive — gated)

- **Body:** `{"applicationKeyId": "<id>"}`

### b2_update_bucket (destructive — gated)

Used for the prefix-purge feature: it writes the bucket's lifecycle rules.

- **Body:** `{"accountId": "<acct>", "bucketId": "<id>",
  "lifecycleRules": [...]}`
- **Returns:** the updated bucket object (same shape as a `b2_list_buckets`
  entry, including the NEW `revision` and the written `lifecycleRules`).
- **`lifecycleRules` REPLACES the entire array — it is NOT additive (caveat).**
  To add/remove a single rule you MUST first read the current rules via
  `b2_list_buckets` (scoped to the bucketId), merge your change into the full
  array, then write the complete set back. Writing just the one rule you want
  silently drops every other rule.
- **No `ifRevisionMatch` on this account/endpoint.** This B2 account's
  `b2_update_bucket` REJECTS `ifRevisionMatch` with **HTTP 400** `bad_request`
  ("unknown field ... ifRevisionMatch"), so no optimistic-lock token is sent.
  Writes are therefore **last-write-wins** — the read-merge-write of the full
  rules array on every change is what keeps pre-existing rules intact. The skill
  does not implement a 409-conflict retry (there is no revision guard); it makes
  at most one defensive retry on a transient 5xx, never loops.
- B2 allows up to **100** lifecycle rules per bucket.

#### Lifecycle rule shape

```json
{ "fileNamePrefix": "MBS-<guid>/CBB_<machine>/",
  "daysFromUploadingToHiding": 1,
  "daysFromHidingToDeleting": 1 }
```

- `fileNamePrefix` — files whose name starts with this string are governed by the
  rule. `""` means the WHOLE BUCKET.
- `daysFromUploadingToHiding` — after this many days, B2's daily lifecycle pass
  HIDES the file (creates a hide marker).
- `daysFromHidingToDeleting` — after this many days hidden, B2 DELETES the file
  version permanently.
- With both `= 1`, every version older than ~1 day is hidden then deleted on the
  next daily passes -> full server-side purge of the prefix within ~24-48h. This
  is the mechanism the skill uses to purge prefixes with 1.2M+ versions, where
  per-file `b2_delete_file_version` would be impractical. **Irreversible — no
  recycle bin.**

### b2_get_file_info / b2_delete_file_version

- `b2_get_file_info` body: `{"fileId": "<id>"}` (read).
- `b2_delete_file_version` body: `{"fileName": "<name>", "fileId": "<id>"}`
  (destructive; exposed only via `raw --confirm` or the client helper).

---

## Cost formula

```
GB   = bytes / 1_000_000_000          # decimal GB (billing unit, NOT 2^30)
cost = GB * RATE_PER_GB_USD           # RATE_PER_GB_USD = 0.00695 (ACG cost basis)
```

`RATE_PER_GB_USD` is ACG's cost basis, recorded in
`.claude/memory/reference_backblaze_storage_rate.md`, and used by the GuruRMM
mspbackups storage-cost calc. Override with `--rate`. The `usage` report sums
upload-version bytes per bucket, converts to decimal GB, multiplies by the rate,
sorts by cost desc, and prints a TOTAL row plus grand totals. For `ACG-*`
buckets it derives a client label by stripping the `ACG-` prefix.

---

## Account structure (live)

- accountId `46f69bc61163`, region `us-west-001`.
- 12 buckets (all `allPrivate`): ACG-BST, ACG-Brett, ACG-Dataforth, ACG-GLAZTECH,
  ACG-IX, ACG-Internal, ACG-Lens, ACG-PST, ACG-REDNOUR, Horseshoe,
  MSPBackups20200311, VWP-Backup. Most hold MSP360/CloudBerry data
  (`MBS-<guid>/CBB_<CLIENT>/...`).
- 2 application keys: `cloudberrykey` (`00146f69bc611630000000003`, the
  MSP360/CloudBerry key) and `ClaudeTools` (`00146f69bc611630000000009`, used by
  this skill).