# IPFS Pinning Service API ## What is the IPFS Pinning Service API? The IPFS Pinning Service API is a standardized API for re-pinning existing IPFS CIDs. It is often referred to as "remote" pinning or the IPFS "PSA". The IPFS PSA is used by both the IPFS CLI and IPFS Desktop application. The IPFS development team tracks the compliance of each provider that supports the IPFS PSA to validate each implementation. Filebase is fully compliant with the IPFS PSA requirements. The official compliance report can be seen [here](https://ipfs-shipyard.github.io/pinning-service-compliance/api.filebase.io.html). Filebase supports the IPFS Pinning Service API through our [IPFS Re-Pinning](https://docs.filebase.com/ipfs-concepts/what-is-ipfs-pinning#re-pinning-existing-ipfs-cids-from-the-filebase-web-console) service. This API can be used to view pinned objects, add a new object to be pinned, or remove a pinned object. {% hint style="info" %} The IPFS Pinning Service API has an effective rate limit of 100 RPS per IP address. {% endhint %} To interact with the Filebase IPFS Pinning Service API, use the following information below. ### **API Endpoint** `https://api.filebase.io/v1/ipfs/pins` ### Authentication To authenticate with the IPFS Pinning Service API, a token is required to be sent with each request in the HTTP headers, using the following format: * `Authorization: Bearer ` The **`access-token`** can be generated by navigating to the [Filebase Access Keys page](https://console.filebase.com/keys), then viewing the IPFS Pinning Service API Endpoint. Click the drop down menu for 'Choose Bucket to Generate Token', then choose the IPFS Filebase Bucket you want to use.
Then copy the generated Secret Access Token:
### Payload **Request Body Schema:** `application/json` To interact with the IPFS Pinning Service API, you need to send a payload in the form of JSON to the API URL. The following is an example of a POST payload: ```json { "cid": "bafybeihbfkn5afsjep2jd65gn5vedh7vpvp6i6avfu5za7fnnhsvfutzjy", "name": "image3", "meta": { "key_name": "value_name" } } ``` {% hint style="info" %} **All parameters listed in the following API methods are JSON fields in the payload.** {% endhint %} ## List pinned objects `GET` `https://api.filebase.io/v1/ipfs/pins` List all pinned objects; supports optional filters, if no filter is provided all successful pins are returned. #### Query Parameters | Name | Type | Description | | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cid | Array |

Returns pinned objets matching specified filters. Limit of 2000 characters per URL in browser contexts.

Example: cid=Qm1 , bafy2 , Qm3

| | name | String |

Return pinned objects with a specific name. Default matching strategy is case-sensitive, exact match.

Example: name=ExampleObject.pdf

| | match | String |

Customize the text matching strategy applied to the name filter. Default matching strategy is case-sensitive, exact match. Other options are partial matches, case-insensitive exact (iexact)and case-insensitive partial (ipartial) matches.

Options: "exact" "iexact" "partial" "ipartial"

Example: match=iexact

| | status | Array |

Return pinned objects matching a specified status.

Options: "queued" "pinning" "pinned" "failed"

Example: status=queued,failed

| | before | String |

Return pinned objects queued before the provided timestamp.

Example: before=2022-02-09T12:12:02Z

| | after | String |

Return pinned objects queued after the provided timestamp.

Example: after=2022-02-09T12:12:02Z

| | limit | Integer |

Maximum amount of results to return.

Default: 10

Example: limit=20

| | meta | Object |

Return pinned objects that match specified metadata values passed using a string representation of a JSON object. If using a client library, encode the parameter to ensure secure transmission.

Example: meta={"object\_id": "99999"}

