Pastas

As pastas organizam os teus ficheiros carregados no painel. São apenas metadados por predefinição — os ficheiros mantêm os seus próprios CIDs e não são movidos no IPFS — mas também podes criar um instantâneo de uma pasta para a materializar como um diretório UnixFS real e obter um único CID para tudo.

Quando criar um instantâneo de uma pasta

Um instantâneo de pasta é um único CID de diretório IPFS que contém todos os ficheiros da pasta, endereçáveis por nome. Com ele podes:

• Partilhar a pasta inteira através de um único URL: https://ipfs.ninja/ipfs/{dirCid}/
• Resolver https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (ou em qualquer outro gateway) diretamente
• Colocar o CID num contenthash ENS para alojar um site estático
• Usá-lo como CID base de uma coleção de NFTs, para que cada token referencie ipfs://{dirCid}/<id>.json
• Fixar o diretório em qualquer outro lugar — todos os gateways IPFS do mundo sabem resolver um CID de diretório UnixFS

Os instantâneos são endereçados por conteúdo: conteúdos de pasta idênticos produzem sempre o mesmo CID. Voltar a criar um instantâneo de uma pasta que não alteraste devolve o mesmo CID de antes. Adicionar/remover/mudar o nome de um ficheiro produz um novo CID; o CID anterior continua fixado e resolúvel enquanto não eliminares os seus ficheiros.

Criar pasta

POST /folders

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome a apresentar.
parentFolderId	string | null	Não	ID da pasta-mãe para pastas aninhadas. Omite para uma pasta de nível raiz.

Exemplo

curl -X POST https://api.ipfs.ninja/folders \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My NFT collection" }'

Devolve:

{
  "folderId": "1f8e2c3a-…",
  "name": "My NFT collection",
  "parentFolderId": null,
  "createdAt": 1746360000000
}

As pastas recém-criadas não têm instantâneo. O campo latestSnapshot aparece na pasta assim que chamares POST /folders/{id}/snapshot (ver abaixo) e nas respostas seguintes de GET /folders.

Listar pastas

GET /folders

Devolve todas as pastas da tua conta, tanto de nível raiz como aninhadas, com o CID do último instantâneo de cada uma (se existir).

[
  {
    "folderId": "1f8e2c3a-…",
    "name": "My NFT collection",
    "parentFolderId": null,
    "createdAt": 1746360000000,
    "fileCount": 42,
    "latestSnapshot": {
      "cid": "QmRZx5…",
      "takenAt": 1746421000000,
      "fileCount": 42
    }
  }
]

fileCount reflete o conteúdo atual da pasta; latestSnapshot.fileCount reflete o conteúdo no momento do último instantâneo. Se forem diferentes, o CID do instantâneo continua a resolver, mas está desatualizado — cria um novo instantâneo para o atualizar.

Mover um ficheiro para uma pasta

PUT /files/{cid}/move

Parâmetro	Tipo	Obrigatório	Descrição
folderId	string | null	Sim	ID da pasta de destino, ou null para mover o ficheiro para a raiz.

curl -X PUT https://api.ipfs.ninja/files/Qm.../move \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "folderId": "1f8e2c3a-…" }'

Criar um instantâneo de uma pasta (obter um CID de diretório UnixFS)

POST /folders/{folderId}/snapshot

Materializa a pasta como um diretório UnixFS real no cluster IPFS e fixa o resultado. Devolve um único CID para a pasta inteira. Os nomes dos filhos vêm do fileName de cada ficheiro; as duplicações são resolvidas automaticamente.

Não é necessário corpo no pedido; o parâmetro de caminho identifica a pasta.

Exemplo

curl -X POST https://api.ipfs.ninja/folders/1f8e2c3a-.../snapshot \
  -H "X-Api-Key: bws_your_api_key_here"

Devolve:

{
  "ok": true,
  "folderId": "1f8e2c3a-…",
  "cid": "QmRZx5VgFHDsG7ECvaKkZBS4ydmkdAkDyaKyF71RYvh8",
  "fileCount": 42,
  "sizeBytes": 8421376,
  "takenAt": 1746421000000,
  "ipfsUrl": "https://ipfs.ninja/ipfs/QmRZx5.../"
}

O CID também é guardado na linha da pasta, pelo que chamadas seguintes a GET /folders o devolvem como latestSnapshot.cid sem ser necessário criar outro instantâneo.

Resolver um instantâneo

Assim que um instantâneo é fixado, o CID do diretório resolve através de qualquer gateway IPFS. O padrão de URL mais simples:

https://ipfs.ninja/ipfs/{dirCid}/         → listagem do diretório
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → esse ficheiro específico

O cluster fixa de forma recursiva, pelo que os filhos também ficam resolúveis — mesmo que mais tarde elimines o ficheiro original da tua conta, a cópia do instantâneo sobrevive porque é uma fixação separada que percorre o diretório recursivamente.

Voltar a criar instantâneos

Voltar a criar um instantâneo de uma pasta inalterada devolve o mesmo CID — os CIDs de diretório são endereçados por conteúdo, pelo que conteúdos idênticos produzem sempre o mesmo hash, e a chamada de fixação do cluster reconhece a duplicação e não faz nada do seu lado.

