openapi: 3.0.3
info:
  title: Filebase IPFS Service Buckets Pinning 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: Pinning
  description: Pin and unpin IPFS objects
paths:
  /api/v0/pin/add:
    post:
      operationId: pinAdd
      summary: Pin an object
      description: Pin objects to local storage by CID.
      tags:
      - Pinning
      parameters:
      - name: arg
        in: query
        required: true
        description: Path to object(s) to be pinned
        schema:
          type: string
      - name: recursive
        in: query
        description: Recursively pin the object linked to by the specified object(s)
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Pinned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinAddResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v0/pin/rm:
    post:
      operationId: pinRemove
      summary: Remove pinned objects
      description: Remove pinned objects from local storage.
      tags:
      - Pinning
      parameters:
      - name: arg
        in: query
        required: true
        description: Path to object(s) to be unpinned
        schema:
          type: string
      - name: recursive
        in: query
        description: Recursively unpin the object linked to by the specified object(s)
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Unpinned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinRmResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /api/v0/pin/ls:
    post:
      operationId: pinList
      summary: List pinned objects
      description: List objects pinned to local storage.
      tags:
      - Pinning
      parameters:
      - name: arg
        in: query
        description: Path to object(s) to be listed
        schema:
          type: string
      - name: type
        in: query
        description: The type of pinned keys to list
        schema:
          type: string
          enum:
          - direct
          - indirect
          - recursive
          - all
          default: all
      - name: quiet
        in: query
        description: Write just hashes of objects
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of pinned objects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinLsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PinAddResponse:
      type: object
      properties:
        Pins:
          type: array
          items:
            type: string
          description: List of pinned CIDs
    PinLsResponse:
      type: object
      properties:
        Keys:
          type: object
          additionalProperties:
            type: object
            properties:
              Type:
                type: string
                enum:
                - direct
                - indirect
                - recursive
    PinRmResponse:
      type: object
      properties:
        Pins:
          type: array
          items:
            type: string
          description: List of unpinned CIDs
    Error:
      type: object
      properties:
        Message:
          type: string
          description: Error message
        Code:
          type: integer
          description: Error code
        Type:
          type: string
          description: Error type
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized; Bearer token missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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