Arquivos

Envie, liste e recupere arquivos no IPFS.

Enviar Arquivo

POST /upload/new

Envie qualquer arquivo para o IPFS. O arquivo é fixado e um CID permanente é retornado.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
content	string | object	Sim	Objeto/array JSON, ou dados de arquivo codificados em base64 (imagens, PDFs, HTML ou qualquer tipo de arquivo). Para importações CAR, arquivo CAR codificado em base64.
car	boolean	Não	Defina como true para importar um arquivo CAR (importação de DAG). Preserva os CIDs exatos.
description	string	Não	Descrição curta do conteúdo enviado.
metadata	object	Não	Pares chave-valor personalizados para anexar ao arquivo. Máximo de 10 chaves. As chaves devem ser alfanuméricas ou underscore, de 1 a 64 caracteres. Os valores devem ser strings, com no máximo 256 caracteres cada. O tamanho total dos metadados não deve exceder 4 KB.

Exemplo de requisição

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

Enviando uma imagem (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"
  })
});

Resposta 200 OK

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

CIDv1 por padrão

Novos uploads retornam o CIDv1 moderno (bafk… para conteúdo pequeno de bloco único, bafy… para arquivos e diretórios maiores) conforme o perfil IPIP-0499 unixfs-v1-2025 — blocos de 1 MiB com raw leaves. CIDs legados Qm… de uploads anteriores continuam totalmente resolvíveis e seguem funcionando em todos os endpoints.

Alternativa pelo painel

A página /upload do painel aceita arrastar e soltar arquivos, pastas (empacotadas em um diretório UnixFS no navegador) e arquivos .car — tudo passando por este mesmo endpoint. Veja Importação de CAR para detalhes sobre o caminho CAR.

Renomear um Arquivo

PUT /files/:cid/name

Atualiza o nome de exibição mostrado em um arquivo. O CID não muda — é um hash do conteúdo — apenas o rótulo que você vê na sua lista de arquivos.

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
name	string	Sim	Novo nome de exibição. De 1 a 200 caracteres. Não deve conter separadores de caminho (/, \). Nomes contendo apenas espaços em branco são rejeitados.

Exemplo de requisição

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

Resposta 200 OK

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

Painel

A página Arquivos tem uma opção Renomear no menu de ações de cada linha de arquivo (botão de três pontos). Mesmo efeito, sem precisar de código.

Listar Arquivos

GET /upload/list

Recupera uma lista dos seus arquivos IPFS enviados dentro de um intervalo de tempo.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
from	number	Sim	Início do intervalo de tempo, timestamp Unix em milissegundos.
to	number	Sim	Fim do intervalo de tempo, timestamp Unix em milissegundos.

Exemplo de requisição

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

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

Obter Arquivo

GET /file/:cid

Recupera os metadados de um arquivo enviado específico pelo seu CID.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
cid	string	Sim	O identificador de conteúdo IPFS do arquivo.

Exemplo de requisição

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

Resposta 200 OK

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