Leitfaden zur Files API

Dateien (in einigen Schemata Ressourcen genannt) enthalten die an Datensätze angehängten Nachweise: Bilder, PDFs, Dokumente und Scanartefakte. Eine Datei kann direkt an einen Datensatz angehängt oder als Wert eines Feldes vom Typ Ressource verwendet werden.

Es gibt zwei Upload-Wege: eine einfache, einmalige POST-Anfrage für kleine Dateien und das fortsetzbare tus-Protokoll für große Dateien. Vollständige Schemata: API-Referenz.

Endpunkte im Überblick

Vorgang	Methode & Pfad
Einfacher Upload	POST /api/v1/files
Fortsetzbarer Upload (tus)	POST /api/v1/files/upload, dann PATCH /api/v1/files/upload/{id}
tus-Uploads abschließen	POST /api/v1/files/finalize
Herunterladen	GET /api/v1/files/{resource_id}/download
Signierte URLs	POST /api/v1/files/urls
Dateien durchsuchen	GET /api/v1/files/search
Dateien auflisten (Cursor)	GET /api/v1/files
Dateien eines Datensatzes auflisten	GET /api/v1/threads/{thread_id}/files

Dateianfragen erfordern eine aktuelle Mitgliedschaft im ausgewählten Team, das zur ausgewählten Organisation gehören muss. Dies gilt für Personen und Servicekonten. Das Hochladen in einen Datensatz erfordert Bearbeitungszugriff; private Uploads müssen einem Datensatz zugeordnet sein und erfordern die Berechtigung, dessen private Assets zu verwalten. Nicht angehängte Dateien können nur von ihrem besitzenden Team gelesen werden, sofern sie nicht privat sind.

Einfacher Upload

Für Dateien, die problemlos mit einer einzelnen Anfrage übertragen werden können, senden Sie multipart/form-data per POST mit file und optionalen Zuordnungszielen. Die Antwort enthält die erstellte Ressource mit einer signierten URL:

curl

curl -fsS "$APID_URL/api/v1/files" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -F "file=@inspection-report.pdf" \
  -F "threadId=$THREAD_ID"

TypeScript

const resources = await client.files.upload({
  file,               // a File
  threadId,           // optional: attach to a Thread
  // fieldId,         // optional: attach as a field value
  // isPrivate: true, // optional
});

fieldId hängt die Datei als Wert eines Feldes vom Typ Ressource an; isPrivate schränkt die Sichtbarkeit ein.

Fortsetzbarer Upload (tus)

Große Dateien verwenden das fortsetzbare Upload-Protokoll tus 1.0 unter /api/v1/files/upload, gefolgt von einem Abschlussaufruf, der den abgeschlossenen Upload in einen Ressourceneintrag umwandelt. Der Ablauf lautet: Hochladen → Abschließen → (bereits angehängt oder über Felder anhängen).

1. Upload erstellen. Senden Sie eine POST-Anfrage mit tus-Headern; die Werte von Upload-Metadata sind Base64-codiert und filename ist erforderlich (optional: fieldId, threadId, isPrivate):

   curl -i -X POST "$APID_URL/api/v1/files/upload" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Length: 52428800" \
     -H "Upload-Metadata: filename $(printf 'video.mp4' | base64),threadId $(printf %s "$THREAD_ID" | base64)"
   # → 201 Created
   # → Location: …/api/v1/files/upload/<upload-id>

   Bewahren Sie die <upload-id> aus Location für den Abschluss auf. Die abschließende Antwort liefert die permanente Ressourcen-ID, die davon abweichen kann. Geben Sie den vorgesehenen Datensatz, das Feld und die Privatsphäre beim Erstellen an; diese Angaben können beim Abschluss nicht geändert werden. Upload-Length muss eine positive, bekannte Byteanzahl sein.

2. Bytes senden (fortsetzbar – wiederholte PATCH-Anfragen werden ab Upload-Offset fortgesetzt):

   curl -i -X PATCH "$APID_URL/api/v1/files/upload/$UPLOAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Offset: 0" \
     -H "Content-Type: application/offset+octet-stream" \
     --data-binary @video.mp4

   Upload-Anfragen tolerieren längere Inaktivitätspausen. Um den Upload nach einer Unterbrechung fortzusetzen, senden Sie eine HEAD-Anfrage an dieselbe URL, um den aktuellen Upload-Offset auszulesen, und setzen Sie ihn anschließend von dort per PATCH fort. Jede tus-1.0-Clientbibliothek (z. B. tus-js-client) übernimmt dieses Protokoll für Sie.

3. Abschließen. Uploads werden erst nach dem Abschluss zu Ressourceneinträgen:

   curl -fsS "$APID_URL/api/v1/files/finalize" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "'"$THREAD_ID"'",
       "requests": [
         { "resId": "'"$UPLOAD_ID"'", "filename": "video.mp4", "size": 52428800 }
       ]
     }'

   POST /api/v1/files/finalize akzeptiert mehrere Uploads gleichzeitig; jedes Anfrageelement enthält die tus-Upload-ID als resId sowie filename und size (optional: fieldId, isPrivate). Dateiname, Größe, Datensatz, Feld und Privatsphäre müssen mit der Anfrage zur Erstellung des Uploads übereinstimmen. Verwenden Sie für die Erstellung, die Blöcke, HEAD, DELETE und den Abschluss dieselbe authentifizierte Identität sowie denselben Organisations-/Teamkontext. Upload-Sitzungen laufen sieben Tage nach ihrer Erstellung ab. Nur abgeschlossene Uploads können finalisiert werden.

   Wird ein identischer Abschlussversuch innerhalb dieses Zeitraums wiederholt, werden die ursprünglichen Ressourcen mit neuen signierten URLs zurückgegeben. Ein Batch darf entweder nur neue abgeschlossene Uploads oder nur bereits finalisierte Uploads enthalten. Finalisierte Uploads können über tus weder mit PATCH geändert noch beendet werden.

Hinweis

Die tus-Endpunkte verwenden das tus-Netzwerkprotokoll anstelle von JSON und erscheinen daher nur zusammenfassend in der API-Referenz. Das oben beschriebene Verhalten wird durch die tus-Konfiguration des Servers definiert (/upload und /upload/{id} unter /api/v1/files).

Downloads und signierte URLs

• GET /api/v1/files/{resource_id}/download — Weiterleitung zu einer signierten URL für die Datei.
• POST /api/v1/files/urls?ids=<id>&ids=<id> — erzeugt kurzlebige signierte URLs für den direkten Zugriff auf den Objektspeicher; verwenden Sie diese, wenn ein Browser oder nachgelagertes System die Bytes ohne Proxy-Zugriff benötigt.

Achtung

Signierte URLs laufen ab. Speichern Sie Ressourcen-IDs, niemals signierte URLs – fordern Sie URLs erneut an, wenn Sie einen neuen Zugriff benötigen.

Suche und Auflistung

Es gibt zwei Abfragestile:

• GET /api/v1/files/search — seitenindexierte Suche mit q, threadId, mimeFilters und includeArchived.
• GET /api/v1/files — mit einem Cursor paginierte Auflistung (cursor, pageSize; includeArchived ist erforderlich), gefiltert nach threadId oder createdBy.

Für Dateien im Kontext eines einzelnen Datensatzes sollten Sie GET /api/v1/threads/{thread_id}/files bevorzugen (siehe den Leitfaden zur Threads API).

Verwandte Seiten

• Leitfaden zur Threads API — Dateien an Datensatzfelder und Vorschaubilder anhängen
• Kernmodell — Position von Dateien im Domänenmodell
• API-Referenz — vollständige Parameter- und Schemadetails