Dateien hochladen

POST /api/v1/files lädt eine Datei mit multipart/form-data hoch. Der öffentliche Endpoint akzeptiert derzeit Dateien bis 100 MiB (104.857.600 Bytes). Er benötigt den Scope upload und die Rollenberechtigung files.upload des API-Key-Inhabers.

Request

Feld	Pflicht	Beschreibung
`file`	ja	Die Datei. Dateiname und Content-Type stammen aus diesem Multipart-Part.
`collection_id`	nein	UUID einer Sammlung. Bei einer fehlenden oder nicht zugänglichen Sammlung bleibt die Datei nur in der Bibliothek.

Der Header Content-Length ist erforderlich. Akzeptiert werden image/*, video/*, application/pdf, text/plain und application/octet-stream. Bekannte Bildendungen – darunter übliche RAW-Formate, PSD, TIFF, HEIC und HEIF – werden vor der Validierung anhand des Dateinamens normalisiert.

bash

curl --fail-with-body \
  -X POST "$NEW_ARCHIVE_URL/api/v1/files" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY" \
  -F "file=@sunset.jpg" \
  -F "collection_id=0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b"

Upload-Response

Ein erfolgreicher Upload liefert 202 Accepted. Die Bytes sind gespeichert, während im Hintergrund möglicherweise noch Thumbnails und Daten für den Search-Index erzeugt werden.

json

{
  "id": "0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b",
  "version_id": "0198c9a0-8a12-7e55-9c01-d4b6f7a8e9c0",
  "status": "processing"
}

Uploads über dem Limit liefern 413 payload_too_large. Ein volles Speicherkontingent des Teams liefert 507 quota_exceeded.

Status und Metadaten lesen

GET /api/v1/files/:fileId akzeptiert den Scope upload oder search. Verwende den Endpoint zum Polling eines Uploads oder zum Lesen eines einzelnen Suchergebnisses.

bash

curl --fail-with-body \
  "$NEW_ARCHIVE_URL/api/v1/files/0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY"

json

{
  "id": "0198c9a0-7d3e-7c41-b7a2-3f9d1c2e4a5b",
  "status": "ready",
  "original_name": "sunset.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 2481931,
  "width": 4000,
  "height": 3000,
  "taken_at": "2026-06-30T18:41:02.000Z",
  "created_at": "2026-07-11T09:12:44.201Z",
  "thumbnail_url": "https://storage.example/signed-thumbnail"
}

Feld	Typ	Beschreibung
`id`	string	Stabile Datei-UUID.
`status`	string	`processing`, `ready` oder `failed`.
`original_name`	string	Beim Upload übergebener Dateiname.
`mime_type`	string	Normalisierter Content-Type.
`size_bytes`	number	Größe des gespeicherten Originals in Bytes.
`width`	number oder `null`	Pixelbreite, wenn verfügbar.
`height`	number oder `null`	Pixelhöhe, wenn verfügbar.
`taken_at`	string oder `null`	Aufnahmezeit aus Metadaten im ISO-8601-Format.
`created_at`	string	Upload-Zeitpunkt im ISO-8601-Format.
`thumbnail_url`	string oder `null`	Signed URL für ein Thumbnail, etwa eine Stunde gültig.

Eine unbekannte Datei-ID – oder eine aus einem anderen Team – liefert 404 not_found. Downloads von Originaldateien gehören nicht zu API v1.

Processing-Status pollen

Sende höchstens einen Request pro Sekunde, da jeder Request auf das Rate Limit des API-Keys angerechnet wird.

async function waitForFile(fileId) {
  const url = `${process.env.NEW_ARCHIVE_URL}/api/v1/files/${fileId}`
  for (;;) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.NEW_ARCHIVE_API_KEY}` },
    })
    const body = await response.json()
    if (!response.ok)
      throw new Error(`${body.error.code}: ${body.error.message}`)
    if (body.status !== "processing") return body
    await new Promise((resolve) => setTimeout(resolve, 2000))
  }
}

ZurückAuthentifizierung WeiterSuchen