Adding a Pin

Adding a new pin to the Sagittarius A* IPFS Cluster.

Overview

The Pin Add Request, a POST request to the /ipfs/pin/add endpoint, is an IPFS Pin Orchestration request used to create a new pin for the provided CID on the Sagittarius A* IPFS Cluster. Because multiple requestors may attempt to pin the same CID, a request ID system is utilized to differentiate between these different requests, where the x-api-key from the request header is used as a unique identifier. This allows for multiple requestors to pin the same CID without any conflict.

Request Spec

  /ipfs/pin/add/{cid}:
    post:
      summary: Pin an IPFS CID.
      parameters:
        - in: path
          name: cid
          required: true
          description: An IPFS Content Identifier (CID).
          schema:
            type: string

Sending the Request

Sending a request to the /ipfs/pin/add endpoint requires a valid API Key to be provided in the x-api-key header, and that an IPFS CID be provided.

Pin Add Request

curl -X POST -H "x-api-key: Your-API-Key" https://api.sgr-a.xyz/ipfs/pin/add/QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u 

When a Pin Add Request completes successfully, the returned output will contain a success message for confirmation, along with information about the newly created pin.

Pin Add Output

{
    "message": "Pin added successfully",
    "result": {
        "cid": "CID",
        "type": "pin",
        "timestamp": "TIMESTAMP"
    },
    "apiKey": "Your-API-Key"
}

In the case where a pin already exists for the given apiKey and cid pair, a new pin will not be created. Instead, a message will be returned alerting that a pin already exists.

Pin Add Output

{
    "message": "Pin already exists for this CID and API key"
}