Файли

Завантажуйте, переглядайте та отримуйте файли в IPFS. Див. автентифікацію для налаштування API key та помилки для кодів статусу HTTP.

Завантаження файлу в IPFS: 3 кроки

POST /upload/new

1. Закодуйте ваш файл у base64 (для зображень/PDF) або передайте JSON-об'єкт напряму.
2. Надішліть POST-запит на /upload/new з вашим API key у заголовку X-Api-Key.
3. Збережіть повернутий cid — він постійно ідентифікує ваш файл в IPFS.

Завантажте будь-який файл в IPFS. Файл закріплюється і повертається постійний CID.

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
content	string | object	Так	JSON-об'єкт/масив або дані файлу в кодуванні base64 (зображення, PDF, HTML або будь-який тип файлу). Для CAR-імпорту — CAR-файл у кодуванні base64.
car	boolean	Ні	Встановіть true для імпорту CAR-файлу (імпорт DAG). Зберігає точні CID.
description	string	Ні	Короткий опис завантаженого контенту.
metadata	object	Ні	Користувацькі пари ключ-значення для прикріплення до файлу. Макс. 10 ключів. Ключі мають бути буквено-цифровими або з підкресленням, 1-64 символи. Значення мають бути рядками, макс. 256 символів кожне. Загальний розмір метаданих не повинен перевищувати 4 КБ.

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

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

Завантаження зображення (base64)

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: image,
    description: "Profile photo"
  })
});

Відповідь 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

CIDv1 за замовчуванням

Нові завантаження повертають сучасні CIDv1 (bafk… для малого одноблокового контенту, bafy… для більших файлів і директорій) відповідно до профілю IPIP-0499 unixfs-v1-2025 — блоки по 1 MiB з raw leaves. Застарілі CID Qm… з попередніх завантажень залишаються повністю розв'язуваними і продовжують працювати з кожним ендпоінтом.

Альтернатива через dashboard

Сторінка /upload у dashboard приймає drag-and-drop для файлів, папок (запаковуються в директорію UnixFS у браузері) та архівів .car — усі вони проходять через той самий ендпоінт. Див. CAR Import для деталей про шлях CAR.

Підтримувані типи файлів

API приймає JSON-об'єкти та масиви напряму, а також бінарні файли в кодуванні base64: зображення (JPEG, PNG, GIF, WebP), PDF, HTML та будь-які інші типи файлів. Сервер автоматично визначає тип контенту з переданих даних.

Поля відповіді

Поле cid у відповіді — це постійний ідентифікатор контенту IPFS. sizeMB — це збережений розмір у мегабайтах. Об'єкт uris містить як нативний ipfs:// URI, так і HTTPS-адресу gateway для доступу через браузер.

Перейменування файлу

PUT /files/:cid/name

Оновіть відображувану назву файлу. CID не змінюється — це хеш контенту — змінюється лише мітка, яку ви бачите у своєму списку файлів.

Тіло запиту

Параметр	Тип	Обов'язковий	Опис
name	string	Так	Нова відображувана назва. 1-200 символів. Не повинна містити роздільники шляху (/, \). Назви, що складаються лише з пробілів, відхиляються.

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

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

Відповідь 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

Dashboard

На сторінці Files у меню дій кожного рядка файлу (кнопка з трьома крапками) є пункт Rename. Той самий ефект, код не потрібен.

Список файлів

GET /upload/list

Отримайте список ваших завантажених файлів IPFS за часовий діапазон.

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
from	number	Так	Початок часового діапазону, Unix timestamp у мілісекундах.
to	number	Так	Кінець часового діапазону, Unix timestamp у мілісекундах.

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

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

Відповідь 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

Отримати файл

GET /file/:cid

Отримайте метадані конкретного завантаженого файлу за його CID.

Параметри шляху

Параметр	Тип	Обов'язковий	Опис
cid	string	Так	Ідентифікатор контенту IPFS цього файлу.

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

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Відповідь 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}