Fijación

Fija contenido IPFS existente en tu cuenta. Cuando fijas un CID, nuestro cluster obtiene el contenido de la red IPFS y lo mantiene disponible de forma permanente.

Fijar por CID

POST /pin

Parámetro	Tipo	Requerido	Descripción
cid	string	Sí	Identificador de contenido IPFS. Se acepta cualquier formato: CIDv0 (Qm…), CIDv1 en base32 (bafk…, bafy…, y otros codecs).
description	string	No	Descripción corta para tu referencia.
metadata	object	No	Pares clave-valor personalizados para adjuntar al pin. 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.
multiaddresses	string[]	No	Indicaciones opcionales de swarm-connect. Hasta 5 multiaddresses libp2p de peers que alojan el CID. Nuestro cluster ejecuta swarm connect contra cada una en paralelo antes de la fijación, de modo que el contenido en peers privados / que no están en la DHT es alcanzable sin esperar al descubrimiento por DHT. Mejor esfuerzo — una conexión fallida no hace fallar la fijación. Consulta Fijar desde un nodo privado.

Ejemplo de solicitud

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Respuesta 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Para DAGs grandes (>500 bloques o >50 MB), la respuesta incluye una bandera async: true:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Fijar desde un nodo privado

Si el CID que quieres fijar vive en un peer que no participa en la DHT pública — un nodo de staging privado, una máquina autoalojada en una VPN, o una estación de trabajo detrás de NAT — el flujo de fijación por defecto no lo encontrará. Pasar uno o más multiaddresses le indica a nuestro cluster exactamente dónde buscar.

Ejecutamos ipfs swarm connect <multiaddr> para cada indicación en paralelo antes de que se ejecute la fijación. Si la conexión tiene éxito, la obtención del DAG de la fijación puede hablar directamente con tu peer en lugar de buscar en la DHT. Si falla, la fijación continúa igualmente contra la red pública (semántica de mejor esfuerzo).

Ejemplo: fijar desde un peer específico

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

La respuesta incluye el estado por cada indicación

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Formas de multiaddress aceptadas

Se admiten las formas comunes: transportes /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocolos /tcp o /udp; actualizaciones opcionales /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. La multiaddress debe terminar con /p2p/<peerId>. Límite: hasta 5 indicaciones por fijación.

Obtener la multiaddress de tu nodo

En el peer desde el que quieres fijar, ejecuta ipfs id y copia cualquiera de las entradas de Addresses que termine en /p2p/<PeerID>. Prefiere direcciones públicas enrutables (/ip4/YOUR_PUBLIC_IP/…) o basadas en DNS (/dnsaddr/your.domain/…) para que nuestro cluster pueda alcanzar el peer desde AWS.

Fijar directorios muy grandes

POST /pin es para contenido que ya vive en la red IPFS — el cluster obtiene el DAG bloque a bloque desde los peers, lo cual puede tomar varios minutos para directorios con más de 1.000 archivos. Durante esa ventana de obtención, algunos archivos hijos pueden no estar aún disponibles localmente y las solicitudes al gateway sobre ellos pueden agotar el tiempo de espera. Una vez que el status del padre cambia a pinned, cada hijo está disponible localmente y accesible a través de tu gateway.

Si tienes los archivos localmente (en lugar de solo un CID), prefiere la importación CAR para colecciones NFT o conjuntos de datos grandes — sube el DAG completo a IPFS Ninja en una sola solicitud atómica, por lo que no hay ventana de obtención ni estado de fijación parcial. Crea un CAR con:

npx ipfs-car pack ./my-collection -o collection.car

Luego impórtalo mediante POST /upload/new con car: true.

TIP

La fijación es asíncrona. La respuesta se devuelve inmediatamente con estado pinning. Consulta el endpoint de estado para verificar cuándo se completa la fijación.

Verificar Estado de Fijación

GET /pin/:cid

Parámetro	Tipo	Requerido	Descripción
cid	string	Sí	El CID que estás verificando.

Respuesta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Valores de estado

Estado	Significado
pinning	El contenido se está obteniendo de la red IPFS. Consulta de nuevo en unos segundos.
pinned	El contenido está fijado y disponible a través de tu cuenta y gateway.
failed	El contenido no pudo encontrarse en la red IPFS. El CID puede ser inválido o el contenido ya no está disponible.

Cómo funciona la fijación

1. Envías un CID mediante POST /pin
2. Nuestro cluster IPFS busca en la red los nodos que tienen el contenido
3. El cluster descarga y fija el contenido localmente
4. Una vez fijado, el archivo aparece en tu lista de archivos y es accesible a través del gateway
5. El uso de almacenamiento se registra cuando la fijación se completa

WARNING

El tiempo de fijación depende del tamaño del archivo y la disponibilidad en la red. Los archivos pequeños normalmente se fijan en segundos. Los archivos grandes o el contenido fijado con poca frecuencia pueden tardar minutos.

Almacenamiento

El contenido fijado cuenta para el límite de almacenamiento de tu plan. El tamaño del archivo se registra cuando la fijación se completa. Si te acercas a tu límite de almacenamiento, puedes liberar espacio eliminando archivos no utilizados o actualizar tu plan para obtener más capacidad.