Pin
Pin an existing CID (content already on IPFS). Requires scope files:write.
Endpoint
| Method | POST |
| URL | https://api.pinarkive.com/api/v3/files/pin/:cid |
| Content-Type | application/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"
}| Field | Type | Description |
|---|---|---|
cid | string | The pinned CID |
clusterId | string | Cluster where the content was pinned |
expiresAt | string | null | Expiration (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.