ipfs-pinning-service.yaml

openapi: 3.0.3
info:
  version: "1.0.0"
  title: 'IPFS Pinning Service API'
  x-logo:
    url: "https://bafybeidehxarrk54mkgyl5yxbgjzqilp6tkaz2or36jhq24n3rdtuven54.ipfs.dweb.link/?filename=ipfs-pinning-service.svg"
  description: ""

servers:
  - url: https://pinning-service.example.com

paths:
  /pins:
    get:
      operationId: getPins
      summary: List pin objects
      description: List all the pin objects, matching optional filters; when no filter is provided, only successful pins are returned
      tags:
        - pins
      parameters:
        - $ref: '#/components/parameters/cid'
        - $ref: '#/components/parameters/name'
        - $ref: '#/components/parameters/match'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/before'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/meta'
      responses:
        '200':
          description: Successful response (PinResults object)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/InsufficientFunds'
        '4XX':
          $ref: '#/components/responses/CustomServiceError'
        '5XX':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: addPin
      summary: Add pin object
      description: Add a new pin object for the current access token
      tags:
        - pins
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pin'
      responses:
        '202':
          description: Successful response (PinStatus object)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/InsufficientFunds'
        '4XX':
          $ref: '#/components/responses/CustomServiceError'
        '5XX':
          $ref: '#/components/responses/InternalServerError'

  /pins/{requestid}:
    parameters:
      - name: requestid
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getPinByRequestId
      summary: Get pin object
      description: Get a pin object and its status
      tags:
        - pins
      responses:
        '200':
          description: Successful response (PinStatus object)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/InsufficientFunds'
        '4XX':
          $ref: '#/components/responses/CustomServiceError'
        '5XX':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: replacePinByRequestId
      summary: Replace pin object
      description: Replace an existing pin object (shortcut for executing remove and add operations in one step to avoid unnecessary garbage collection of blocks present in both recursive pins)
      tags:
        - pins
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pin'
      responses:
        '202':
          description: Successful response (PinStatus object)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/InsufficientFunds'
        '4XX':
          $ref: '#/components/responses/CustomServiceError'
        '5XX':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deletePinByRequestId
      summary: Remove pin object
      description: Remove a pin object
      tags:
        - pins
      responses:
        '202':
          description: Successful response (no body, pin removed)
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/InsufficientFunds'
        '4XX':
          $ref: '#/components/responses/CustomServiceError'
        '5XX':
          $ref: '#/components/responses/InternalServerError'