Nota: o próprio percurso de criação do instantâneo não é gratuito, mesmo quando o resultado é o mesmo CID. Cada chamada lê de volta os bytes de cada ficheiro a partir do IPFS e volta a carregá-los como multiparte para o endpoint /add do cluster — é aí que acontece o envolvimento com o diretório. Para pastas típicas (≤100 ficheiros pequenos) isto continua a demorar poucos segundos; para pastas muito grandes, prefere chamar o instantâneo apenas quando o conteúdo realmente mudou.

Chamar o instantâneo depois de adicionares ou removeres ficheiros produz um CID diferente; o anterior continua a resolver enquanto não eliminares os seus ficheiros subjacentes.

Limites

• A pasta tem de conter pelo menos um ficheiro. Pastas vazias devolvem 400 — folder is empty.
• Os caracteres do nome do ficheiro são codificados em URL no carregamento multiparte que o Kubo aceita; os URLs de gateway podem precisar de codificação percent-encoding para espaços ou caracteres não ASCII nos nomes dos teus ficheiros.
• Os instantâneos contam para o total de fixações do teu plano exatamente uma vez por CID único — os blocos de ficheiros são deduplicados, pelo que o instantâneo maioritariamente só acrescenta um pequeno nó de diretório sobre ficheiros que já fixas.

Atualizar uma pasta

PUT /folders/{folderId}

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Não	Novo nome a apresentar.
parentFolderId	string | null	Não	Muda a pasta-mãe da pasta. null move-a para a raiz.

Eliminar uma pasta

DELETE /folders/{folderId}

Elimina a pasta e propaga-se recursivamente por todos os ficheiros e subpastas que contém. Sujeito à mesma proteção de segurança para CIDs partilhados que as eliminações de ficheiros individuais — se outros utilizadores ainda fixarem um CID que carregaste, o teu unpin não o remove para eles.

{
  "deleted": true,
  "filesDeleted": 42,
  "foldersDeleted": 3
}

Configurar CORS S3 para uma pasta / bucket

As pastas expostas através da API compatível com S3 funcionam como buckets. Se estás a usar essa API a partir de JavaScript no browser, precisas de regras de CORS no bucket para que os preflights do browser passem. Duas superfícies equivalentes persistem no mesmo armazenamento:

• PUT /folders/{folderId}/cors — este endpoint REST, autenticado por JWT (usado pelo painel)
• Subrecurso S3 PUT /{bucket}?cors — autenticado por SigV4 (usado pelos SDKs da AWS, ver s3-compatibility.md)

O PUT neste endpoint também reserva o nome da pasta como bucket globalmente único caso ainda não tenha sido reservado.

PUT /folders/{folderId}/cors

Define as regras de CORS para o bucket S3 da pasta. Até 5 regras por bucket, 64 KB no total.

Parâmetro	Tipo	Obrigatório	Descrição
rules	CorsRule[]	Sim	Array de regras de CORS no formato AWS (ver abaixo). Não pode estar vazio.
bucketName	string	Não	Nome explícito do bucket S3. Por predefinição usa o nome a apresentar da pasta. Se o nome pretendido já estiver reservado globalmente, passa aqui uma alternativa.

Cada CorsRule:

Campo	Tipo	Obrigatório	Descrição
AllowedOrigins	string[]	Sim	Origens autorizadas a enviar pedidos. Suporta wildcards (https://*.myapp.com). Usa * para qualquer origem.
AllowedMethods	string[]	Sim	Um ou mais de GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Não	Cabeçalhos que os browsers podem incluir nos pedidos. Predefinição: nenhum. Usa ["*"] para permitir todos (recomendado para o AWS SDK v3, que envia Authorization, x-amz-*, etc.).
ExposeHeaders	string[]	Não	Cabeçalhos de resposta tornados legíveis pelo JavaScript do browser. Inclui ETag e x-amz-meta-cid se a tua aplicação precisar do CID devolvido.
MaxAgeSeconds	number	Não	Durante quanto tempo os browsers guardam o preflight em cache. 0-86400. Predefinição 3600.
ID	string	Não	Etiqueta de texto livre para a regra.

Exemplo de pedido

curl -X PUT https://api.ipfs.ninja/folders/17f6dfd8-519c-4d0e-8f3a-5988a1d34ef2/cors \
  -H "Authorization: Bearer $COGNITO_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [{
      "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"],
      "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      "MaxAgeSeconds": 3600
    }]
  }'

Resposta 200 OK

{ "success": true, "rules": [ { "AllowedOrigins": ["https://myapp.com", "http://localhost:3000"], "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"], "AllowedHeaders": ["*"], "ExposeHeaders": ["ETag", "x-amz-meta-cid", "x-amz-request-id"], "MaxAgeSeconds": 3600 } ] }

GET /folders/{folderId}/cors

Devolve as regras de CORS atuais e o nome do bucket (se reservado).

{
  "rules": [ … ],
  "bucketName": "my-project"
}

DELETE /folders/{folderId}/cors

Remove todas as regras de CORS. Os preflights do browser contra o bucket falharão até serem definidas novas regras.

Alternativa: painel

Na página Ficheiros, o menu de ações de cada pasta tem uma opção S3 CORS que abre um editor baseado em formulário. Mesmo armazenamento subjacente que este endpoint REST e que PutBucketCors via API S3.