openapi: 3.0.3
info:
  title: Filebase Platform API
  description: >-
    The Filebase Platform API provides account-level operations including total
    storage usage, 24-hour trailing bandwidth metrics, and per-bucket storage
    consumption. Authentication uses HTTP Basic auth with base64-encoded access
    key and secret key pairs as a Bearer token. Rate limit is 500 requests per
    second per account.
  version: v1
  contact:
    name: Filebase Support
    url: https://filebase.com/
    email: support@filebase.com
  termsOfService: https://filebase.com/terms/
  license:
    name: Proprietary
    url: https://filebase.com/terms/
externalDocs:
  description: Filebase Platform API Documentation
  url: https://filebase.com/docs/platform-api/overview
servers:
  - url: https://api.filebase.io
    description: Filebase Platform API
security:
  - BearerAuth: []
paths:
  /v1/usage:
    get:
      operationId: getUsage
      summary: Get account storage usage
      description: >-
        Returns total storage usage in bytes for the account across all buckets.
      tags:
        - Usage
      responses:
        "200":
          description: Account usage statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/usage/bandwidth:
    get:
      operationId: getBandwidthUsage
      summary: Get 24-hour trailing bandwidth metrics
      description: >-
        Returns bandwidth usage over the trailing 24-hour period for the account.
      tags:
        - Usage
      responses:
        "200":
          description: Bandwidth usage statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BandwidthResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/buckets:
    get:
      operationId: listBuckets
      summary: List buckets with storage consumption
      description: >-
        Returns a list of all buckets with per-bucket storage consumption metrics.
      tags:
        - Buckets
      responses:
        "200":
          description: List of buckets with storage usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BucketListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/buckets/{bucketName}/usage:
    get:
      operationId: getBucketUsage
      summary: Get per-bucket storage consumption
      description: >-
        Returns storage consumption metrics for the specified bucket.
      tags:
        - Buckets
      parameters:
        - name: bucketName
          in: path
          required: true
          description: The name of the bucket
          schema:
            type: string
      responses:
        "200":
          description: Bucket storage usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BucketUsageResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        HTTP Basic authentication encoded as base64(accessKey:secretKey) passed
        as a Bearer token in the Authorization header.
  schemas:
    UsageResponse:
      type: object
      properties:
        storage_bytes:
          type: integer
          format: int64
          description: Total storage used in bytes
        object_count:
          type: integer
          format: int64
          description: Total number of objects stored
        bucket_count:
          type: integer
          description: Total number of buckets
    BandwidthResponse:
      type: object
      properties:
        bandwidth_bytes:
          type: integer
          format: int64
          description: Bandwidth consumed in the trailing 24 hours (bytes)
        period_start:
          type: string
          format: date-time
          description: Start of the measurement period
        period_end:
          type: string
          format: date-time
          description: End of the measurement period
    BucketListResponse:
      type: object
      properties:
        buckets:
          type: array
          items:
            $ref: "#/components/schemas/BucketUsageResponse"
    BucketUsageResponse:
      type: object
      properties:
        name:
          type: string
          description: Bucket name
        storage_bytes:
          type: integer
          format: int64
          description: Storage used by this bucket in bytes
        object_count:
          type: integer
          format: int64
          description: Number of objects in this bucket
        region:
          type: string
          description: Bucket region (always us-east-1 for Filebase)
        created_at:
          type: string
          format: date-time
          description: Bucket creation timestamp
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooManyRequests:
      description: Rate limit exceeded (500 req/s per account)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
tags:
  - name: Usage
    description: Account-level usage and bandwidth metrics
  - name: Buckets
    description: Per-bucket storage consumption