CAR Import (DAG Import)

Importeer volledige IPFS DAG's in een enkel verzoek met CAR-bestanden (Content Addressable aRchive). Je CID's blijven exact behouden — geen re-chunking of re-hashing.

Een CAR-bestand uploaden naar IPFS Ninja

Een CAR-bestand verpakt een volledige IPFS-directorystructuur of DAG in een enkel draagbaar archief. Elk blok wordt opgeslagen met zijn oorspronkelijke CID, zodat de service alles ongewijzigd importeert. Dit betekent:

• CID-behoud — bereken CID's lokaal, verifieer dat de service exact dezelfde CID retourneert
• Batch-upload — upload honderden bestanden in één verzoek in plaats van één voor één
• Providermigratie — exporteer een DAG van een andere provider, importeer naar IPFS Ninja met identieke CID's
• Aangepaste DAG's — upload elke IPLD-datastructuur rechtstreeks

Uploaden via het Dashboard

Twee drag-and-drop-paden op /upload komen uit bij dezelfde importflow — geen code nodig:

• Sleep een .car-bestand. De uploadzone detecteert de extensie automatisch, toont een banner "CAR archive detected", en de verzendknop wordt "Import <filename> as CAR". De eigen root-CID van het archief blijft behouden.
• Sleep een map. Het dashboard verpakt de map tot een UnixFS-DAG in je browser (met ipfs-unixfs-importer en de moderne chunker van 1 MiB volgens IPIP-0499) en uploadt het resulterende CAR-bestand via hetzelfde pad. De root-CID is een bafybei…-directory die oplost op /ipfs/{cid}/{subpath}.

Beide gebruiken de presigned-PUT-flow voor alles boven een paar MB — de bestandsgrootte-limiet is 5 GB per CAR.

REST API

POST /upload/new

Zelfde endpoint als reguliere uploads — voeg car: true toe om een CAR-import aan te geven.

Verzoekinhoud

Parameter	Type	Vereist	Beschrijving
content	string	Ja	Base64-gecodeerd CAR-bestand
car	boolean	Ja	Zet op true om CAR-import in te schakelen
description	string	Nee	Korte beschrijving van de import
folderId	string	Nee	Map-ID om de geïmporteerde content in te organiseren
metadata	object	Nee	Aangepaste sleutel-waardeparen (dezelfde regels als reguliere uploads)

Voorbeeld: een CAR-bestand importeren met curl

Stap 1: Maak een CAR-bestand van een lokale directory met ipfs-car:

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

Stap 2: Upload het CAR-bestand:

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\"
  }"

Voorbeeld: een CAR-bestand importeren met 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);

Voorbeeld: een CAR-bestand importeren met 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"])

Respons 200 OK

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

Hoe het tellen van bestanden werkt

Elk bestand in de CAR telt individueel mee voor het bestandslimiet van je plan. Een CAR met 12 bestanden gebruikt 13 slots (12 onderliggende bestanden + 1 root-CAR-item). Een CAR met één bestand telt als 1 slot.

• Opslag wordt eenmalig in rekening gebracht op het root-CAR-item (de volledige CAR-bestandsgrootte)
• Individuele onderliggende bestanden verschijnen in je bestandslijst met de root-CID in hun metadata (carParentCid) zodat je ze kunt groeperen
• Maximaal 1000 bestanden per CAR-import — grotere DAG's moeten worden opgesplitst over meerdere imports

Als het importeren van de CAR het bestandsaantal van je plan zou overschrijden, wordt het verzoek geweigerd met een 402-fout en wordt de content automatisch losgekoppeld:

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

S3-compatibele API

Gebruik de x-amz-meta-import: car-header bij een PutObject-verzoek om een CAR-bestand via de S3 API te importeren.

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" }   // ← activeert CAR-import
}));

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

MCP-server

De ipfs_import_car-tool is beschikbaar in de 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...

CAR-bestanden aanmaken

Vanuit een directory (aanbevolen)

Gebruik de ipfs-car CLI-tool:

# 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

Vanuit een draaiende IPFS-node

Exporteer elke CID als een CAR-bestand met de Kubo CLI:

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

Programmatisch met JavaScript

Gebruik de @ipld/car-bibliotheek:

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);

CID-integriteit verifiëren

Het belangrijkste voordeel van CAR-import is CID-behoud. Je kunt verifiëren dat de root-CID overeenkomt vóór en na de upload:

# 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"
# ✓ CID's komen overeen — content exact geïmporteerd zoals lokaal gebouwd

Migreren vanaf een andere provider

Vanaf 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}"

Vanaf 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}"

Limieten

Limiet	Waarde
Maximale CAR-bestandsgrootte	100 MB
Maximaal enkele root	Moet minstens één root-CID hebben
CAR-formaat	CARv1 (universeel ondersteund)
Beschikbaarheid	Alle plannen (Dharma, Bodhi, Nirvana)

Opslag- en bestandsaantallimieten van je plan zijn van toepassing. De geïmporteerde DAG telt als één bestandsvermelding en de CAR-bestandsgrootte wordt afgetrokken van je opslagquotum.

Probleemoplossing

"invalid CAR file: too small"

De geüploade content is kleiner dan 40 bytes, wat te klein is om een geldig CAR-bestand te zijn. Zorg ervoor dat je de volledige base64-gecodeerde CAR-content verstuurt.

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

Het gedecodeerde CAR-bestand overschrijdt 100 MB. Splits je content in meerdere kleinere CAR-bestanden met het carbites-pakket, of upload bestanden afzonderlijk.

"dag/import did not return a root CID"

De IPFS-node kon het CAR-bestand niet verwerken. Controleer of het bestand een geldig CARv1-archief is:

ipfs-car roots my-archive.car

Als dit commando mislukt, is het CAR-bestand beschadigd. Genereer het opnieuw met ipfs-car pack of ipfs dag export.

"not enough storage"

De opslaglimiet van je plan is bereikt. Verwijder ongebruikte bestanden of upgrade je plan op ipfs.ninja/pricing.