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.