Bestanden

Upload, lijst en haal bestanden op via IPFS. Zie authenticatie voor het instellen van je API-sleutel, en foutafhandeling voor de HTTP-statuscodes die deze endpoints kunnen retourneren.

Bestand uploaden

POST /upload/new

Upload elk bestand naar IPFS. Het bestand wordt vastgezet en een permanente CID wordt geretourneerd.

Verzoekinhoud

Parameter	Type	Vereist	Beschrijving
content	string | object	Ja	JSON-object/array, of base64-gecodeerde bestandsdata (afbeeldingen, PDF's, HTML, of elk ander bestandstype). Voor CAR-imports: base64-gecodeerd CAR-bestand.
car	boolean	Nee	Zet op true om een CAR-bestand te importeren (DAG-import). Behoudt exacte CID's.
description	string	Nee	Korte beschrijving van de geüploade content.
metadata	object	Nee	Aangepaste sleutel-waardeparen om aan het bestand te koppelen. Max. 10 sleutels. Sleutels moeten alfanumeriek zijn of underscores bevatten, 1-64 tekens. Waarden moeten strings zijn, max. 256 tekens elk. Totale metadatagrootte mag niet groter zijn dan 4 KB.

Voorbeeldverzoek

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

Een afbeelding uploaden (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"
  })
});

Respons 200 OK

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

CIDv1 standaard

Nieuwe uploads retourneren moderne CIDv1 (bafk… voor kleine content in één blok, bafy… voor grotere bestanden en directory's) volgens het IPIP-0499 unixfs-v1-2025-profiel — 1 MiB-chunks met raw leaves. Legacy Qm…-CID's van eerdere uploads blijven volledig oplosbaar en werken bij elk endpoint.

Dashboard-alternatief

De /upload-pagina van het dashboard accepteert drag-and-drop voor bestanden, mappen (verpakt tot een UnixFS-directory in de browser), en .car-archieven — allemaal via hetzelfde endpoint. Zie CAR-import voor meer over het CAR-pad.

Ondersteunde bestandstypen

De API accepteert JSON-objecten en -arrays rechtstreeks, plus base64-gecodeerde binaire bestanden: afbeeldingen (JPEG, PNG, GIF, WebP), PDF's, HTML en elk ander bestandstype. De server detecteert het inhoudstype automatisch op basis van de payload.

Responsvelden

De cid in de respons is de permanente IPFS-content-identifier. sizeMB is de opgeslagen grootte in megabytes. Het uris-object bevat zowel de native ipfs://-URI als een HTTPS-gateway-URL voor toegang via de browser.

Bestand hernoemen

PUT /files/:cid/name

Werk de weergavenaam van een bestand bij. De CID verandert niet — het is een hash van de content — alleen het label dat je in je bestandslijst ziet.

Verzoekinhoud

Parameter	Type	Vereist	Beschrijving
name	string	Ja	Nieuwe weergavenaam. 1-200 tekens. Mag geen padscheidingstekens bevatten (/, \). Namen die alleen uit witruimte bestaan worden geweigerd.

Voorbeeldverzoek

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

Respons 200 OK

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

Dashboard

De pagina Bestanden heeft een Hernoemen-item in het actiemenu (drie-puntjes-knop) van elke bestandsrij. Zelfde effect, geen code nodig.

Bestanden oplijsten

GET /upload/list

Haal een lijst op van je geüploade IPFS-bestanden binnen een tijdsbereik.

Queryparameters

Parameter	Type	Vereist	Beschrijving
from	number	Ja	Begin van het tijdsbereik, Unix-timestamp in milliseconden.
to	number	Ja	Einde van het tijdsbereik, Unix-timestamp in milliseconden.

Voorbeeldverzoek

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

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

Bestand ophalen

GET /file/:cid

Haal metadata op voor een specifiek geüpload bestand via zijn CID.

Padparameters

Parameter	Type	Vereist	Beschrijving
cid	string	Ja	De IPFS-content-identifier van het bestand.

Voorbeeldverzoek

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

Respons 200 OK

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