Pinning

Pinning

Pin Files or Directory

This API allows you to pin a file to IPFS using the provided pinning API key and secret key.

Example metadata:

{
  "name": "sample name", 
  "keyvalues": {
    "key1": "value1",
    "key2": "value2"
  }
}
POSThttps://api.w3ipfs.storage/api/pinning

Headers

pinning_api_key* PINNING-API-KEY
pinning_secret_key* PINNING-SECRET-KEY

Body

file* Read stream representing the file
metadata Optional stringified object

Response

201: Created
{
    "data": {
        "id": "string",
        "file_record_id": "string",
        "root_hash": "string",
        "cid": "string",
        "user_id": "string",
        "date_pinned": "2023-01-01T11:11:11.111111Z",
        "date_unpinned": "2023-11-11T11:11:11.111111Z",
        "pinned": false,
        "is_pin_by_hash": false,
        "sub_hash_status": "string",
        "is_dir": false,
        "metadata": {
            "name": "string",
            "type": "string"
        },
        "status": "string"
    },
    "status": "success"
}
curl --location --request POST 'https://api.w3ipfs.storage/api/pinning/' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET' \
--form 'file=@"/test.png"'

Pin by CID

The request body when pin a file by CID will look like this:

{
    "hash_to_pin": "CID",
    "metadata": {
        "name": "string",
        "keyvalues": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}
POSThttps://api.w3ipfs.storage/api/pinning/pinByHash

Headers

pinning_api_key* PINNING-API-KEY
pinning_secret_key* PINNING-SECRET-KEY

Body

hash_to_pin* CID
metadata Optional stringified object

Response

200: OK
{
    "data": {
        "id": "string",
        "file_record_id": "string",
        "root_hash": "string",
        "cid": "string",
        "user_id": "string",
        "date_pinned": "2023-01-01T11:11:11.111111Z",
        "date_unpinned": "2023-11-11T11:11:11.111111Z",
        "pinned": false,
        "is_pin_by_hash": true,
        "is_dir": false,
        "metadata": {
            "name": "string"
        },
        "status": "string"
    },
    "status": "success"
}
curl --location --request POST 'https://api.w3ipfs.storage/api/pinning/pinByHash' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET' \
--header 'Content-Type: application/json' \
--data-raw '{
"hash_to_pin": "Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs",
"metadata": {
    "name": "name-ipfs-hash"
}
}'

Get Pin Details by pinID

This code snippet makes a GET request to the /pinning/{pinId} endpoint, where {pinId} is the ID of the pin you want to retrieve information for.

GEThttps://api.w3ipfs.storage/api/pinning/:pinId

Parameters

pinId* pinId

Headers

pinning_api_key* PINNING-API-KEY
pinning_secret_key* PINNING-SECRET-KEY

Response

200: OK
{
    "data": {
        "id": "string",
        "file_record_id": "string",
        "root_hash": "string",
        "cid": "string",
        "size": number,
        "user_id": "string",
        "date_pinned": "2023-01-01T11:11:11.111111Z",
        "date_unpinned": "2023-11-11T11:11:11.111111Z",
        "pinned": true,
        "is_pin_by_hash": false,
        "sub_hash_status": "string",
        "is_dir": false,
        "metadata": {
            "name": "string",
            "type": "string"
        },
        "status": "string"
    },
    "status": "success"
}
curl --location --request GET 'https://api.w3ipfs.storage/api/pinning/3c3fec2a-ca65-4b8e-bcf3-c8e2ceaa23d2' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET' 

List Pins of User

GEThttps://api.w3ipfs.storage/api/pinning/pins/

Query

offset (default 0)
limit (default 10)
pinned Filter by pinned status (options: all, true, false) (default all)
sortBy Field to sort by (options: created_at, size, name). Defaults to created_at.
sortOrder Sort direction (options: ASC, DESC). Defaults to DESC.

Headers

pinning_api_key* PINNING-API-KEY
pinning_secret_key* PINNING-SECRET-KEY

Response

200: OK
{
    "data": {
        "totals": {
            "files": number,
            "size": number
        },
        "pins": [
            {
                "id": "string",
                "file_record_id": "string",
                "root_hash": "string",
                "cid": "string",
                "size": number,
                "user_id": "string",
                "date_pinned": "2023-01-01T11:11:11.111111Z",
                "date_unpinned": "2023-11-11T11:11:11.111111Z",
                "pinned": true,
                "is_pin_by_hash": true,
                "sub_hash_status": "string",
                "is_dir": false,
                "metadata": {
                    "name": "string"
                },
                "status": "string"
            }
        ]
    },
    "status": "success"
}
curl --location --request GET 'https://api.w3ipfs.storage/api/pinning/pins/?offset=0&limit=10&pinned=true&sortBy=name&sortOrder=ASC' \
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET'

Remove Files (Unpin)

DELETEhttps://api.w3ipfs.storage/api/pinning/unpin/:pinId

Parameters

pinId* pinId

Headers

pinning_api_key* PINNING-API-KEY
pinning_secret_key* PINNING-SECRET-KEY

Response

200: OK
{
    "data": {
        "id": "string",
        "file_record_id": "string",
        "root_hash": "string",
        "cid": "string",
        "size": number,
        "user_id": "string",
        "date_pinned": "2023-01-01T11:11:11.111111Z",
        "date_unpinned": "2023-11-11T11:11:11.111111Z",
        "pinned": true,
        "is_pin_by_hash": true,
        "is_dir": false,
        "metadata": {
            "name": "string"
        },
        "status": "string"
    },
    "status": "success"
}
curl --location --request DELETE 'https://api.w3ipfs.storage/api/pinning/unpin/:pinId
--header 'pinning_api_key: KEY' \
--header 'pinning_secret_key: SECRET'