Pastas

As pastas organizam seus arquivos enviados no painel. Por padrão, elas existem apenas como metadados — os arquivos mantêm seus próprios CIDs e não são movidos no IPFS — mas você também pode gerar um snapshot de uma pasta para materializá-la como um diretório UnixFS real e obter um único CID para tudo.

Quando gerar um snapshot de uma pasta

Um snapshot de pasta é um único CID de diretório IPFS que contém todos os arquivos da pasta, endereçáveis por nome. Com ele você pode:

• Compartilhar a pasta inteira com uma única URL: https://ipfs.ninja/ipfs/{dirCid}/
• Resolver https://ipfs.ninja/ipfs/{dirCid}/photo.jpg (ou qualquer outro gateway) diretamente
• Colocar o CID em um contenthash do ENS para hospedar um site estático
• Usá-lo como o CID base de uma coleção de NFTs, de forma que cada token referencie ipfs://{dirCid}/<id>.json
• Fixar o diretório em qualquer outro lugar — todo gateway IPFS no mundo sabe resolver um CID de diretório UnixFS

Snapshots são endereçados por conteúdo: conteúdos de pasta idênticos sempre produzem o mesmo CID. Gerar um novo snapshot de uma pasta que você não alterou retorna o mesmo CID retornado anteriormente. Adicionar/remover/renomear um arquivo produz um novo CID; o CID anterior continua fixado e resolvível enquanto você não excluir os arquivos dele.

Criar pasta

POST /folders

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Nome de exibição.
parentFolderId	string | null	Não	ID da pasta pai para pastas aninhadas. Omita para uma pasta no 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" }'

Retorna:

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

Pastas recém-criadas não têm snapshot. O campo latestSnapshot aparece na pasta assim que você chama POST /folders/{id}/snapshot (veja abaixo) e nas respostas subsequentes de GET /folders.

Listar pastas

GET /folders

Retorna todas as pastas da sua conta, tanto de nível raiz quanto aninhadas, com o CID do último snapshot de cada uma (se houver).

[
  {
    "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 snapshot. Se forem diferentes, o CID do snapshot ainda resolve, mas está desatualizado — gere um novo snapshot para atualizá-lo.

Mover um arquivo 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 arquivo 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-…" }'

Gerar snapshot 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. Retorna um único CID para a pasta inteira. Os nomes dos itens filhos vêm do fileName de cada arquivo; duplicatas são resolvidas automaticamente.

Nenhum corpo de requisição é necessário; 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"

Retorna:

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

O CID também é persistido no registro da pasta, então chamadas subsequentes de GET /folders o retornam como latestSnapshot.cid sem precisar de outro snapshot.

Resolvendo um snapshot

Assim que um snapshot é fixado, o CID de diretório resolve por qualquer gateway IPFS. O padrão de URL mais simples:

https://ipfs.ninja/ipfs/{dirCid}/         → directory listing
https://ipfs.ninja/ipfs/{dirCid}/photo.jpg → that one file

O cluster fixa recursivamente, então os filhos também são resolvíveis — mesmo que você exclua depois o arquivo original da sua conta, a cópia do snapshot sobrevive porque é uma fixação separada que percorre recursivamente o diretório.

Gerando um novo snapshot

Gerar um novo snapshot de uma pasta inalterada retorna o mesmo CID — CIDs de diretório são endereçados por conteúdo, então conteúdos idênticos sempre produzem o mesmo hash, e a chamada de fixação do cluster reconhece a duplicata e não faz nada do seu lado.

Nota: o próprio caminho de snapshot não é gratuito, mesmo quando o resultado é o mesmo CID. Cada chamada lê de volta os bytes de cada arquivo a partir do IPFS e os reenvia como multipart para o endpoint /add do cluster — é aí que ocorre o empacotamento em diretório. Para pastas típicas (≤100 arquivos pequenos) isso ainda é concluído em poucos segundos; para pastas muito grandes, prefira chamar o snapshot apenas quando o conteúdo realmente mudar.

Chamar o snapshot depois de adicionar ou remover arquivos produz um CID diferente; o anterior continua resolvendo enquanto você não excluir os arquivos que o compõem.

Limites

• A pasta precisa conter pelo menos um arquivo. Pastas vazias retornam 400 — folder is empty.
• Os caracteres do nome de arquivo são codificados como URL no upload multipart aceito pelo Kubo; URLs de gateway podem precisar de percent-encoding para espaços ou caracteres não ASCII nos nomes de seus arquivos.
• Snapshots contam para o total de fixações do seu plano exatamente uma vez por CID único — os blocos de arquivo são deduplicados, então o snapshot basicamente adiciona um pequeno nó de diretório sobre arquivos que você já fixa.

Atualizar uma pasta

PUT /folders/{folderId}

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Não	Novo nome de exibição.
parentFolderId	string | null	Não	Reatribui a pasta pai. null move a pasta para a raiz.

Excluir uma pasta

DELETE /folders/{folderId}

Exclui a pasta e propaga recursivamente por todos os arquivos e subpastas que ela contém. Sujeito à mesma proteção de CID compartilhado das exclusões de arquivos individuais — se outros usuários ainda fixam um CID que você enviou, a remoção da sua fixação não o remove para eles.

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

Configurar CORS S3 para uma pasta / bucket

Pastas expostas através da API compatível com S3 funcionam como buckets. Se você estiver usando essa API a partir do JavaScript do navegador, precisa de regras de CORS no bucket para que os preflights do navegador passem. Duas superfícies equivalentes persistem no mesmo armazenamento:

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

O PUT neste endpoint também reivindica o nome da pasta como um bucket globalmente único, caso ainda não tenha sido reivindicado.

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 (veja abaixo). Não pode ser vazio.
bucketName	string	Não	Nome explícito do bucket S3. Por padrão, usa o nome de exibição da pasta. Se o nome desejado já estiver reivindicado globalmente, informe uma alternativa aqui.

Cada CorsRule:

Campo	Tipo	Obrigatório	Descrição
AllowedOrigins	string[]	Sim	Origens permitidas a enviar requisições. Suporta wildcards (https://*.myapp.com). Use * para qualquer origem.
AllowedMethods	string[]	Sim	Um ou mais de GET, HEAD, PUT, POST, DELETE.
AllowedHeaders	string[]	Não	Cabeçalhos que os navegadores podem incluir nas requisições. Padrão: nenhum. Use ["*"] 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 navegador. Inclua ETag e x-amz-meta-cid se seu app precisar do CID retornado.
MaxAgeSeconds	number	Não	Por quanto tempo os navegadores fazem cache do preflight. De 0 a 86400. Padrão 3600.
ID	string	Não	Rótulo de texto livre para a regra.

Exemplo de requisição

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

Retorna as regras de CORS atuais mais o nome do bucket (se reivindicado).

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

DELETE /folders/{folderId}/cors

Remove todas as regras de CORS. Os preflights do navegador contra o bucket falharão (fechado por padrão) até que novas regras sejam definidas.

Alternativa pelo painel

Na página Arquivos, o menu de ações de cada pasta tem uma opção S3 CORS que abre um editor baseado em formulário. Mesmo armazenamento por baixo dos panos deste endpoint REST e do PutBucketCors via API S3.