📌Pin Files

APIs related to pin files

➡️ General

Endpoint

All url in the sample code below should start with https://pingo.to/api, for example, when you see a url as "/pin/cid", the full endpoint is "https://pingo.to/api/pin/cid".

Authorization

All the APIs below use Bearer token authorization. You should put:

{
    "Authorization": "Bearer <your api token>"
}

in the request header. You can create/manage your API tokens in the "Access Tokens" page in Pingo.to website.

The Status Field

The status field in the response has 4 possible values:

• Pending - request has been sent, but Pingo hasn't started to pin it yet

• Pinning - Pingo is pinning this cid across all requested servers

• Pinned - Pingo finished pinning this cid in all requested servers. This also means the status field in the servers array are all changed to 3.

• Failed - Pingo failed to pin this cid after trying several times. This could be a result of, for example, Pingo can't find this cid from IPFS peers. If you are sure this cid exists, you could issue a re-pin request. See the repin API below.

➡️ Pin Cid

Pin an existing cid

💡 Click the ">" on the right of the card to see API details.

Send a request to pin an IPFS cid

POST /pin/cid

Content-Type: application/json

Request Body

Name	Type	Description
name*	String	file name
cid*	String	ipfs cid

400: Bad Request Invalid Parameter

{
    // Response
}

409: Conflict Account has pinned this Cid before

412: Precondition Failed Account is missing pin-preference settings

200: OK Pin request has been sent successfully. Click ">" on the right to see an example response

401: Unauthorized Invalid Bearer Token

Sample code (Javascript):

const url = `/pin/cid`
const args = {
    name: "hello.txt",
    cid: "bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e",
}
const headers = {
    "Authorization": "Bearer <your api token>",
}
const resp = await axios.post(url, args, {headers: headers})
if (resp.status === 200) {
    const data = resp.data
    console.log(data.id)
    console.log(data.status)
}

➡️ Pin File

Pin a file via uploading

💡 Click the ">" on the right of the card to see API details.

Send a request to pin a file via uploading

POST /pin/file

Content-Type: multipart/form-data

Request Body

Name	Type	Description
file*	FormData	file form data to upload

400: Bad Request Invalid Parameter

{
    // Response
}

409: Conflict Account has pinned content with the same Cid before

413: Payload Too Large File size is too large

412: Precondition Failed Account is missing pin-preference settings

200: OK Pin request has been sent successfully. Click ">" on the right to see an example response

401: Unauthorized Invalid API Token

Sample code (Javascript):

const url = `/pin/file`
const formData = new FormData()
// f is the file object from <input type="file" />
formData.append("file", f)
const headers = {
  "Authorization": "Bearer <your api token>",
  "Content-Type": "multipart/form-data",
}
const resp = await axios.post(url, formData, { headers: headers })
if (resp.status === 200) {
    const data = resp.data
    console.log(data.id)
    console.log(data.status)
}

➡️ Pin Text

Pin some plain text directly

💡 Click the ">" on the right of the card to see API details

Send a request to pin text directly

POST /pin/text

Content-Type: application/json

Request Body

Name	Type	Description
name*	String	file name
content*	String	text you want to pin

400: Bad Request Invalid Parameter

{
    // Response
}

401: Unauthorized Invalid API Token

409: Conflict Account has pinned content with the same cid before

412: Precondition Failed Account is missing pin-preference settings

413: Payload Too Large File size is too large

200: OK Pin request has been sent successfully. Click ">" on the right to see an example response

Sample code (Javascript):

const url = `/pin/text`
const headers = {
  "Authorization": "Bearer <your api token>",
}
const args = {
    name: "hello.txt",
    content: "hello world",
}
const resp = await axios.post(url, args, { headers: headers })
if (resp.status === 200) {
    const data = resp.data
    console.log(data.id)
    console.log(data.status)
}

➡️ Get Pin Files

Get account pin files

💡 Click the ">" on the right of the card to see API details

Get account's pin file list

GET /pin/files

Query Parameters

Name	Type	Description
page	Number	fetch pins in this page number, default value is 1
count	Number	how many pins to get in this one page, default value is 20, max is 100

400: Bad Request Invalid Parameter

{
    // Response
}

401: Unauthorized Invalid API Token

200: OK Return a pin list. Click ">" on the right to see an example response

Sample code (Javascript):

const url = "/pin/files"
const args = {
  page: 1,
  count: 20,
}
const resp = await axios.get(url, { params: args, headers: headers })
if (resp.status === 200) {
    const data = resp.data
    console.log(data.total)
    console.log(data.list)
}

➡️ Change Pin-File Name

Change a pin-file name.

💡 Click the ">" on the right of the card to see API details

Change name by cid

PUT /pin/cid/<cid>/name

Content-Type: application/json

Path Parameters

Name	Type	Description
cid*	String	file cid's name to change

Request Body

Name	Type	Description
name*	String	new name

400: Bad Request Invalid Parameter

{
    // Response
}

401: Unauthorized Invalid API Token

404: Not Found Account hasn't pinned this Cid before

200: OK Renamed successfully

Sample code (Javascript):

const url = `/pin/cid/${fileCid}/name`
const headers = {
  "Authorization": "Bearer <your api token>",
}
const args = {
  name: newName,
}
const resp = await axios.put(url, args, { headers: headers })
if (resp.status === 200) {
  // renamed successfully
}

➡️ Delete Pin Cid

Delete a pinned Cid.

💡 Click the ">" on the right of the card to see API details

Delete / Unpin a pinned Cid. The current Cid's pin status must be "Pinned".

DELETE /pin/cid/<cid>

Path Parameters

Name	Type	Description
cid	String	cid to delete/unpin

400: Bad Request Invalid Parameter

{
    // Response
}

401: Unauthorized Invalid API Token

404: Not Found This account hasn't pinned this Cid before

403: Forbidden This Cid's current pin-status is not "Pinned"

200: OK Deleted successfully

Sample code (Javascript):

const url = `/pin/cid/${fileCid}`
const headers = {
  "Authorization": "Bearer <your api token>",
}
const resp = await apis.delete(url, { headers: headers })
if (resp.status === 200) {
  // deleted successfully
}

➡️ Re-pin Cid

When you called the "Pin Cid" API above, Pingo will try many times to search Cid across the IPFS nodes and try to fetch that file to Pingo server. However, sometimes it may end up with "failed" to pin, e.g. this Cid doesn't exist across the IPFS nodes thus Pingo failed to find it. But if you are sure this Cid exists, you can make this re-pin API call to try to pin this Cid again.

💡 Click the ">" on the right of the card to see API details

Repin a Cid. To repin a Cid, the current pin status must be "Failed".

POST /repin/cid

Content-Type: application/json

Request Body

Name	Type	Description
cid*	String	Cid to repin

400: Bad Request Invalid Parameter

{
    // Response
}

401: Unauthorized Invalid API Token

403: Forbidden This cid status is not "Failed"

404: Not Found This account hasn't pinned this Cid before

200: OK Request has been sent successfully.

Sample code (Javascript):

const url = `/repin/cid`
const headers = {
  "Authorization": "Bearer <your api token>",
}
const args = {
  cid: cid,
}
const resp = await axios.post(url, args, { headers: headers })
if (resp.status === 200) {
  // success
}