Archivos

Sube, lista y recupera archivos en IPFS.

Subir Archivo

POST /upload/new

Sube cualquier archivo a IPFS. El archivo se fija y se devuelve un CID permanente.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
content	string | object	Sí	Objeto/arreglo JSON, o datos de archivo codificados en base64 (imágenes, PDFs, HTML o cualquier tipo de archivo). Para importaciones CAR, archivo CAR codificado en base64.
car	boolean	No	Establece en true para importar un archivo CAR (importación de DAG). Conserva los CIDs exactos.
description	string	No	Descripción corta del contenido subido.
metadata	object	No	Pares clave-valor personalizados para adjuntar al archivo. Máximo 10 claves. Las claves deben ser alfanuméricas o guion bajo, de 1 a 64 caracteres. Los valores deben ser cadenas, máximo 256 caracteres cada uno. El tamaño total de los metadatos no debe exceder 4 KB.

Ejemplo de solicitud

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

Subir una imagen (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"
  })
});

Respuesta 200 OK

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

CIDv1 por defecto

Las nuevas subidas devuelven CIDv1 moderno (bafk… para contenido pequeño de un solo bloque, bafy… para archivos y directorios más grandes) según el perfil IPIP-0499 unixfs-v1-2025 — fragmentos de 1 MiB con raw leaves. Los CIDs Qm… heredados de subidas anteriores siguen siendo totalmente resolubles y continúan funcionando con todos los endpoints.

Alternativa desde el dashboard

La página /upload del dashboard acepta arrastrar y soltar archivos, carpetas (empaquetadas en un directorio UnixFS en el navegador) y archivos .car — todo pasando por este mismo endpoint. Consulta Importación CAR para más detalles sobre la ruta CAR.

Renombrar un Archivo

PUT /files/:cid/name

Actualiza el nombre visible de un archivo. El CID no cambia — es un hash del contenido — solo la etiqueta que ves en tu lista de archivos.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nuevo nombre visible. 1-200 caracteres. No debe contener separadores de ruta (/, \). Se rechazan los nombres compuestos solo por espacios en blanco.

Ejemplo de solicitud

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

Respuesta 200 OK

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

Dashboard

La página Files tiene una opción Rename en el menú de acciones de cada fila de archivo (botón de tres puntos). Mismo efecto, sin necesidad de código.

Listar Archivos

GET /upload/list

Recupera una lista de tus archivos IPFS subidos dentro de un rango de tiempo.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
from	number	Sí	Inicio del rango de tiempo, marca de tiempo Unix en milisegundos.
to	number	Sí	Fin del rango de tiempo, marca de tiempo Unix en milisegundos.

Ejemplo de solicitud

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

Respuesta 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"
    }
  }
]

Obtener Archivo

GET /file/:cid

Recupera los metadatos de un archivo subido específico por su CID.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
cid	string	Sí	El identificador de contenido IPFS del archivo.

Ejemplo de solicitud

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

Respuesta 200 OK

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