components:
  schemas:

    PinResults:
      description: Response used for listing pin objects matching request
      type: object
      required:
        - count
        - results
      properties:
        count:
          description: The total number of pin objects that exist for passed query filters
          type: integer
          format: int32
          minimum: 0
          example: 1
        results:
          description: An array of PinStatus results
          type: array
          items:
            $ref: '#/components/schemas/PinStatus'
          uniqueItems: true
          minItems: 0
          maxItems: 1000

    PinStatus:
      description: Pin object with status
      type: object
      required:
        - requestid
        - status
        - created
        - pin
        - delegates
      properties:
        requestid:
          description: Globally unique identifier of the pin request; can be used to check the status of ongoing pinning, or pin removal
          type: string
          example: "UniqueIdOfPinRequest"
        status:
          $ref: '#/components/schemas/Status'
        created:
          description: Immutable timestamp indicating when a pin request entered a pinning service; can be used for filtering results and pagination
          type: string
          format: date-time  # RFC 3339, section 5.6
          example: "2020-07-27T17:32:28Z"
        pin:
          $ref: '#/components/schemas/Pin'
        delegates:
          $ref: '#/components/schemas/Delegates'
        info:
          $ref: '#/components/schemas/StatusInfo'

    Pin:
      description: Pin object
      type: object
      required:
        - cid
      properties:
        cid:
          description: Content Identifier (CID) to be pinned recursively
          type: string
          example: "QmCIDToBePinned"
        name:
          description: Optional name for pinned data; can be used for lookups later
          type: string
          maxLength: 255
          example: "PreciousData.pdf"
        origins:
          $ref: '#/components/schemas/Origins'
        meta:
          $ref: '#/components/schemas/PinMeta'

    Status:
      description: Status a pin object can have at a pinning service
      type: string
      enum:
        - queued     # pinning operation is waiting in the queue; additional info can be returned in info[status_details]      
        - pinning    # pinning in progress; additional info can be returned in info[status_details]
        - pinned     # pinned successfully
        - failed     # pinning service was unable to finish pinning operation; additional info can be found in info[status_details]

    Delegates:
      description: List of multiaddrs designated by pinning service that will receive the pin data; see Provider Hints in the docs
      type: array
      items:
        type: string
      uniqueItems: true
      minItems: 1
      maxItems: 20
      example: ['/ip4/203.0.113.1/tcp/4001/p2p/QmServicePeerId']

    Origins:
      description: Optional list of multiaddrs known to provide the data; see Provider Hints in the docs
      type: array
      items:
        type: string
      uniqueItems: true
      minItems: 0
      maxItems: 20
      example: ['/ip4/203.0.113.142/tcp/4001/p2p/QmSourcePeerId', '/ip4/203.0.113.114/udp/4001/quic/p2p/QmSourcePeerId']

    PinMeta:
      description: Optional metadata for pin object
      type: object
      additionalProperties:
        type: string
        minProperties: 0
        maxProperties: 1000
      example:
        app_id: "99986338-1113-4706-8302-4420da6158aa" # Pin.meta[app_id], useful for filtering pins per app

    StatusInfo:
      description: Optional info for PinStatus response
      type: object
      additionalProperties:
        type: string
        minProperties: 0
        maxProperties: 1000
      example:
        status_details: "Queue position: 7 of 9" # PinStatus.info[status_details], when status=queued

    TextMatchingStrategy:
      description: Alternative text matching strategy
      type: string
      default: exact
      enum:
        - exact    # full match, case-sensitive (the implicit default)
        - iexact   # full match, case-insensitive
        - partial  # partial match, case-sensitive
        - ipartial # partial match, case-insensitive

    Failure:
      description: Response for a failed request
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - reason
          properties:
            reason:
              type: string
              description: Mandatory string identifying the type of error
              example: "ERROR_CODE_FOR_MACHINES"
            details:
              type: string
              description: Optional, longer description of the error; may include UUID of transaction for support, links to documentation etc
              example: "Optional explanation for humans with more details"

  parameters:

    before:
      description: Return results created (queued) before provided timestamp
      name: before
      in: query
      required: false
      schema:
        type: string
        format: date-time  # RFC 3339, section 5.6
      example: "2020-07-27T17:32:28Z"

    after:
      description: Return results created (queued) after provided timestamp
      name: after
      in: query
      required: false
      schema:
        type: string
        format: date-time  # RFC 3339, section 5.6
      example: "2020-07-27T17:32:28Z"

    limit:
      description: Max records to return
      name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 10

    cid:
      description: Return pin objects responsible for pinning the specified CID(s); be aware that using longer hash functions introduces further constraints on the number of CIDs that will fit under the limit of 2000 characters per URL  in browser contexts
      name: cid
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
        uniqueItems: true
        minItems: 1
        maxItems: 10
      style: form # ?cid=Qm1,Qm2,bafy3
      explode: false
      example: ["Qm1","Qm2","bafy3"]

    name:
      description: Return pin objects with specified name (by default a case-sensitive, exact match)
      name: name
      in: query
      required: false
      schema:
        type: string
        maxLength: 255
      example: "PreciousData.pdf"

    match:
      description: Customize the text matching strategy applied when the name filter is present; exact (the default) is a case-sensitive exact match, partial matches anywhere in the name, iexact and ipartial are case-insensitive versions of the exact and partial strategies
      name: match
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/TextMatchingStrategy'
      example: exact

    status:
      description: Return pin objects for pins with the specified status
      name: status
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Status'
        uniqueItems: true
        minItems: 1
      style: form # ?status=queued,pinning
      explode: false
      example: ["queued","pinning"]

    meta:
      description: Return pin objects that match specified metadata keys passed as a string representation of a JSON object; when implementing a client library, make sure the parameter is URL-encoded to ensure safe transport
      name: meta
      in: query
      required: false
      content:
        application/json: # ?meta={"foo":"bar"}
          schema:
            $ref: '#/components/schemas/PinMeta'

  responses:

    BadRequest:
      description: Error response (Bad request)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'

    Unauthorized:
      description: Error response (Unauthorized; access token is missing or invalid)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'

    NotFound:
      description: Error response (The specified resource was not found)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'

    InsufficientFunds:
      description: Error response (Insufficient funds)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            InsufficientFundsExample:
              $ref: '#/components/examples/InsufficientFundsExample'

    CustomServiceError:
      description: Error response (Custom service error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            CustomServiceErrorExample:
              $ref: '#/components/examples/CustomServiceErrorExample'

    InternalServerError:
      description: Error response (Unexpected internal server error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            InternalServerErrorExample:
              $ref: '#/components/examples/InternalServerErrorExample'

  examples:

    BadRequestExample:
      value:
        error:
          reason: "BAD_REQUEST"
          details: "Explanation for humans with more details"
      summary: A sample response to a bad request; reason will differ

    UnauthorizedExample:
      value:
        error:
          reason: "UNAUTHORIZED"
          details: "Access token is missing or invalid"
      summary: Response to an unauthorized request

    NotFoundExample:
      value:
        error:
          reason: "NOT_FOUND"
          details: "The specified resource was not found"
      summary: Response to a request for a resource that does not exist

    InsufficientFundsExample:
      value:
        error:
          reason: "INSUFFICIENT_FUNDS"
          details: "Unable to process request due to the lack of funds"
      summary: Response when access token run out of funds

    CustomServiceErrorExample:
      value:
        error:
          reason: "CUSTOM_ERROR_CODE_FOR_MACHINES"
          details: "Optional explanation for humans with more details"
      summary: Response when a custom error occured

    InternalServerErrorExample:
      value:
        error:
          reason: "INTERNAL_SERVER_ERROR"
          details: "Explanation for humans with more details"
      summary: Response when unexpected error occured

  securitySchemes:
    accessToken:
      description: "
An opaque token is required to be sent with each request in the HTTP header:

- `Authorization: Bearer <access-token>`


The `access-token` should be generated per device, and the user should have the ability to revoke each token separately.
"
      type: http
      scheme: bearer
security:
  - accessToken: []