CAR Import (DAG Import)

Importa DAGs completos de IPFS en una sola solicitud usando archivos CAR (Content Addressable aRchive). Tus CIDs se conservan exactamente — sin re-fragmentación ni re-hashing.

¿Qué es un archivo CAR?

Un archivo CAR empaqueta un árbol de directorios IPFS completo o un DAG en un único archivo portátil. Cada bloque se almacena con su CID original, por lo que el servicio importa todo tal cual. Esto significa:

• Conservación de CID — calcula los CIDs localmente, verifica que el servicio devuelve exactamente el mismo CID
• Carga por lotes — sube cientos de archivos en una sola solicitud en lugar de uno por uno
• Migración de proveedor — exporta un DAG de otro proveedor, impórtalo a IPFS Ninja con CIDs idénticos
• DAGs personalizados — sube cualquier estructura de datos IPLD directamente

Subir a través del Dashboard

Dos rutas de arrastrar y soltar en /upload llegan a este mismo flujo de importación — sin necesidad de código:

• Suelta un archivo .car. La zona de subida detecta automáticamente la extensión, muestra un aviso «CAR archive detected» y el botón de envío se convierte en «Import <filename> as CAR». Se conserva el CID raíz propio del archivo.
• Suelta una carpeta. El dashboard empaqueta la carpeta en un DAG UnixFS en tu navegador (usando ipfs-unixfs-importer con el chunker moderno de 1 MiB según IPIP-0499) y sube el CAR resultante por el mismo camino. El CID raíz es un directorio bafybei… que resuelve en /ipfs/{cid}/{subpath}.

Ambas rutas usan el flujo de PUT prefirmado para cualquier cosa por encima de unos pocos MB — el límite de tamaño de archivo es 5 GB por CAR.

REST API

POST /upload/new

El mismo endpoint que las subidas regulares — añade car: true para indicar una importación CAR.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
content	string	Sí	Archivo CAR codificado en base64
car	boolean	Sí	Establece en true para habilitar la importación CAR
description	string	No	Descripción breve de la importación
folderId	string	No	ID de carpeta para organizar el contenido importado
metadata	object	No	Pares clave-valor personalizados (mismas reglas que las subidas regulares)

Ejemplo: importar un archivo CAR con curl

Paso 1: crea un archivo CAR a partir de un directorio local usando ipfs-car:

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

Paso 2: sube el archivo 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\"
  }"

Ejemplo: importar un archivo 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);

Ejemplo: importar un archivo 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"])

Respuesta 200 OK

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

Cómo funciona el conteo de archivos

Cada archivo dentro del CAR cuenta individualmente para el límite de archivos de tu plan. Un CAR que contiene 12 archivos usa 13 espacios (12 hijos + 1 entrada raíz del CAR). Un CAR de un solo archivo cuenta como 1 espacio.

• El almacenamiento se cobra una vez en la entrada raíz del CAR (el tamaño completo del archivo CAR)
• Los archivos hijos individuales aparecen en tu listado de archivos con el CID raíz en sus metadatos (carParentCid) para que puedas agruparlos
• Máximo 1000 archivos por importación CAR — los DAGs más grandes deben dividirse en varias importaciones

Si importar el CAR excedería el límite de archivos de tu plan, la solicitud se rechaza con un error 402 y el contenido se despina automáticamente:

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

API compatible con S3

Usa el encabezado x-amz-meta-import: car en una solicitud PutObject para importar un archivo CAR a través de la API S3.

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" }   // ← activa la importación CAR
}));

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

MCP Server

La herramienta ipfs_import_car está disponible en el 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...

Creación de archivos CAR

Desde un directorio (recomendado)

Usa la herramienta 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

Desde un nodo IPFS en ejecución

Exporta cualquier CID como archivo CAR usando la CLI de Kubo:

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

Programáticamente con JavaScript

Usa la biblioteca @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);

Verificación de la integridad del CID

El beneficio principal de la importación CAR es la conservación del CID. Puedes verificar que el CID raíz coincide antes y después de la subida:

# 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"
# ✓ CIDs match — content imported exactly as built locally

Migración desde otro proveedor

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

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

Límites

Límite	Valor
Tamaño máximo de archivo CAR	100 MB
Máximo root único	Debe tener al menos un root CID
Formato CAR	CARv1 (universalmente soportado)
Disponibilidad	Todos los planes (Dharma, Bodhi, Nirvana)

Se aplican los límites de almacenamiento y cantidad de archivos de tu plan. El DAG importado cuenta como una entrada de archivo, y el tamaño del archivo CAR se deduce de tu cuota de almacenamiento.

Solución de problemas

"invalid CAR file: too small"

El contenido subido tiene menos de 40 bytes, lo cual es demasiado pequeño para ser un archivo CAR válido. Asegúrate de enviar el contenido CAR completo codificado en base64.

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

El archivo CAR decodificado excede los 100 MB. Divide tu contenido en varios archivos CAR más pequeños usando el paquete carbites, o sube los archivos individualmente.

"dag/import did not return a root CID"

El nodo IPFS no pudo procesar el archivo CAR. Verifica que el archivo sea un archivo CARv1 válido:

ipfs-car roots my-archive.car

Si este comando falla, el archivo CAR está malformado. Regenéralo con ipfs-car pack o ipfs dag export.

"not enough storage"

Se ha alcanzado el límite de almacenamiento de tu plan. Elimina archivos no utilizados o actualiza tu plan en ipfs.ninja/pricing.