Public API

Die Public API ist eine Machine-to-Machine-HTTP-API für Datei-Uploads, das Polling ihres Processing-Status und die Suche in der Bibliothek. Sie steht Teams mit einem aktiven Pro-Abonnement zur Verfügung.

Endpoints im Überblick

Methode	Pfad	Berechtigung	Zweck
`POST`	`/api/v1/files`	`upload`	Eine Datei bis 100 MiB hochladen.
`GET`	`/api/v1/files/:fileId`	`upload` oder `search`	Dateimetadaten und Status lesen.
`POST`	`/api/v1/search`	`search`	Die Team-Bibliothek durchsuchen und filtern.

Die Basis-URL besteht aus der Adresse deiner New-Archive-Installation und /api/v1:

text

https://your-host/api/v1

Requests und Responses verwenden JSON. Nur Datei-Uploads verwenden multipart/form-data. Die maschinenlesbare OpenAPI-3.1-Spezifikation eignet sich zur Generierung von Client-Code und für Contract-Tests.

Schnellstart

Erstelle unter Einstellungen → API-Schlüssel einen API-Key und speichere Host und Secret in Umgebungsvariablen. Das Secret beginnt mit na_ und wird nur einmal angezeigt.

bash

export NEW_ARCHIVE_URL="https://your-host"
export NEW_ARCHIVE_API_KEY="na_your_key"

Datei hochladen:

bash

curl --fail-with-body \
  -X POST "$NEW_ARCHIVE_URL/api/v1/files" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY" \
  -F "file=@sunset.jpg"

Die API antwortet mit 202 Accepted, während das Processing im Hintergrund weiterläuft:

json

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

Bibliothek durchsuchen:

bash

curl --fail-with-body \
  -X POST "$NEW_ARCHIVE_URL/api/v1/search" \
  -H "Authorization: Bearer $NEW_ARCHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Sonnenuntergang am Strand","limit":10}'

Anleitungen

Authentifizierung beschreibt API-Keys, Scopes, Rollenberechtigungen, Pro-Zugang und Rate Limits.
Dateien hochladen erklärt Uploads, Response-Felder und das Polling des Processing-Status.
Suchen beschreibt Ranking, alle Filter und Cursor-Pagination.
Upload-Limits erklärt das aktuelle 100-MiB-Limit und den Unterschied zum App-Uploader.
Fehler dokumentiert das stabile Error-Format, alle Error-Codes und Retry-Verhalten.

Aktuelle Grenzen

Version 1 bietet kein OAuth, keine Downloads von Originaldateien, keine Facettenlisten, keine Similarity Search und keinen öffentlichen Direct-to-S3-Multipart-Upload mit Presigned URLs. Fertige Dateien enthalten kurzlebige Signed URLs für Thumbnails. Dateien über 100 MiB müssen derzeit über die App hochgeladen werden.

ZurückTastaturbefehle WeiterAuthentifizierung