openapi: 3.0.3
info:
  title: Backblaze B2 Native Application Keys Files API
  description: The Backblaze B2 Native API provides programmatic access to Backblaze B2 Cloud Storage. It covers account authorization, bucket management, file upload and download, lifecycle rules, application key management, large file handling, replication, and event notifications. The API uses HTTPS with JSON request and response bodies. Authentication is performed via the b2_authorize_account endpoint which returns an authorization token used for subsequent calls.
  version: v4
  x-generated-from: documentation
  contact:
    name: Backblaze Developer Support
    url: https://www.backblaze.com/docs
  license:
    name: Proprietary
    url: https://www.backblaze.com/company/terms-of-service
servers:
- url: https://api.backblazeb2.com
  description: Backblaze B2 API (cluster-specific URL returned by b2_authorize_account)
security:
- ApplicationKeyAuth: []
tags:
- name: Files
  description: File upload, download, listing, deletion, and metadata
paths:
  /b2api/v4/b2_get_upload_url:
    post:
      operationId: getUploadUrl
      summary: Backblaze B2 Native API Get Upload URL
      description: Gets a URL for uploading a single file to a bucket. The URL returned is specific to the bucket and can only be used to upload to that bucket.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUploadUrlRequest'
            examples:
              GetUploadUrlRequestExample:
                summary: Default getUploadUrl request
                x-microcks-default: true
                value:
                  bucketId: e73ede9969c64355ef8b
      responses:
        '200':
          description: Upload URL details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUploadUrlResponse'
              examples:
                GetUploadUrl200Example:
                  summary: Default getUploadUrl 200 response
                  x-microcks-default: true
                  value:
                    bucketId: e73ede9969c64355ef8b
                    uploadUrl: https://pod-000-1005-03.backblaze.com/b2api/v4/b2_upload_file
                    authorizationToken: 3_en0Y0j2f-0r0BVLS8vN9GJTWA-pLEP
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_upload_file:
    post:
      operationId: uploadFile
      summary: Backblaze B2 Native API Upload File
      description: Uploads one file to B2, returning its unique file ID. The file data is the request body. Before calling this function, b2_get_upload_url must be called to get the URL and authorization token.
      tags:
      - Files
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: Upload authorization token from b2_get_upload_url
        example: 3_en0Y0j2f-0r0BVLS8vN9GJTWA-pLEP
      - name: X-Bz-File-Name
        in: header
        required: true
        schema:
          type: string
        description: URL-encoded name of the file
        example: photos%2Fimage.jpg
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: MIME type of the file
        example: image/jpeg
      - name: Content-Length
        in: header
        required: true
        schema:
          type: integer
        description: Length of the file in bytes
        example: 102400
      - name: X-Bz-Content-Sha1
        in: header
        required: true
        schema:
          type: string
        description: SHA1 checksum of the file content
        example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
              examples:
                UploadFile200Example:
                  summary: Default uploadFile 200 response
                  x-microcks-default: true
                  value:
                    fileId: 4_h4a48fe8875c6214145260818
                    fileName: photos/image.jpg
                    accountId: abc123def456
                    bucketId: e73ede9969c64355ef8b
                    contentLength: 102400
                    contentSha1: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
                    contentType: image/jpeg
                    fileInfo: {}
                    uploadTimestamp: 1660000000000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_download_file_by_id:
    get:
      operationId: downloadFileById
      summary: Backblaze B2 Native API Download File by ID
      description: Downloads one file by its file ID. Can be used to download a specific version of a file.
      tags:
      - Files
      parameters:
      - name: fileId
        in: query
        required: true
        schema:
          type: string
        description: The unique file ID to download
        example: 4_h4a48fe8875c6214145260818
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_download_file_by_name/{bucketName}/{fileName}:
    get:
      operationId: downloadFileByName
      summary: Backblaze B2 Native API Download File by Name
      description: Downloads one file from a public or private bucket by name.
      tags:
      - Files
      parameters:
      - name: bucketName
        in: path
        required: true
        schema:
          type: string
        description: Name of the bucket containing the file
        example: my-media-bucket
      - name: fileName
        in: path
        required: true
        schema:
          type: string
        description: Full name of the file including any prefix
        example: photos/image.jpg
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_get_file_info:
    post:
      operationId: getFileInfo
      summary: Backblaze B2 Native API Get File Info
      description: Gets information about one file stored in B2.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFileInfoRequest'
            examples:
              GetFileInfoRequestExample:
                summary: Default getFileInfo request
                x-microcks-default: true
                value:
                  fileId: 4_h4a48fe8875c6214145260818
      responses:
        '200':
          description: File information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
              examples:
                GetFileInfo200Example:
                  summary: Default getFileInfo 200 response
                  x-microcks-default: true
                  value:
                    fileId: 4_h4a48fe8875c6214145260818
                    fileName: photos/image.jpg
                    accountId: abc123def456
                    bucketId: e73ede9969c64355ef8b
                    contentLength: 102400
                    contentSha1: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
                    contentType: image/jpeg
                    fileInfo: {}
                    uploadTimestamp: 1660000000000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_delete_file_version:
    post:
      operationId: deleteFileVersion
      summary: Backblaze B2 Native API Delete File Version
      description: Deletes one version of a file from B2. If the version you delete is the latest version, and there are older versions, then the most recent older version will become the current version of the file.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteFileVersionRequest'
            examples:
              DeleteFileVersionRequestExample:
                summary: Default deleteFileVersion request
                x-microcks-default: true
                value:
                  fileName: photos/image.jpg
                  fileId: 4_h4a48fe8875c6214145260818
      responses:
        '200':
          description: File version deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFileVersionResponse'
              examples:
                DeleteFileVersion200Example:
                  summary: Default deleteFileVersion 200 response
                  x-microcks-default: true
                  value:
                    fileId: 4_h4a48fe8875c6214145260818
                    fileName: photos/image.jpg
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_list_file_names:
    post:
      operationId: listFileNames
      summary: Backblaze B2 Native API List File Names
      description: Lists the names of all files in a bucket, starting at a given name. Returns at most 1000 file names, but it can be set to return fewer.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListFileNamesRequest'
            examples:
              ListFileNamesRequestExample:
                summary: Default listFileNames request
                x-microcks-default: true
                value:
                  bucketId: e73ede9969c64355ef8b
                  maxFileCount: 100
      responses:
        '200':
          description: List of file names
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFileNamesResponse'
              examples:
                ListFileNames200Example:
                  summary: Default listFileNames 200 response
                  x-microcks-default: true
                  value:
                    files:
                    - fileId: 4_h4a48fe8875c6214145260818
                      fileName: photos/image.jpg
                      contentLength: 102400
                      contentType: image/jpeg
                      uploadTimestamp: 1660000000000
                    nextFileName: null
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_list_file_versions:
    post:
      operationId: listFileVersions
      summary: Backblaze B2 Native API List File Versions
      description: Lists all of the versions of all of the files contained in one bucket, in alphabetical order by file name, and by reverse of date/time uploaded for versions of files with the same name.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListFileVersionsRequest'
            examples:
              ListFileVersionsRequestExample:
                summary: Default listFileVersions request
                x-microcks-default: true
                value:
                  bucketId: e73ede9969c64355ef8b
      responses:
        '200':
          description: List of file versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFileVersionsResponse'
              examples:
                ListFileVersions200Example:
                  summary: Default listFileVersions 200 response
                  x-microcks-default: true
                  value:
                    files:
                    - fileId: 4_h4a48fe8875c6214145260818
                      fileName: photos/image.jpg
                      action: upload
                      contentLength: 102400
                      contentType: image/jpeg
                      uploadTimestamp: 1660000000000
                    nextFileName: null
                    nextFileId: null
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_copy_file:
    post:
      operationId: copyFile
      summary: Backblaze B2 Native API Copy File
      description: Creates a new file by copying from an existing file. It copies the source file's contents and optionally overrides some of the source file's metadata.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyFileRequest'
            examples:
              CopyFileRequestExample:
                summary: Default copyFile request
                x-microcks-default: true
                value:
                  sourceFileId: 4_h4a48fe8875c6214145260818
                  fileName: photos/image-copy.jpg
      responses:
        '200':
          description: File copied successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
              examples:
                CopyFile200Example:
                  summary: Default copyFile 200 response
                  x-microcks-default: true
                  value:
                    fileId: 4_z71c4725f4f4a14a14a14a14a
                    fileName: photos/image-copy.jpg
                    accountId: abc123def456
                    bucketId: e73ede9969c64355ef8b
                    contentLength: 102400
                    contentSha1: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
                    contentType: image/jpeg
                    fileInfo: {}
                    uploadTimestamp: 1660500000000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /b2api/v4/b2_hide_file:
    post:
      operationId: hideFile
      summary: Backblaze B2 Native API Hide File
      description: Hides a file so that downloading by name will not find the file, but previous versions of the file are still stored. Can be used to effectively delete a file if versioning is enabled.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HideFileRequest'
            examples:
              HideFileRequestExample:
                summary: Default hideFile request
                x-microcks-default: true
                value:
                  bucketId: e73ede9969c64355ef8b
                  fileName: photos/image.jpg
      responses:
        '200':
          description: File hidden successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
              examples:
                HideFile200Example:
                  summary: Default hideFile 200 response
                  x-microcks-default: true
                  value:
                    fileId: 4_h4a48fe8875c6214145260818
                    fileName: photos/image.jpg
                    action: hide
                    contentLength: 0
                    uploadTimestamp: 1660500000000
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    GetFileInfoRequest:
      title: GetFileInfoRequest
      type: object
      required:
      - fileId
      properties:
        fileId:
          type: string
          description: The ID of the file
          example: 4_h4a48fe8875c6214145260818
    CopyFileRequest:
      title: CopyFileRequest
      type: object
      required:
      - sourceFileId
      - fileName
      properties:
        sourceFileId:
          type: string
          description: The ID of the file to copy
          example: 4_h4a48fe8875c6214145260818
        fileName:
          type: string
          description: The name for the new file
          example: photos/image-copy.jpg
        destinationBucketId:
          type: string
          description: Bucket ID to copy to (defaults to source bucket)
        range:
          type: string
          description: Byte range to copy
        metadataDirective:
          type: string
          enum:
          - COPY
          - REPLACE
          description: Whether to copy or replace metadata
    ListFileVersionsResponse:
      title: ListFileVersionsResponse
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileInfo'
        nextFileName:
          type: string
          nullable: true
        nextFileId:
          type: string
          nullable: true
    DeleteFileVersionResponse:
      title: DeleteFileVersionResponse
      type: object
      properties:
        fileId:
          type: string
          example: 4_h4a48fe8875c6214145260818
        fileName:
          type: string
          example: photos/image.jpg
    GetUploadUrlRequest:
      title: GetUploadUrlRequest
      type: object
      required:
      - bucketId
      properties:
        bucketId:
          type: string
          description: The ID of the bucket to upload to
          example: e73ede9969c64355ef8b
    HideFileRequest:
      title: HideFileRequest
      type: object
      required:
      - bucketId
      - fileName
      properties:
        bucketId:
          type: string
          description: The bucket containing the file
          example: e73ede9969c64355ef8b
        fileName:
          type: string
          description: The name of the file to hide
          example: photos/image.jpg
    ListFileNamesRequest:
      title: ListFileNamesRequest
      type: object
      required:
      - bucketId
      properties:
        bucketId:
          type: string
          description: The bucket to list
          example: e73ede9969c64355ef8b
        startFileName:
          type: string
          description: Start listing from this file name
        maxFileCount:
          type: integer
          description: Maximum number of files to return (1-10000)
          example: 100
        prefix:
          type: string
          description: Prefix to filter file names
        delimiter:
          type: string
          description: Delimiter used for virtual folder simulation
    GetUploadUrlResponse:
      title: GetUploadUrlResponse
      type: object
      properties:
        bucketId:
          type: string
          example: e73ede9969c64355ef8b
        uploadUrl:
          type: string
          example: https://pod-000-1005-03.backblaze.com/b2api/v4/b2_upload_file
        authorizationToken:
          type: string
          example: 3_en0Y0j2f-0r0BVLS8vN9GJTWA-pLEP
    ListFileVersionsRequest:
      title: ListFileVersionsRequest
      type: object
      required:
      - bucketId
      properties:
        bucketId:
          type: string
          description: The bucket to list
          example: e73ede9969c64355ef8b
        startFileName:
          type: string
        startFileId:
          type: string
        maxFileCount:
          type: integer
          example: 100
        prefix:
          type: string
        delimiter:
          type: string
    FileInfo:
      title: FileInfo
      type: object
      description: Information about a stored file
      properties:
        fileId:
          type: string
          description: The unique identifier for this version of this file
          example: 4_h4a48fe8875c6214145260818
        fileName:
          type: string
          description: The name of the file
          example: photos/image.jpg
        accountId:
          type: string
          description: The account that owns the file
          example: abc123def456
        bucketId:
          type: string
          description: The bucket that the file is in
          example: e73ede9969c64355ef8b
        contentLength:
          type: integer
          description: The size of the file in bytes
          example: 102400
        contentSha1:
          type: string
          description: The SHA1 checksum of the bytes in the file
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
        contentType:
          type: string
          description: The MIME type of the file
          example: image/jpeg
        fileInfo:
          type: object
          description: Custom information about the file
        action:
          type: string
          enum:
          - upload
          - hide
          - start
          - copy
          description: The action that created this file version
          example: upload
        uploadTimestamp:
          type: integer
          description: Milliseconds since midnight, January 1, 1970 UTC
          example: 1660000000000
    ListFileNamesResponse:
      title: ListFileNamesResponse
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileInfo'
        nextFileName:
          type: string
          nullable: true
          description: Next file name for pagination
    DeleteFileVersionRequest:
      title: DeleteFileVersionRequest
      type: object
      required:
      - fileName
      - fileId
      properties:
        fileName:
          type: string
          description: The name of the file
          example: photos/image.jpg
        fileId:
          type: string
          description: The ID of the file version to delete
          example: 4_h4a48fe8875c6214145260818
        bypassGovernance:
          type: boolean
          description: Set to true to bypass object lock governance mode
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard B2 error response
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 401
        code:
          type: string
          description: A single-identifier code that identifies the error
          example: unauthorized
        message:
          type: string
          description: A human-readable message describing the error
          example: Authorization token not valid
  securitySchemes:
    ApplicationKeyAuth:
      type: http
      scheme: bearer
      description: Authorization token obtained from b2_authorize_account
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using applicationKeyId as username and applicationKey as password