openapi.json

{
  "components": {
    "schemas": {
      "DailyUploadCount": {
        "description": "One day's upload count, for the dashboard activity chart.",
        "properties": {
          "date": {
            "title": "Date",
            "type": "string"
          },
          "uploads": {
            "title": "Uploads",
            "type": "integer"
          }
        },
        "required": [
          "date",
          "uploads"
        ],
        "title": "DailyUploadCount",
        "type": "object"
      },
      "DeleteFileResponse": {
        "description": "Acknowledgement that one object was removed from the bucket.",
        "properties": {
          "deleted": {
            "title": "Deleted",
            "type": "boolean"
          },
          "key": {
            "title": "Key",
            "type": "string"
          }
        },
        "required": [
          "deleted",
          "key"
        ],
        "title": "DeleteFileResponse",
        "type": "object"
      },
      "FileMetadata": {
        "description": "One stored object as the file list and the by-key metadata route see it.",
        "properties": {
          "content_type": {
            "title": "Content Type",
            "type": "string"
          },
          "filename": {
            "title": "Filename",
            "type": "string"
          },
          "folder": {
            "title": "Folder",
            "type": "string"
          },
          "key": {
            "title": "Key",
            "type": "string"
          },
          "size_bytes": {
            "title": "Size Bytes",
            "type": "integer"
          },
          "size_human": {
            "title": "Size Human",
            "type": "string"
          },
          "uploaded_at": {
            "format": "date-time",
            "title": "Uploaded At",
            "type": "string"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Public object URL, set only when B2_PUBLIC_URL_BASE is configured and the bucket is public. Null otherwise \u2014 the UI asks for a presigned URL instead.",
            "title": "Url"
          }
        },
        "required": [
          "key",
          "filename",
          "folder",
          "size_bytes",
          "size_human",
          "content_type",
          "uploaded_at",
          "url"
        ],
        "title": "FileMetadata",
        "type": "object"
      },
      "FileMetadataDetail": {
        "description": "Rich metadata recomputed on demand by re-reading the stored object.",
        "properties": {
          "bitrate": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Audio/video: bits per second.",
            "title": "Bitrate"
          },
          "codec": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Audio/video: codec name.",
            "title": "Codec"
          },
          "duration_seconds": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Audio/video: duration in seconds.",
            "title": "Duration Seconds"
          },
          "exif": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Image-specific: EXIF tags, values stringified. Null for non-images or when no EXIF block was present.",
            "title": "Exif"
          },
          "extension": {
            "title": "Extension",
            "type": "string"
          },
          "filename": {
            "title": "Filename",
            "type": "string"
          },
          "image_height": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Image-specific: pixel height. Null for non-images.",
            "title": "Image Height"
          },
          "image_width": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Image-specific: pixel width. Null for non-images.",
            "title": "Image Width"
          },
          "md5": {
            "title": "Md5",
            "type": "string"
          },
          "metadata_warning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Set when a format-specific extractor was skipped or failed (e.g. an image above Pillow's decompression-bomb limit). The core fields are always exact, so the UI shows this instead of silently dropping the Image / PDF section.",
            "title": "Metadata Warning"
          },
          "mime_type": {
            "title": "Mime Type",
            "type": "string"
          },
          "pdf_author": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "PDF-specific: author.",
            "title": "Pdf Author"
          },
          "pdf_pages": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "PDF-specific: page count. Null for non-PDFs.",
            "title": "Pdf Pages"
          },
          "pdf_title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "PDF-specific: title.",
            "title": "Pdf Title"
          },
          "sha256": {
            "title": "Sha256",
            "type": "string"
          },
          "size_bytes": {
            "title": "Size Bytes",
            "type": "integer"
          },
          "size_human": {
            "title": "Size Human",
            "type": "string"
          },
          "uploaded_at": {
            "format": "date-time",
            "title": "Uploaded At",
            "type": "string"
          }
        },
        "required": [
          "filename",
          "size_bytes",
          "size_human",
          "mime_type",
          "extension",
          "md5",
          "sha256",
          "uploaded_at",
          "metadata_warning",
          "image_width",
          "image_height",
          "exif",
          "pdf_pages",
          "pdf_author",
          "pdf_title",
          "duration_seconds",
          "codec",
          "bitrate"
        ],
        "title": "FileMetadataDetail",
        "type": "object"
      },
      "FileUploadResponse": {
        "description": "The stored object as `POST /upload/verify` reports it back.",
        "properties": {
          "content_type": {
            "title": "Content Type",
            "type": "string"
          },
          "filename": {
            "title": "Filename",
            "type": "string"
          },
          "key": {
            "title": "Key",
            "type": "string"
          },
          "metadata": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FileMetadataDetail"
              },
              {
                "type": "null"
              }
            ],
            "description": "Rich metadata, when extraction succeeded for this type."
          },
          "size_bytes": {
            "title": "Size Bytes",
            "type": "integer"
          },
          "size_human": {
            "title": "Size Human",
            "type": "string"
          },
          "uploaded_at": {
            "format": "date-time",
            "title": "Uploaded At",
            "type": "string"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Public object URL when the bucket is public, else null.",
            "title": "Url"
          }
        },
        "required": [
          "key",
          "filename",
          "size_bytes",
          "size_human",
          "content_type",
          "uploaded_at",
          "url",
          "metadata"
        ],
        "title": "FileUploadResponse",
        "type": "object"
      },
      "FileUrlResponse": {
        "description": "A short-lived presigned GET for downloading or previewing one object.",
        "properties": {
          "url": {
            "description": "Presigned GET URL. Download URLs force an attachment disposition; preview URLs are signed inline so a PDF renders in place.",
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "title": "FileUrlResponse",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "HealthStatus": {
        "description": "Liveness plus B2 reachability.\n\nThe route answers HTTP 200 even when B2 is unreachable, so a caller must\nread `b2_connected` rather than trusting the status code.",
        "properties": {
          "b2_connected": {
            "description": "True when the bucket answered a cheap head request.",
            "title": "B2 Connected",
            "type": "boolean"
          },
          "status": {
            "description": "\"healthy\" when B2 answered, else \"degraded\".",
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "status",
          "b2_connected"
        ],
        "title": "HealthStatus",
        "type": "object"
      },
      "PresignUploadRequest": {
        "description": "What the browser declares before uploading directly to B2.",
        "properties": {
          "content_type": {
            "title": "Content Type",
            "type": "string"
          },
          "filename": {
            "title": "Filename",
            "type": "string"
          },
          "size_bytes": {
            "title": "Size Bytes",
            "type": "integer"
          }
        },
        "required": [
          "filename",
          "content_type",
          "size_bytes"
        ],
        "title": "PresignUploadRequest",
        "type": "object"
      },
      "PresignUploadResponse": {
        "description": "A short-lived presigned PUT the browser uploads to, plus the exact\nheaders it must send. `Content-Length` and `content-type` are signed into\nthe URL, so B2 rejects a body of any other size or type.",
        "properties": {
          "content_type": {
            "title": "Content Type",
            "type": "string"
          },
          "expires_in": {
            "title": "Expires In",
            "type": "integer"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Signed into the URL, so the browser must send them verbatim \u2014 B2 answers a mismatch with 403.",
            "title": "Headers",
            "type": "object"
          },
          "key": {
            "title": "Key",
            "type": "string"
          },
          "method": {
            "title": "Method",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "key",
          "url",
          "method",
          "content_type",
          "headers",
          "expires_in"
        ],
        "title": "PresignUploadResponse",
        "type": "object"
      },
      "UploadStats": {
        "description": "Aggregate bucket figures behind the dashboard stat cards.",
        "properties": {
          "total_downloads": {
            "title": "Total Downloads",
            "type": "integer"
          },
          "total_files": {
            "title": "Total Files",
            "type": "integer"
          },
          "total_size_bytes": {
            "title": "Total Size Bytes",
            "type": "integer"
          },
          "total_size_human": {
            "title": "Total Size Human",
            "type": "string"
          },
          "uploads_today": {
            "title": "Uploads Today",
            "type": "integer"
          }
        },
        "required": [
          "total_files",
          "total_size_bytes",
          "total_size_human",
          "uploads_today",
          "total_downloads"
        ],
        "title": "UploadStats",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "VerifyUploadRequest": {
        "description": "Sent after the direct PUT so the API can inspect the stored object.",
        "properties": {
          "key": {
            "title": "Key",
            "type": "string"
          }
        },
        "required": [
          "key"
        ],
        "title": "VerifyUploadRequest",
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Local API for the Vibe Coding Starter Kit template, providing file upload and management backed by Backblaze B2. This contract documents the template's local API, not a hosted public endpoint.",
    "title": "Vibe Coding Starter Kit API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/files": {
      "get": {
        "operationId": "list_files_endpoint_files_get",
        "parameters": [
          {
            "in": "query",
            "name": "prefix",
            "required": false,
            "schema": {
              "default": "",
              "title": "Prefix",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "title": "Limit",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FileMetadata"
                  },
                  "title": "Response List Files Endpoint Files Get",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Files Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files-by-key": {
      "delete": {
        "operationId": "delete_file_by_key_endpoint_files_by_key_delete",
        "parameters": [
          {
            "in": "query",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteFileResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete File By Key Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files-by-key/detail": {
      "get": {
        "description": "Rich metadata (checksums, image/PDF fields) recomputed on demand.\n\nUnlike /metadata (a cheap head_object), this downloads the object to\nre-run extraction, so it is billed at the tighter 'write' rate-limit tier\n(see runtime/ratelimit.py) to bound egress/cost amplification.",
        "operationId": "get_file_detail_by_key_endpoint_files_by_key_detail_get",
        "parameters": [
          {
            "in": "query",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileMetadataDetail"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get File Detail By Key Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files-by-key/download": {
      "get": {
        "operationId": "download_file_by_key_endpoint_files_by_key_download_get",
        "parameters": [
          {
            "in": "query",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUrlResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Download File By Key Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files-by-key/metadata": {
      "get": {
        "operationId": "get_file_by_key_endpoint_files_by_key_metadata_get",
        "parameters": [
          {
            "in": "query",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileMetadata"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get File By Key Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files-by-key/preview": {
      "get": {
        "description": "Return a presigned URL for inline preview. Does not count as a download.",
        "operationId": "preview_file_by_key_endpoint_files_by_key_preview_get",
        "parameters": [
          {
            "in": "query",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUrlResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Preview File By Key Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files/stats": {
      "get": {
        "operationId": "stats_endpoint_files_stats_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadStats"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Stats Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files/stats/activity": {
      "get": {
        "operationId": "upload_activity_endpoint_files_stats_activity_get",
        "parameters": [
          {
            "in": "query",
            "name": "days",
            "required": false,
            "schema": {
              "default": 7,
              "title": "Days",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/DailyUploadCount"
                  },
                  "title": "Response Upload Activity Endpoint Files Stats Activity Get",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Upload Activity Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files/{key}": {
      "delete": {
        "operationId": "delete_file_endpoint_files__key__delete",
        "parameters": [
          {
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteFileResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete File Endpoint",
        "tags": [
          "files"
        ]
      },
      "get": {
        "operationId": "get_file_endpoint_files__key__get",
        "parameters": [
          {
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileMetadata"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get File Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files/{key}/download": {
      "get": {
        "operationId": "download_file_endpoint_files__key__download_get",
        "parameters": [
          {
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUrlResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Download File Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/files/{key}/preview": {
      "get": {
        "description": "Return a presigned URL for inline preview. Does not count as a download.",
        "operationId": "preview_file_endpoint_files__key__preview_get",
        "parameters": [
          {
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "title": "Key",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUrlResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Preview File Endpoint",
        "tags": [
          "files"
        ]
      }
    },
    "/health": {
      "get": {
        "operationId": "health_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Health",
        "tags": [
          "health"
        ]
      }
    },
    "/metrics": {
      "get": {
        "operationId": "metrics_metrics_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Metrics",
        "tags": [
          "metrics"
        ]
      }
    },
    "/upload/presign": {
      "post": {
        "description": "Validate a declared upload and hand back a presigned PUT.\n\nThe browser uploads the bytes straight to B2 with the returned URL, so they\nnever traverse this Function \u2014 that is what lifts Vercel's ~4.5 MB payload\nceiling. Size and content-type are signed into the URL (see the service).",
        "operationId": "presign_upload_upload_presign_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PresignUploadRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PresignUploadResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Presign Upload",
        "tags": [
          "upload"
        ]
      }
    },
    "/upload/verify": {
      "post": {
        "description": "Confirm an object just uploaded directly to B2 is valid and visible.",
        "operationId": "verify_upload_route_upload_verify_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyUploadRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Verify Upload Route",
        "tags": [
          "upload"
        ]
      }
    }
  }
}