IPFS pins API

openapi: 3.0.0
info:
  title: IPFS RPC Add pins API
  version: v0
  description: 'When a Kubo IPFS node is running as a daemon, it exposes an HTTP RPC API that allows you to control the node and run the same commands you can from the command line.


    In many cases, using this RPC API is preferable to embedding IPFS directly in your program — it allows you to maintain peer connections that are longer lived than your app and you can keep a single IPFS node running instead of several if your app can be launched multiple times. In fact, the `ipfs` CLI commands use this RPC API when operating in online mode.'
  x-providerName: IPFS
  x-logo:
    url: https://raw.githubusercontent.com/ipfs/ipfs-docs/55fe8bc6a53ba3b9023951fb4b432efbbc81fba5/docs/.vuepress/public/images/ipfs-logo.svg
servers:
- description: Local IPFS node
  url: http://localhost:5001
- description: Local IPFS node
  url: http://127.0.0.1:5001
- description: Infura hosted IPFS node
  url: https://ipfs.infura.io:5001
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:
  schemas:
    StatusInfo:
      description: Optional info for PinStatus response
      type: object
      additionalProperties:
        type: string
        minProperties: 0
        maxProperties: 1000
      example:
        status_details: 'Queue position: 7 of 9'
    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
    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
    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
    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'
    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'
    Status:
      description: Status a pin object can have at a pinning service
      type: string
      enum:
      - queued
      - pinning
      - pinned
      - failed
  examples:
    CustomServiceErrorExample:
      value:
        error:
          reason: CUSTOM_ERROR_CODE_FOR_MACHINES
          details: Optional explanation for humans with more details
      summary: Response when a custom 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
    InternalServerErrorExample:
      value:
        error:
          reason: INTERNAL_SERVER_ERROR
          details: Explanation for humans with more details
      summary: Response when unexpected 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
    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
  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
    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'
    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'
    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
    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
  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'
    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'
    InsufficientFunds:
      description: Error response (Insufficient funds)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            InsufficientFundsExample:
              $ref: '#/components/examples/InsufficientFundsExample'
    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'
    CustomServiceError:
      description: Error response (Custom service error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          examples:
            CustomServiceErrorExample:
              $ref: '#/components/examples/CustomServiceErrorExample'
externalDocs:
  url: https://docs.ipfs.tech/reference/kubo/rpc/