CAR Import (DAG Import)

Importa interi DAG IPFS in una singola richiesta utilizzando file CAR (Content Addressable aRchive). I tuoi CID vengono preservati esattamente — nessun re-chunking o re-hashing.

Cos'è un file CAR?

Un file CAR racchiude un intero albero di directory o DAG IPFS in un singolo archivio portatile. Ogni blocco viene memorizzato con il suo CID originale, quindi il servizio importa tutto così com'è. Questo significa:

• Preservazione dei CID — calcola i CID localmente, verifica che il servizio restituisca esattamente lo stesso CID
• Caricamento in blocco — carica centinaia di file in una sola richiesta invece che uno alla volta
• Migrazione del provider — esporta un DAG da un altro provider, importalo su IPFS Ninja con CID identici
• DAG personalizzati — carica qualsiasi struttura dati IPLD direttamente

Caricamento tramite Dashboard

Due percorsi drag-and-drop su /upload raggiungono lo stesso flusso di importazione — nessun codice richiesto:

• Trascina un file .car. La zona di caricamento rileva automaticamente l'estensione, mostra un banner "CAR archive detected" e il pulsante di invio diventa "Import <filename> as CAR". Il CID root dell'archivio viene preservato.
• Trascina una cartella. La dashboard impacchetta la cartella in un DAG UnixFS direttamente nel tuo browser (usando ipfs-unixfs-importer con il moderno chunker da 1 MiB secondo IPIP-0499) e carica il CAR risultante attraverso lo stesso percorso. Il CID root è una directory bafybei… che si risolve su /ipfs/{cid}/{subpath}.

Entrambi i percorsi utilizzano il flusso presigned-PUT per contenuti superiori a pochi MB — il limite di dimensione del file è 5 GB per CAR.

REST API

POST /upload/new

Lo stesso endpoint dei caricamenti normali — aggiungi car: true per indicare un'importazione CAR.

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
content	string	Sì	File CAR codificato in Base64
car	boolean	Sì	Imposta su true per abilitare l'importazione CAR
description	string	No	Breve descrizione dell'importazione
folderId	string	No	ID della cartella in cui organizzare il contenuto importato
metadata	object	No	Coppie chiave-valore personalizzate (stesse regole dei caricamenti normali)

Esempio: Importare un file CAR con curl

Passo 1: Crea un file CAR da una directory locale usando ipfs-car:

npx ipfs-car pack ./my-directory -o my-archive.car

Passo 2: Carica il file CAR:

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\": \"$(base64 -w0 my-archive.car)\",
    \"car\": true,
    \"description\": \"My directory import\"
  }"

Esempio: Importare un file CAR con JavaScript

import fs from "fs";

const carBuffer = fs.readFileSync("my-archive.car");
const base64Content = carBuffer.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: base64Content,
    car: true,
    description: "My directory import"
  })
});

const result = await response.json();
console.log("Root CID:", result.cid);
console.log("Gateway:", result.uris.url);

Esempio: Importare un file CAR con Python

import requests
import base64

with open("my-archive.car", "rb") as f:
    car_content = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.ipfs.ninja/upload/new",
    headers={
        "X-Api-Key": "bws_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "content": car_content,
        "car": True,
        "description": "My directory import"
    }
)

result = response.json()
print("Root CID:", result["cid"])
print("Gateway:", result["uris"]["url"])

Risposta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 4.2,
  "car": true,
  "fileCount": 12,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Come funziona il conteggio dei file

Ogni file all'interno del CAR conta individualmente ai fini del limite di file del tuo piano. Un CAR che contiene 12 file utilizza 13 slot (12 file figli + 1 voce CAR root). Un CAR con un solo file conta come 1 slot.

• Lo storage viene addebitato una sola volta sulla voce CAR root (la dimensione completa del file CAR)
• I singoli file figli compaiono nel tuo elenco file con il CID root nei rispettivi metadati (carParentCid), così da poterli raggruppare
• Massimo 1000 file per importazione CAR — i DAG più grandi devono essere suddivisi in più importazioni

Se l'importazione del CAR dovesse superare il limite di numero di file del tuo piano, la richiesta viene rifiutata con un errore 402 e il contenuto viene automaticamente rimosso dal pin (unpin):

{
  "error": "file limit exceeded: this CAR contains 523 files, you have 800/1000. Upgrade your plan."
}

S3-Compatible API

Usa l'header x-amz-meta-import: car in una richiesta PutObject per importare un file CAR tramite l'S3 API.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-archive.car",
  Body: fs.readFileSync("my-archive.car"),
  ContentType: "application/vnd.ipld.car",
  Metadata: { import: "car" }   // ← attiva l'importazione CAR
}));

console.log("Root CID:", result.ETag);

MCP Server

Lo strumento ipfs_import_car è disponibile nel MCP Server (v1.3.0+):

You: Import my-archive.car to IPFS
Claude: [calls ipfs_import_car with base64 content]
     → Root CID: bafybeig... — https://ipfs.ninja/ipfs/bafybeig...

Creare File CAR

Da una directory (consigliato)

Usa lo strumento CLI ipfs-car:

# Install
npm install -g ipfs-car

# Pack a directory into a CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Check the root CID before uploading
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Da un nodo IPFS in esecuzione

Esporta qualsiasi CID come file CAR usando il Kubo CLI:

ipfs dag export QmXyz... > my-archive.car

Programmaticamente con JavaScript

Usa la libreria @ipld/car:

import { CarWriter } from "@ipld/car";
import { CID } from "multiformats/cid";
import * as raw from "multiformats/codecs/raw";
import { sha256 } from "multiformats/hashes/sha2";

// Create blocks
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// Write CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Collect output
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Verifica dell'Integrità dei CID

Il vantaggio principale dell'importazione CAR è la preservazione dei CID. Puoi verificare che il CID root corrisponda prima e dopo il caricamento:

# 1. Pack directory and note the root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Upload to IPFS Ninja
curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 collection.car)\", \"car\": true}" \
  | jq .cid
# "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
# ✓ I CID corrispondono — il contenuto è stato importato esattamente come creato localmente

Migrazione da un Altro Provider

Da Pinata

# Export from Pinata using IPFS gateway
ipfs dag export QmYourCID > export.car

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Da Filebase

# Filebase supports CAR export via their S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Limiti

Limite	Valore
Dimensione massima file CAR	100 MB
Root singola massima	Deve avere almeno un CID root
Formato CAR	CARv1 (supportato universalmente)
Disponibilità	Tutti i piani (Dharma, Bodhi, Nirvana)

Si applicano i limiti di archiviazione e numero di file del tuo piano. Il DAG importato conta come una singola voce file, e la dimensione del file CAR viene detratta dalla tua quota di archiviazione.

Risoluzione dei Problemi

"invalid CAR file: too small"

Il contenuto caricato è inferiore a 40 byte, troppo piccolo per essere un file CAR valido. Assicurati di inviare il contenuto CAR completo codificato in Base64.

"File too large. Maximum upload size is 100 MB."

Il file CAR decodificato supera i 100 MB. Dividi il contenuto in più file CAR più piccoli usando il pacchetto carbites, oppure carica i file singolarmente.

"dag/import did not return a root CID"

Il nodo IPFS non è riuscito a elaborare il file CAR. Verifica che il file sia un archivio CARv1 valido:

ipfs-car roots my-archive.car

Se questo comando fallisce, il file CAR è malformato. Rigeneralo con ipfs-car pack o ipfs dag export.

"not enough storage"

Il limite di archiviazione del tuo piano è stato raggiunto. Elimina i file inutilizzati o aggiorna il tuo piano su ipfs.ninja/pricing.