openapi: 3.0.3
info:
  title: Filebase IPFS Pinning Service Buckets Usage API
  description: The Filebase IPFS Pinning Service API implements the vendor-neutral IPFS Pinning Service specification. Per-bucket Bearer tokens authenticate requests to list, add, retrieve, replace, and delete pinned objects by CID. Supports metadata tagging and filtering by CID, name, status, and timestamps. Compatible with IPFS Desktop, the IPFS CLI, and any third-party tool supporting the pinning service standard. Rate limit is 100 requests per second.
  version: '1.0'
  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/
servers:
- url: https://api.filebase.io/v1/ipfs
  description: Filebase IPFS Pinning Service API
security:
- BearerAuth: []
tags:
- name: Usage
  description: Account-level usage and bandwidth metrics
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'
components:
  responses:
    Unauthorized:
      description: Authentication failed
      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'
  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
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Per-bucket Bearer token for authentication
externalDocs:
  description: Filebase IPFS Pinning Service API Documentation
  url: https://filebase.com/docs/ipfs/pinning-service-api