| {% tabs %} {% tab title="200: OK Successful Response (PinResults object)" %} ```javascript { "count": 1, "results": [ { "requestid": "UniqueIdOfPinRequest", "status": "queued", "created": "2022-02-09T12:12:02Z", "pin": { "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane", "name": "nft-collection", "origins": [ "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId", "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId" ], "meta": { "object_id": "99999" } }, "delegates": [ "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId" ], "info": { "status_details": "Queue position: 1 of 1" } } ] } ``` {% endtab %} {% tab title="400: Bad Request Bad request" %} ```javascript { "error": { "reason": "BAD_REQUEST", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% tab title="401: Unauthorized Unauthorized request" %} ```javascript { "error": { "reason": "UNAUTHORIZED", "details": "Access token is missing or invalid" } } ``` {% endtab %} {% tab title="404: Not Found Resource not found" %} ```javascript { "error": { "reason": "NOT_FOUND", "details": "The specified resource was not found" } } ``` {% endtab %} {% tab title="409 Naming conflict" %} ```javascript { "error": { "reason": "NAMING CONFLICT", "details": "Unable to process request due to object naming conflict." } } ``` {% endtab %} {% tab title="500: Internal Server Error Internal server error" %} ```javascript { { "error": { "reason": "INTERNAL_SERVER_ERROR", "details": "Detailed explanation of internal server error" } } ``` {% endtab %} {% endtabs %} ## Pin an object `POST` `https://api.filebase.io/v1/ipfs/pins` Add a new object to be pinned on IPFS. #### Request Body | Name | Type | Description | | ------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | | cid\* | String | CID to be pinned to IPFS. | | name | String |

Optional human-readable name to be associated with the pinned CID.

Less than or equal to 255 characters.

| | origins | Array | List of multi addresses known to provide the CID's data. | | meta | Object | Optional metadata to be associated with the pinned CID. | {% tabs %} {% tab title="202 Successful response (PinStatus object)" %} ```javascript { "requestid": "UniqueIdOfPinRequest", "status": "queued", "created": "2022-02-09T12:12:02Z", "pin": { "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane", "name": "nft-collection", "origins": [ "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId", "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId" ], "meta": { "object_id": "99999" } }, "delegates": [ "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId" ], "info": { "status_details": "Queue position: 1 of 1" } ``` {% endtab %} {% tab title="400: Bad Request Bad request" %} ```javascript { "error": { "reason": "BAD_REQUEST", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% tab title="401: Unauthorized Unauthorized request" %} ```javascript { "error": { "reason": "UNAUTHORIZED", "details": "Access token is missing or invalid" } } ``` {% endtab %} {% tab title="404: Not Found Resource not found" %} ```javascript { "error": { "reason": "NOT_FOUND", "details": "The specified resource was not found" } } ``` {% endtab %} {% tab title="409 Naming conflict" %} ```javascript { "error": { "reason": "NAMING CONFLICT", "details": "Unable to process request due to object naming conflict." } } ``` {% endtab %} {% tab title="500: Internal Server Error Internal server error" %} ```javascript { "error": { "reason": "INTERNAL_SERVER_ERROR", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% endtabs %} ## Get pinned object `GET` `https://api.filebase.io/v1/ipfs/pins/{requestid}` Get a pinned object's information and status. #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | requestid\* | String | | {% tabs %} {% tab title="200: OK Successful Response (PinStatus object)" %} ```javascript { "requestid": "UniqueIdOfPinRequest", "status": "queued", "created": "2022-02-09T12:12:02Z", "pin": { "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane", "name": "nft-collection", "origins": [ "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId", "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId" ], "meta": { "object_id": "99999" } }, "delegates": [ "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId" ], "info": { "status_details": "Queue position: 1 of 1" } ``` {% endtab %} {% tab title="400: Bad Request Bad request" %} ```javascript { "error": { "reason": "BAD_REQUEST", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% tab title="401: Unauthorized Unauthorized request" %} ```javascript { "error": { "reason": "UNAUTHORIZED", "details": "Access token is missing or invalid" } } ``` {% endtab %} {% tab title="404: Not Found Resource not found" %} ```javascript { "error": { "reason": "NOT_FOUND", "details": "The specified resource was not found" } } ``` {% endtab %} {% tab title="409 Naming conflict" %} ```javascript { "error": { "reason": "NAMING CONFLICT", "details": "Unable to process request due to object naming conflict." } } ``` {% endtab %} {% tab title="500: Internal Server Error Internal server error" %} ```javascript { "error": { "reason": "INTERNAL_SERVER_ERROR", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% endtabs %} ## Replace pinned object `POST` `https://api.filebase.io/v1/ipfs/pins/{requestid}` Replace an existing pinned object. This can be used as a shortcut for running remove and add operations separately for recursive pins. #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | requestid\* | String | | #### Request Body | Name | Type | Description | | ------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------- | | cid\* | String | CID to be pinned to IPFS. | | name | String |

Optional human-readable name to be associated with the pinned CID.

Less than or equal to 255 characters.

| | origins | Array | List of multi addresses known to provide the CID's data. | | meta | String | Optional metadata to be associated with the pinned CID. | {% tabs %} {% tab title="202 Successful response (PinStatus object)" %} ```javascript { "requestid": "UniqueIdOfPinRequest", "status": "queued", "created": "2022-02-09T12:12:02Z", "pin": { "cid": "QmWTqpfKyPJcGuWWg73beJJiL6FrCB5yX8qfcCF4bHvane", "name": "nft-collection", "origins": [ "/ip4/123.12.113.142/tcp/4001/p2p/SourcePeerId", "/ip4/123.12.113.114/udp/4001/quic/p2p/SourcePeerId" ], "meta": { "object_id": "99999" } }, "delegates": [ "/ip4/123.12.113.142/tcp/4001/p2p/QmServicePeerId" ], "info": { "status_details": "Queue position: 1 of 1" } ``` {% endtab %} {% tab title="400: Bad Request Bad request" %} ```javascript { "error": { "reason": "BAD_REQUEST", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% tab title="401: Unauthorized Unauthorized request" %} ```javascript { "error": { "reason": "UNAUTHORIZED", "details": "Access token is missing or invalid" } } ``` {% endtab %} {% tab title="404: Not Found Resource not found" %} ```javascript { "error": { "reason": "NOT_FOUND", "details": "The specified resource was not found" } } ``` {% endtab %} {% tab title="409 Naming conflict" %} ```javascript { "error": { "reason": "NAMING CONFLICT", "details": "Unable to process request due to object naming conflict." } } ``` {% endtab %} {% tab title="500: Internal Server Error Internal service error" %} ```javascript { "error": { "reason": "INTERNAL_SERVER_ERROR", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% endtabs %} ## Remove pinned object `DELETE` `https://api.filebase.io/v1/ipfs/pins/{requestid}` Remove a pinned object. #### Path Parameters | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | requestid\* | String | | {% tabs %} {% tab title="202 Successful response" %} ```javascript No body, pin is removed. ``` {% endtab %} {% tab title="400: Bad Request Bad request" %} ```javascript { "error": { "reason": "BAD_REQUEST", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% tab title="401: Unauthorized Unauthorized request" %} ```javascript { "error": { "reason": "UNAUTHORIZED", "details": "Access token is missing or invalid" } } ``` {% endtab %} {% tab title="404: Not Found Resource not found" %} ```javascript { "error": { "reason": "NOT_FOUND", "details": "The specified resource was not found" } } ``` {% endtab %} {% tab title="409 Naming conflict" %} ```javascript { "error": { "reason": "NAMING CONFLICT", "details": "Unable to process request due to object naming conflict." } } ``` {% endtab %} {% tab title="500: Internal Server Error Internal server error" %} ```javascript { "error": { "reason": "INTERNAL_SERVER_ERROR", "details": "Detailed explanation of bad request" } } ``` {% endtab %} {% endtabs %}