Pinning

Закріпіть існуючий контент IPFS на вашому акаунті. Коли ви закріплюєте CID, наш кластер отримує контент з мережі IPFS і забезпечує його постійну доступність.

Закріпити за CID

POST /pin

Параметр	Тип	Обов'язковий	Опис
cid	string	Так	Ідентифікатор контенту IPFS. Приймається будь-яка форма: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… та інші кодеки).
description	string	Ні	Короткий опис для вашого довідника.
metadata	object	Ні	Користувацькі пари ключ-значення для прикріплення до пінінгу. Макс. 10 ключів. Ключі мають бути буквено-цифровими або з підкресленням, 1-64 символи. Значення мають бути рядками, макс. 256 символів кожне. Загальний розмір метаданих не повинен перевищувати 4 КБ.
multiaddresses	string[]	Ні	Опціональні swarm-connect підказки. До 5 multiaddress libp2p для пірів, що хостять цей CID. Наш кластер паралельно виконує swarm connect для кожного з них перед пінінгом, тому контент на приватних / не-DHT пірах стає доступним без очікування DHT-виявлення. Best-effort — невдале з'єднання не провалює пінінг. Див. Закріплення з приватного вузла.

Приклад запиту

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Відповідь 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Для великих DAG (>500 блоків або >50 MB) відповідь включає прапорець async: true:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Закріплення з приватного вузла

Якщо CID, який ви хочете закріпити, знаходиться на пірі, що не бере участі в публічному DHT — приватний staging-вузол, самостійно розгорнута машина у VPN або робоча станція за NAT — стандартний потік пінінгу його не знайде. Передача одного або кількох multiaddresses вказує нашому кластеру, де саме шукати.

Ми виконуємо ipfs swarm connect <multiaddr> для кожної підказки паралельно перед запуском пінінгу. Якщо з'єднання успішне, отримання DAG для пінінгу може звертатися напряму до вашого піра замість пошуку через DHT. Якщо невдало — пінінг все одно продовжується проти публічної мережі (семантика best-effort).

Приклад: закріплення з конкретного піра

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

Відповідь включає статус для кожної підказки

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Прийняті форми multiaddress

Підтримуються поширені форми: транспорти /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; протоколи /tcp або /udp; опціональні надбудови /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiaddress повинна закінчуватися на /p2p/<peerId>. Ліміт: до 5 підказок на один пінінг.

Отримання multiaddress вашого вузла

На піру, з якого ви хочете закріплювати, виконайте ipfs id і скопіюйте будь-який із записів Addresses, що закінчується на /p2p/<PeerID>. Надавайте перевагу публічно маршрутизованим адресам (/ip4/YOUR_PUBLIC_IP/…) або DNS-based адресам (/dnsaddr/your.domain/…), щоб наш кластер міг досягти піра з AWS.

Закріплення дуже великих директорій

POST /pin призначений для контенту, що вже існує в мережі IPFS — кластер отримує DAG блок за блоком від пірів, що може зайняти кілька хвилин для директорій з 1000+ файлів. Протягом цього вікна отримання деякі дочірні файли можуть бути ще недоступні локально, і запити gateway до них можуть перевищувати час очікування. Щойно status батьківського елемента переходить у pinned, кожен дочірній елемент стає локально доступним і доступним через ваш gateway.

Якщо у вас є файли локально (а не лише CID), для великих колекцій NFT або наборів даних надавайте перевагу CAR import — він завантажує весь DAG на IPFS Ninja одним атомарним запитом, тож немає вікна отримання чи стану часткового пінінгу. Створіть CAR за допомогою:

npx ipfs-car pack ./my-collection -o collection.car

Потім імпортуйте його через POST /upload/new з car: true.

TIP

Пінінг є асинхронним. Відповідь повертається негайно зі статусом pinning. Опитуйте ендпоінт статусу, щоб перевірити, коли пінінг завершиться.

Перевірка статусу закріплення

GET /pin/:cid

Параметр	Тип	Обов'язковий	Опис
cid	string	Так	CID, який ви перевіряєте.

Відповідь 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Значення статусу

Статус	Значення
pinning	Контент отримується з мережі IPFS. Опитайте знову за кілька секунд.
pinned	Контент закріплений і доступний через ваш акаунт та gateway.
failed	Контент не вдалося знайти в мережі IPFS. CID може бути недійсним, або контент більше недоступний.

Як працює пінінг

1. Ви надсилаєте CID через POST /pin
2. Наш кластер IPFS шукає в мережі вузли, що мають цей контент
3. Кластер завантажує та закріплює контент локально
4. Після закріплення файл з'являється у вашому списку файлів і доступний через gateway
5. Використання сховища записується після завершення пінінгу

WARNING

Час пінінгу залежить від розміру файлу та доступності мережі. Малі файли зазвичай закріплюються за секунди. Великі файли або рідко закріплюваний контент можуть зайняти кілька хвилин.

Сховище

Закріплений контент враховується в ліміт сховища вашого плану. Розмір файлу записується після завершення пінінгу. Якщо ви наближаєтесь до ліміту сховища, ви можете звільнити місце, видаливши невикористані файли, або оновити план для більшої ємності.