A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Backblaze B2 API is how an app or AI agent works with B2 cloud storage: uploading and downloading files, listing and deleting their versions, creating and managing buckets, and minting application keys. Access is granted through an application key that carries a set of capabilities, like listBuckets or writeFiles, and a key can be limited to a single bucket and a single file name prefix. Backblaze B2 can also push an event to a webhook when a file is created, deleted, or hidden in a bucket.
How an app or AI agent connects to Backblaze B2 determines what it can reach. There is the B2 Native API for storage operations, an S3-compatible API for tools that already speak S3, and event notifications for receiving activity, each governed by the application key behind it and the capabilities that key carries.
The B2 Native API is Backblaze's own storage API. A call first hits b2_authorize_account with the application key over HTTP Basic auth, which returns an authorization token and the base URL to send every later request to. The version is a number in the path, like v3.
Backblaze B2 also exposes an S3-compatible API, so tools and libraries built for Amazon S3 can read and write B2 buckets with little change. It uses the same application keys as the Native API.
Event notifications POST a JSON payload to a webhook URL when a file is created, deleted, or hidden in a bucket. A rule can set an hmacSha256SigningSecret, and each delivery then carries an X-Bz-Event-Notification-Signature header so the receiver can confirm it came from Backblaze.
An application key is a keyID and applicationKey pair sent to b2_authorize_account with HTTP Basic auth. The key carries a set of capabilities, like listBuckets, readFiles, or writeFiles, and can be limited to a single bucket and a single file name prefix. The authorize call returns a short-lived token used for every other request.
The master application key is the account-wide key created with the account. It carries every capability across all buckets and cannot be restricted, so Backblaze recommends a scoped application key for day-to-day work.
The B2 Native API is split into areas an agent can act on, like buckets, files, large uploads, and application keys. Each method names the capability it needs, and writes in some areas delete data or mint new keys.
Exchange an application key for an authorization token and the base URL to use for every later call.
Create, list, update, and delete the buckets that hold files.
Upload, list, get metadata for, download, copy, hide, and delete files.
Start a multi-part upload, upload each part, then finish or cancel it.
Create, list, and delete the application keys that grant access to the account.
Read and set the rules that send a webhook when files change in a bucket.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AuthorizationExchange an application key for an authorization token and the base URL to use for every later call.1 | ||||||
| GET | /b2api/v3/b2_authorize_account | Exchange an application key ID and key for an authorization token and the base URL for later calls. | read | — | Current | |
The only call that uses HTTP Basic auth with the keyID and applicationKey; no capability is needed to call it. The response reports the capabilities, buckets, and name prefix the key is allowed. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BucketsCreate, list, update, and delete the buckets that hold files.4 | ||||||
| POST | /b2api/v3/b2_create_bucket | Create a bucket with a globally unique name. | write | writeBuckets | Current | |
The token must have the writeBuckets capability. Acts onbucket Permission (capability) writeBucketsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_list_buckets | List the buckets in an account, in alphabetical order by name. | read | listBuckets | Current | |
The token must have the listBuckets capability. A key restricted to one bucket lists only that bucket. Acts onbucket Permission (capability) listBucketsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_update_bucket | Update a bucket's properties, like its type, lifecycle rules, encryption, or Object Lock. | write | writeBuckets | Current | |
The token must have the writeBuckets capability. Acts onbucket Permission (capability) writeBucketsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_delete_bucket | Delete a bucket, which must hold no file versions first. | write | deleteBuckets | Current | |
The token must have the deleteBuckets capability. The bucket must be empty. Acts onbucket Permission (capability) deleteBucketsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FilesUpload, list, get metadata for, download, copy, hide, and delete files.10 | ||||||
| GET | /b2api/v3/b2_get_upload_url | Get a URL and token used to upload a file to a specified bucket. | write | writeFiles | Current | |
The token must have the writeFiles capability. The returned upload URL points at a specific pod and is used by b2_upload_file. Acts onupload URL Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_upload_file | Upload a single file to a bucket, in one request, up to 5 GB. | write | writeFiles | Current | |
Sent to the upload URL from b2_get_upload_url, not the main API host, with that call's writeFiles authorization. Files over 5 GB use the large-file flow. Acts onfile Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook event object_created_uploadRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_list_file_names | List file names in a bucket, the current version of each, up to 10,000 per call. | read | listFiles | Current | |
The token must have the listFiles capability. Returning more than 1,000 files in one call counts as multiple class C transactions. Acts onfile Permission (capability) listFilesVersionAvailable since the API’s base version Webhook eventNone Rate limit1 class C transaction per 1,000 files returned SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_list_file_versions | List every version of the files in a bucket, by name then newest first. | read | listFiles | Current | |
The token must have the listFiles capability. Returning more than 1,000 entries in one call counts as multiple class C transactions. Acts onfile version Permission (capability) listFilesVersionAvailable since the API’s base version Webhook eventNone Rate limit1 class C transaction per 1,000 entries returned SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_get_file_info | Get the metadata of a single file by its file ID. | read | readFiles | Current | |
The token must have the readFiles capability. Acts onfile Permission (capability) readFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /file/{bucketName}/{fileName} | Download a file by its bucket name and file name. | read | readFiles | Current | |
The token must have the readFiles capability for a private bucket. Served from the download host, not the main API host. A public bucket needs no token. Acts onfile Permission (capability) readFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_download_file_by_id | Download a file by its file ID. | read | readFiles | Current | |
The token must have the readFiles capability for a private bucket. Served from the download host. Acts onfile Permission (capability) readFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_copy_file | Copy a full file or a byte range into a new destination file. | write | writeFiles | Current | |
The token must have the writeFiles capability, and readFiles if the source bucket is private. Acts onfile Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook event object_created_copyRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_hide_file | Hide a file so a download by name no longer finds it, keeping earlier versions. | write | writeFiles | Current | |
The token must have the writeFiles capability. Acts onfile Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook event hide_marker_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_delete_file_version | Delete one version of a file by its name and file ID. | write | deleteFiles | Current | |
The token must have the deleteFiles capability. An older version may become current when the latest is removed. Acts onfile version Permission (capability) deleteFilesVersionAvailable since the API’s base version Webhook event object_deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Large filesStart a multi-part upload, upload each part, then finish or cancel it.7 | ||||||
| POST | /b2api/v3/b2_start_large_file | Begin a multi-part upload for a large file, returning the file ID for its parts. | write | writeFiles | Current | |
The token must have the writeFiles capability. Acts onlarge file Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_get_upload_part_url | Get a URL used to upload the parts of a large file. | write | writeFiles | Current | |
The token must have the writeFiles capability. The returned URL points at a specific pod and is used by b2_upload_part. Acts onupload URL Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_upload_part | Upload one part of a large file, numbered from 1 to 10,000. | write | writeFiles | Current | |
Sent to the upload URL from b2_get_upload_part_url, not the main API host, with that call's writeFiles authorization. Acts onlarge file part Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_finish_large_file | Combine the uploaded parts into a single complete file. | write | writeFiles | Current | |
The token must have the writeFiles capability. Acts onlarge file Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook event object_created_multipartRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_cancel_large_file | Cancel an in-progress large file upload and delete the parts already sent. | write | writeFiles | Current | |
The token must have the writeFiles capability. Acts onlarge file Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_list_parts | List the parts already uploaded for an unfinished large file, up to 1,000 per call. | read | writeFiles | Current | |
The token must have the writeFiles capability, the same one that uploads the parts, not listFiles. Acts onlarge file part Permission (capability) writeFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_list_unfinished_large_files | List large file uploads that were started but not yet finished or cancelled. | read | listFiles | Current | |
The token must have the listFiles capability. Acts onlarge file Permission (capability) listFilesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Application keysCreate, list, and delete the application keys that grant access to the account.3 | ||||||
| POST | /b2api/v3/b2_create_key | Create an application key with chosen capabilities, an optional bucket restriction, and an optional name prefix. | write | writeKeys | Current | |
The token must have the writeKeys capability. A new key can carry no more capabilities than the key that created it. The secret key is returned only once. Acts onapplication key Permission (capability) writeKeysVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /b2api/v3/b2_list_keys | List the application keys associated with an account. | read | listKeys | Current | |
The token must have the listKeys capability. The list never includes the secret part of a key. Acts onapplication key Permission (capability) listKeysVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_delete_key | Delete an application key by its key ID. | write | deleteKeys | Current | |
The token must have the deleteKeys capability. Acts onapplication key Permission (capability) deleteKeysVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Event notificationsRead and set the rules that send a webhook when files change in a bucket.2 | ||||||
| POST | /b2api/v3/b2_set_bucket_notification_rules | Set the event notification rules on a bucket, each naming the events to watch and a webhook URL. | write | writeBucketNotifications | Current | |
The token must have the writeBucketNotifications capability. A rule can set an HMAC signing secret so the receiver can verify each webhook. Acts onnotification rule Permission (capability) writeBucketNotificationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /b2api/v3/b2_get_bucket_notification_rules | Read the event notification rules currently set on a bucket. | read | readBucketNotifications | Current | |
The token must have the readBucketNotifications capability. The response includes whether a rule is suspended and why. Acts onnotification rule Permission (capability) readBucketNotificationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Backblaze B2 can notify an app or AI agent when something happens in a bucket, like a file being uploaded, deleted, or hidden. It sends an HTTP POST with a JSON payload to a webhook URL set on a notification rule, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
b2:ObjectCreated:Upload | Fires when an object is created by uploading a file with b2_upload_file. | /b2api/v3/b2_upload_file |
b2:ObjectCreated:MultipartUpload | Fires when an object is created by finishing a large, multi-part upload. | /b2api/v3/b2_finish_large_file |
b2:ObjectCreated:Copy | Fires when an object is created by a server-side copy with b2_copy_file. | /b2api/v3/b2_copy_file |
b2:ObjectDeleted:Delete | Fires when a file version is deleted by a user with b2_delete_file_version. | /b2api/v3/b2_delete_file_version |
b2:HideMarkerCreated:Hide | Fires when a hide marker is created by a user with b2_hide_file. | /b2api/v3/b2_hide_file |
Backblaze limits how fast an app or AI agent can call on a per-account basis, and large transfers are split into parts rather than sent in one request.
Backblaze states that B2 may limit API requests on a per-account basis, returning HTTP 429 too_many_requests when a limit is hit, with a Retry-After header to honor where present. A 503 service_unavailable points at a busy upload pod rather than the account, and the documented fix is to retry with exponential backoff, requesting a fresh upload URL from b2_get_upload_url before retrying an upload. Backblaze does not publish a fixed requests-per-second number for the Native API. A separate billing model counts each call as a class A, B, or C transaction, and a single list call that returns more than 1,000 files is billed as several class C transactions.
List calls page forward with a continuation token in the response. b2_list_file_names and b2_list_file_versions return up to maxFileCount entries, which defaults to 100 and tops out at 10,000, and a nextFileName in the response is passed back as startFileName to fetch the next page, or is null when the list is exhausted. The large-file and key list calls follow the same next-token pattern with their own fields.
A single b2_upload_file request uploads a file up to 5 GB. A larger file uses the large-file flow: b2_start_large_file, then b2_upload_part for each part numbered 1 to 10,000, then b2_finish_large_file. A list call returns at most 1,000 entries per billed transaction, even when maxFileCount is set higher.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request had bad parameters, like an invalid bucket name or a missing field. The code names the specific problem. | Read the message, fix the named parameter, and resend. The request is not retryable as-is. |
| 401 | unauthorized / bad_auth_token / expired_auth_token | Authentication failed: the application key is wrong, the authorization token is invalid, or the token has expired. | Call b2_authorize_account again to get a fresh token, then retry. An expired_auth_token is the normal signal to re-authorize. |
| 403 | transaction_cap_exceeded / access_denied | The account hit a usage cap, or the key lacks the capability or bucket access the request needs. | Raise the cap in the account, or grant the missing capability or bucket on the key, then retry. |
| 404 | not_found | The requested bucket, file, or key does not exist or is not visible to this key. | Confirm the identifier and that the key can reach the resource, then retry. |
| 408 | request_timeout | The request took too long to complete on the server side. | Retry the request, splitting a large upload into parts if needed. |
| 429 | too_many_requests | B2 is limiting requests on a per-account basis because too many arrived too quickly. | Honor the Retry-After header when present, then retry with backoff and a lower request rate. |
| 500 | internal_error | An error on Backblaze's side while handling the request. | Retry with exponential backoff. For an upload, get a fresh upload URL first. |
| 503 | service_unavailable | The service is temporarily unavailable, often a busy upload pod. | Retry with exponential backoff, and for an upload request a new upload URL from b2_get_upload_url first. |
Backblaze versions the B2 Native API by a number in the request path. v3 reworked how authorization reports access across multiple API suites, and the newer v4 added application keys that span several buckets.
v4 added the ability to create application keys that grant access to a chosen group of buckets within an account, with an optional file prefix restriction, through a new bucketIds field on b2_create_key. The b2_authorize_account response moved bucket restriction details into an allowed object holding buckets, capabilities, and namePrefix. A v4 key with no bucket restriction still works with v3 b2_authorize_account. It was released on 29 April 2025.
v3 reworked b2_authorize_account to report access across multiple API suites, including the B2 Storage and Partner APIs, grouping the returned information by suite rather than as a single flat response. It was released on 23 September 2021.
v2 cleaned up the application key behavior introduced in 2018 for restricted keys. Later additive updates on v2 added server-side encryption fields in March 2021 and Object Lock fields in May 2021. It was released on 13 September 2018.
v1 launched with the B2 Cloud Storage service. Later additive updates added application key management in July 2018 and adjusted behavior for restricted keys in August 2018. It was released on 22 September 2015.
An integration can pin a version in the path and move up on a schedule that suits it.
B2 Native API version history ↗Bollard AI sits between a team's AI agents and Backblaze B2. Grant each agent exactly the access it needs, read or write, bucket by bucket, and every call is checked and logged.