openapi: 3.0.3
info:
  title: Filebase IPFS Pinning Service Buckets Objects 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: Objects
  description: Object upload, download, copy, delete, and metadata
paths:
  /{bucket}:
    parameters:
    - $ref: '#/components/parameters/bucket'
    get:
      operationId: listObjects
      summary: List objects in a bucket
      description: Returns some or all (up to 1,000) of the objects in a bucket. Use list-type=2 for ListObjectsV2.
      tags:
      - Objects
      parameters:
      - name: prefix
        in: query
        description: Limits the response to keys that begin with the specified prefix
        schema:
          type: string
      - name: delimiter
        in: query
        description: A delimiter is a character you use to group keys
        schema:
          type: string
      - name: marker
        in: query
        description: Specifies the key to start with when listing objects
        schema:
          type: string
      - name: max-keys
        in: query
        description: Sets the maximum number of keys returned (default 1000)
        schema:
          type: integer
          maximum: 1000
          default: 1000
      - name: list-type
        in: query
        description: Version 2 of list objects request (set to 2)
        schema:
          type: integer
          enum:
          - 2
      - name: continuation-token
        in: query
        description: Indicates Amazon S3 that the list is being continued with a token (V2)
        schema:
          type: string
      responses:
        '200':
          description: Successfully listed objects
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /{bucket}/{key}:
    parameters:
    - $ref: '#/components/parameters/bucket'
    - $ref: '#/components/parameters/key'
    copy:
      operationId: copyObject
      summary: Copy an object
      description: Creates a copy of an object that is already stored in Filebase.
      tags:
      - Objects
      parameters:
      - name: x-amz-copy-source
        in: header
        required: true
        description: Specifies the source bucket and key name (bucket/key)
        schema:
          type: string
      responses:
        '200':
          description: Object copied successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CopyObjectResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putObject
      summary: Upload an object
      description: Adds an object to a bucket. Objects are automatically pinned to IPFS for IPFS-backed buckets and receive 3x geo-redundant replication. The CID is returned in the x-amz-meta-cid response header.
      tags:
      - Objects
      parameters:
      - name: x-amz-meta-cid
        in: header
        description: IPFS CID of the uploaded object (response header)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Object uploaded successfully
          headers:
            ETag:
              description: Entity tag (MD5 hash) of the uploaded object
              schema:
                type: string
            x-amz-meta-cid:
              description: IPFS CID of the uploaded object
              schema:
                type: string
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      operationId: getObject
      summary: Download an object
      description: Retrieves an object from Filebase. Returns the object data.
      tags:
      - Objects
      parameters:
      - name: Range
        in: header
        description: Downloads the specified range bytes of an object
        schema:
          type: string
      responses:
        '200':
          description: Object content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Type:
              schema:
                type: string
            ETag:
              schema:
                type: string
            x-amz-meta-cid:
              description: IPFS CID of the object
              schema:
                type: string
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    head:
      operationId: headObject
      summary: Get object metadata
      description: Retrieves metadata from an object without returning the object itself.
      tags:
      - Objects
      responses:
        '200':
          description: Object metadata
          headers:
            Content-Type:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
            ETag:
              schema:
                type: string
            x-amz-meta-cid:
              description: IPFS CID of the object
              schema:
                type: string
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteObject
      summary: Delete an object
      description: Removes an object from a bucket.
      tags:
      - Objects
      responses:
        '204':
          description: Object deleted successfully
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    bucket:
      name: bucket
      in: path
      required: true
      description: Name of the bucket
      schema:
        type: string
    key:
      name: key
      in: path
      required: true
      description: Object key (file path within the bucket)
      schema:
        type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access denied
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CopyObjectResult:
      type: object
      xml:
        name: CopyObjectResult
      properties:
        LastModified:
          type: string
          format: date-time
        ETag:
          type: string
    ListBucketResult:
      type: object
      xml:
        name: ListBucketResult
      properties:
        Name:
          type: string
          description: Bucket name
        Prefix:
          type: string
          description: Limits the response to keys beginning with the specified prefix
        MaxKeys:
          type: integer
          description: Maximum number of keys returned
        IsTruncated:
          type: boolean
          description: Whether the results are truncated
        Contents:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
              LastModified:
                type: string
                format: date-time
              ETag:
                type: string
              Size:
                type: integer
                format: int64
              StorageClass:
                type: string
    Error:
      type: object
      xml:
        name: Error
      properties:
        Code:
          type: string
        Message:
          type: string
        Resource:
          type: string
        RequestId:
          type: string
  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