Fijación

Fija contenido IPFS existente a tu cuenta. Cuando fijas un CID, nuestro cluster busca el contenido en la red IPFS y lo mantiene disponible permanentemente.

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 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	Sugerencias opcionales de conexión swarm. Hasta 5 multiaddresses libp2p de peers que alojan el CID. Nuestro cluster ejecuta swarm connect contra cada uno en paralelo antes de la fijación, de modo que el contenido en peers privados / no-DHT sea alcanzable sin esperar al descubrimiento por DHT. Best-effort — 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 marca 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 un puesto de trabajo detrás de NAT — el flujo de fijación por defecto no lo encontrará. Pasar una o más multiaddresses le indica a nuestro cluster exactamente dónde buscar.

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

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 sugerencia

{
  "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": { … }
}

Formatos de multiaddress aceptados

Se admiten los formatos habituales: transportes /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocolos /tcp o /udp; y las mejoras opcionales /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. La multiaddress debe terminar con /p2p/<peerId>. Límite: hasta 5 sugerencias 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 que puede tardar varios minutos para directorios con más de 1.000 archivos. Durante esa ventana de descarga, algunos archivos hijos pueden no estar aún disponibles localmente, y las solicitudes al gateway hacia ellos pueden agotar el tiempo de espera. Una vez que el status del padre cambia a pinned, todos los hijos están disponibles localmente y accesibles 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 todo el DAG a IPFS Ninja en una sola solicitud atómica, así que no hay ventana de descarga 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 el estado de la 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 está siendo buscado en 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 típicamente se fijan en segundos. Los archivos grandes o el contenido raramente fijado 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 que no uses o actualizar tu plan para obtener más capacidad.