Ficheiros

Carrega, lista e obtém ficheiros no IPFS. Consulta autenticação para configurar a tua chave API, e tratamento de erros para os códigos de estado HTTP que estes endpoints podem devolver.

Carregar um Ficheiro para o IPFS: 3 Passos

1. Codifica o teu ficheiro em base64 (para imagens/PDFs) ou passa um objeto JSON diretamente.
2. Faz um POST para /upload/new com a tua chave API no cabeçalho X-Api-Key.
3. Guarda o cid devolvido — identifica permanentemente o teu ficheiro no IPFS.

POST /upload/new

Carrega qualquer ficheiro para o IPFS. O ficheiro é fixado e é devolvido um CID permanente.

Corpo do pedido

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

Exemplo de pedido

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

Carregar 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 predefinição

Os novos carregamentos devolvem o CIDv1 moderno (bafk… para conteúdo pequeno de bloco único, bafy… para ficheiros e diretórios maiores) segundo o perfil IPIP-0499 unixfs-v1-2025 — blocos de 1 MiB com raw leaves. Os CIDs legados Qm… de carregamentos anteriores continuam totalmente resolúveis e continuam a funcionar com todos os endpoints.

Alternativa: painel

A página /upload do painel aceita arrastar e largar para ficheiros, pastas (agrupadas num diretório UnixFS no browser) e arquivos .car — tudo passando pelo mesmo endpoint. Consulta Importação CAR para detalhes sobre o percurso CAR.

Tipos de ficheiro suportados

A API aceita objetos e arrays JSON diretamente, além de ficheiros binários codificados em base64: imagens (JPEG, PNG, GIF, WebP), PDFs, HTML e qualquer outro tipo de ficheiro. O servidor deteta automaticamente o tipo de conteúdo a partir do payload.

Campos da resposta

O cid da resposta é o identificador de conteúdo IPFS permanente. sizeMB é o tamanho armazenado em megabytes. O objeto uris contém tanto o URI nativo ipfs:// como um URL de gateway HTTPS para acesso pelo browser.

Mudar o Nome de um Ficheiro

PUT /files/:cid/name

Atualiza o nome apresentado num ficheiro. O CID não muda — é um hash do conteúdo — apenas a etiqueta que vês na tua lista de ficheiros.

Corpo do pedido

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

Exemplo de pedido

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 Ficheiros tem uma opção Mudar o nome no menu de ações de cada linha de ficheiro (botão de três pontos). Mesmo efeito, sem necessidade de código.

Listar Ficheiros

GET /upload/list

Obtém uma lista dos teus ficheiros IPFS carregados 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 pedido

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 Ficheiro

GET /file/:cid

Obtém os metadados de um ficheiro carregado específico através do seu CID.

Parâmetros de caminho

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

Exemplo de pedido

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