IPFS Pins API

openapi: 3.2.0
info:
  version: 1.0.0
  title: IPFS Pinning Service Pins API
  x-logo:
    url: https://bafybeidehxarrk54mkgyl5yxbgjzqilp6tkaz2or36jhq24n3rdtuven54.ipfs.dweb.link/?filename=ipfs-pinning-service.svg
  contact:
    name: IPFS
    url: https://github.com/ipfs/pinning-services-api-spec
  description: '## About this spec

    The IPFS Pinning Service API is intended to be an implementation-agnostic API:

    - For use and implementation by pinning service providers

    - For use in client mode by IPFS nodes and GUI-based applications


    ### Document scope and intended audience

    The intended audience of this document is **IPFS developers** building pinning service clients or servers compatible with this OpenAPI spec.'
servers:
- url: https://pinning-service.example.com
security:
- accessToken: []
tags:
- name: Pins
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:
  parameters:
    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
      explode: false
      example:
      - Qm1
      - Qm2
      - bafy3
    status:
      description: Return pin objects for pins with the specified status (when missing, service should default to pinned only)
      name: status
      in: query
      required: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Status'
        uniqueItems: true
        minItems: 1
      style: form
      explode: false
      example:
      - queued
      - pinning
    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
    before:
      description: Return results created (queued) before provided timestamp
      name: before
      in: query
      required: false
      schema:
        type: string
        format: date-time
      example: '2020-07-27T17:32:28.276Z'
    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
    after:
      description: Return results created (queued) after provided timestamp
      name: after
      in: query
      required: false
      schema:
        type: string
        format: date-time
      example: '2020-07-27T17:32:28.276Z'
    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:
          schema:
            $ref: '#/components/schemas/PinMeta'
    limit:
      description: Max records to return
      name: limit
      in: query
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 10
  schemas:
    Status:
      description: Status a pin object can have at a pinning service
      type: string
      enum:
      - queued
      - pinning
      - pinned
      - failed
    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
          example: '2020-07-27T17:32:28.276Z'
        pin:
          $ref: '#/components/schemas/Pin'
        delegates:
          $ref: '#/components/schemas/Delegates'
        info:
          $ref: '#/components/schemas/StatusInfo'
    PinMeta:
      description: Optional metadata for pin object
      type: object
      additionalProperties:
        type: string
        minProperties: 0
        maxProperties: 1000
      example:
        app_id: 99986338-1113-4706-8302-4420da6158aa
    TextMatchingStrategy:
      description: Alternative text matching strategy
      type: string
      default: exact
      enum:
      - exact
      - iexact
      - partial
      - ipartial
    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
    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'
    StatusInfo:
      description: Optional info for PinStatus response
      type: object
      additionalProperties:
        type: string
        minProperties: 0
        maxProperties: 1000
      example:
        status_details: 'Queue position: 7 of 9'
    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
    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
  examples:
    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
    CustomServiceErrorExample:
      value:
        error:
          reason: CUSTOM_ERROR_CODE_FOR_MACHINES
          details: Optional explanation for humans with more details
      summary: Response when a custom error occured
    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
    UnauthorizedExample:
      value:
        error:
          reason: UNAUTHORIZED
          details: Access token is missing or invalid
      summary: Response to an unauthorized request
    InternalServerErrorExample:
      value:
        error:
          reason: INTERNAL_SERVER_ERROR
          details: Explanation for humans with more details
      summary: Response when unexpected error occured
    BadRequestExample:
      value:
        error:
          reason: BAD_REQUEST
          details: Explanation for humans with more details
      summary: A sample response to a bad request; reason will differ
  responses:
    NotFound:
      description: Error response (The specified resource was not found)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    BadRequest:
      description: Error response (Bad request)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    InternalServerError:
      description: Error response (Unexpected internal server error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            InternalServerErrorExample:
              $ref: '#/components/examples/InternalServerErrorExample'
    InsufficientFunds:
      description: Error response (Insufficient funds)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            InsufficientFundsExample:
              $ref: '#/components/examples/InsufficientFundsExample'
    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'
    CustomServiceError:
      description: Error response (Custom service error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            CustomServiceErrorExample:
              $ref: '#/components/examples/CustomServiceErrorExample'
  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