Files
Pin

Pin

Pin an existing CID (content already on IPFS). Requires scope files:write.


Endpoint

MethodPOST
URLhttps://api.pinarkive.com/api/v3/files/pin/:cid
Content-Typeapplication/json

Replace :cid with the IPFS content identifier.

Headers: Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY

Body (optional): originalName, customName, cl (cluster id), timelock (ISO 8601, premium only).


Request

cURL

curl -X POST "https://api.pinarkive.com/api/v3/files/pin/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cl": "cl0-global"}'

JavaScript (fetch)

const cid = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi";
 
const response = await fetch(`https://api.pinarkive.com/api/v3/files/pin/${cid}`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.PINARKIVE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ cl: "cl0-global" }),
});
const data = await response.json();

JavaScript (axios)

const cid = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi";
 
const { data } = await axios.post(
  `https://api.pinarkive.com/api/v3/files/pin/${cid}`,
  { cl: "cl0-global" },
  {
    headers: {
      "X-API-Key": process.env.PINARKIVE_API_KEY,
      "Content-Type": "application/json",
    },
  }
);

Python

import os
import requests
 
cid = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
url = f"https://api.pinarkive.com/api/v3/files/pin/{cid}"
headers = {
    "X-API-Key": os.environ["PINARKIVE_API_KEY"],
    "Content-Type": "application/json",
}
payload = {"cl": "cl0-global"}
r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()
print(r.json())

Go

package main
 
import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)
 
func main() {
	cid := "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
	url := "https://api.pinarkive.com/api/v3/files/pin/" + cid
	apiKey := os.Getenv("PINARKIVE_API_KEY")
	body, _ := json.Marshal(map[string]string{"cl": "cl0-global"})
	req, _ := http.NewRequest("POST", url, bytes.NewReader(body))
	req.Header.Set("X-API-Key", apiKey)
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

PHP

<?php
$cid = 'bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi';
$url = "https://api.pinarkive.com/api/v3/files/pin/$cid";
$apiKey = getenv('PINARKIVE_API_KEY');
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['cl' => 'cl0-global']));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);

Response

Success (200 / 201)

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "clusterId": "cl0-global",
  "expiresAt": "2026-12-31T23:59:59.000Z"
}
FieldTypeDescription
cidstringThe pinned CID
clusterIdstringCluster where the content was pinned
expiresAtstring | nullExpiration (timelock), if set

Error (4xx / 5xx)

{
  "error": "Bad Request",
  "message": "Invalid CID"
}

Common codes: 401, 403 (quota, timelock on free plan, or code: missing_scope, required), 404 (CID not found), 429 (rate limit). See Error handling.

We use analytics cookies to understand how the docs are used. Accept to enable Google Analytics, or reject to continue without tracking.