Eine Datei über die REST-API hochladen
Initialisieren Sie einen REST-Upload. Senden Sie die Datei per Einzel-PUT oder fortsetzbarem Multipart. Prüfen Sie das Ergebnis und klären Sie Limits, Konflikte und verlorene Antworten sicher.
Zuletzt geprüft
Screenshots zeigen die englische Oberfläche.
Öffnen Sie zum REST-API-Upload eine Uploadsitzung, senden Sie ihre Bytes und lesen Sie die endgültige Dateiantwort. Die Initialisierung reserviert eine Übertragung. Sie bedeutet nicht, dass eine gespeicherte Datei bereitsteht. Kleine Dateien enden mit einem PUT. Multipart-Uploads brauchen einen eigenen Abschlussaufruf.
Zugangsdaten und Ziel
Öffnen Sie Profil → API-Schlüssel, wählen Sie API-Schlüssel erstellen und anschließend Nur Upload. Öffnen Sie Einschränkungen und Gültigkeit → Protokolle, wählen Sie Nur ausgewählte und aktivieren Sie REST API. Speichern Sie das einmalige Token aus Schlüssel erstellen vertraulich. Eine Workspace-Bindung wird unterstützt. Ein Ordneranker gewöhnlicher API-Schlüssel wird über REST nicht unterstützt.
Sie benötigen die workspace_id des Ziels und für Unterordner die folder_id. Ein API-Schlüssel mit Nur Upload kann Uploadsitzungen öffnen und abfragen, aber keine gewöhnlichen Dateien oder Workspaces auflisten. Ermitteln Sie IDs mit getrennt berechtigten Lesezugangsdaten oder Anfragen der angemeldeten App. Erweitern Sie einen Produktions-Uploadschlüssel nicht vorübergehend zur Zielsuche.
Hinterlegen Sie einen berechtigten Lese-API-Schlüssel vertraulich als DOSYA_READ_API_KEY und fordern Sie zur ID-Suche die Workspace-Liste an:
curl --fail-with-body --silent --show-error \
'https://api.dosya.dev/api/workspaces' \
-H "Authorization: Bearer $DOSYA_READ_API_KEY"
Kopieren Sie die id des gewünschten Workspaces aus workspaces. Rufen Sie mit denselben Lesezugangsdaten GET /api/files?workspace_id=THAT_ID für seine Stammliste auf. Kopieren Sie die Zielordner-ID aus den gelieferten Ordnern. Geben Sie zum Prüfen eines verschachtelten Ordners auch folder_id an. Nutzen Sie diese IDs mit den Upload-Zugangsdaten. Lesbare Namen sind keine API-IDs.
Ihre Workspace-Mitgliedschaft muss upload_files und Zugriff auf die Uploadseite erlauben. Das Ziel muss innerhalb einer Mitglieds-Ordnerbeschränkung liegen, für das Mitglied sichtbar sein und neue Inhalte erlauben. Ordner- oder Dateisperren, Erweiterungsregeln, Speicherkontingent des Inhabers, Mitglieds-Speichergrenze oder Workspace-Parallelität können den Transfer stoppen.

Schritte: kleine Testdatei mit curl hochladen
Hinterlegen Sie DOSYA_API_KEY vertraulich. Ersetzen Sie den Workspace-Platzhalter durch eine echte berechtigte ID. Das Beispiel braucht curl und Python 3. Es erstellt eine 12-Byte-Datei und lädt sie in den Workspace-Stamm hoch:
set -e
printf 'Hello dosya\n' > dosya-api-test.txt
DOSYA_WORKSPACE_ID='REPLACE_WITH_WORKSPACE_ID'
python3 - "$DOSYA_WORKSPACE_ID" <<'PYTHON' > upload-request.json
import json, sys
print(json.dumps({"workspace_id": sys.argv[1],
"file_name": "dosya-api-test.txt", "file_size": 12,
"mime_type": "text/plain"}))
PYTHON
curl --fail-with-body --silent --show-error \
'https://api.dosya.dev/api/upload/init' \
-H "Authorization: Bearer $DOSYA_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @upload-request.json -o upload-init.json
DOSYA_UPLOAD_PATH=$(python3 -c 'import json; print(json.load(open("upload-init.json"))["upload_url"])')
curl --fail-with-body --silent --show-error --request PUT \
"https://api.dosya.dev$DOSYA_UPLOAD_PATH" \
-H "Authorization: Bearer $DOSYA_API_KEY" \
-H 'Content-Type: text/plain' \
--data-binary @dosya-api-test.txt -o upload-result.json
python3 -m json.tool upload-result.json
Stoppen Sie bei gescheiterter Initialisierung. Senden Sie den PUT nicht an einen alten Pfad des vorigen Versuchs. Ergänzen Sie für einen bekannten Zielordner "folder_id": "REPLACE_WITH_FOLDER_ID" im Initialisierungs-JSON. Namen werden von Pfadtrennern, Referenzen auf übergeordnete Ordner und Steuerzeichen bereinigt, dann auf höchstens 255 Zeichen geprüft. Senden Sie in file_size echte ganzzahlige Bytes, keine MB oder formatierte Zeichenfolge.
Die Initialisierung liefert 201 mit session_id, upload_url, workspace_id, file_name, file_size, mime_type, extension, region und resumable. Bis 52.428.800 Bytes (50 MiB) ist resumable null, sofern nicht force_multipart: true angefordert wurde. Die Region kommt vom Workspace. Eine clientseitig genannte Region verschiebt die Datei nicht.
Die PUT-Antwort 201 enthält ok: true und file mit id, name, size_bytes, version, region, content_hash, hash_verified und etag. Vergleichen Sie size_bytes mit der lokalen Datei und behalten Sie die ID. Nur-Upload-API-Schlüssel prüfen den Abschluss per Sitzungsstatus. Prüfen Sie die Ergebnisdatei unabhängig über die angemeldete Dateiliste oder einen Lese-API-Schlüssel. Hochladen allein erstellt keinen öffentlichen Link und sendet keine E-Mail an Empfänger.
Multipart-Übertragung und Fortsetzen
Nutzen Sie über 50 MiB die gelieferten resumable-Werte. Teile haben 10.485.760 Bytes (10 MiB), außer dem kürzeren letzten Teil. total_parts ist die angegebene Größe geteilt durch die Teilgröße, aufgerundet. Dateien mit positiver Größe können auch force_multipart: true anfordern. Erzwungenes Multipart für null Bytes wird abgelehnt.
Erstellen Sie für größere lokale Dateien neue Initialisierungsdaten aus der tatsächlichen Größe. Behalten Sie nicht die 12-Byte-Testwerte bei. Dieser Python-Befehl ersetzt upload-request.json im bereits gewählten Workspace. Ändern Sie path und ergänzen Sie bei Bedarf eine bekannte folder_id:
python3 - "$DOSYA_WORKSPACE_ID" <<'PYTHON' > upload-request.json
import json, sys
from pathlib import Path
path = Path("REPLACE_WITH_LOCAL_FILE_PATH")
print(json.dumps({"workspace_id": sys.argv[1], "file_name": path.name,
"file_size": path.stat().st_size,
"mime_type": "application/octet-stream"}))
PYTHON
Führen Sie den vorigen POST /api/upload/init mit diesen Daten aus. Speichern Sie die Antwort als upload-init.json und nutzen Sie dieselbe unveränderte lokale Datei im folgenden Fortsetzungsprogramm. Behalten Sie das erfolgreiche Initialisierungs-JSON, um nach Unterbrechung dieselbe Sitzung fortzusetzen. Das Python-3-Programm sendet fehlende Teile nacheinander und schließt sie ab. Speichern Sie es als resume-upload.py, setzen Sie vertraulich die Umgebungsvariable DOSYA_API_KEY und führen Sie python3 resume-upload.py PATH_TO_UNCHANGED_FILE upload-init.json aus. Es verlangt eine Initialisierung mit resumable ungleich null:
import json, os, sys
from pathlib import Path
from urllib.request import Request, urlopen
base = "https://api.dosya.dev"
init = json.loads(Path(sys.argv[2]).read_text())
r = init["resumable"]
if r is None:
raise SystemExit("Use the single PUT flow for this session")
file = Path(sys.argv[1])
if file.stat().st_size != init["file_size"]:
raise SystemExit("Local size changed; open a new upload session")
headers = {"Authorization": "Bearer " + os.environ["DOSYA_API_KEY"]}
def call(path, method="GET", body=None):
req = Request(base + path, data=body, method=method,
headers={**headers, "Content-Type": "application/octet-stream"})
with urlopen(req) as response:
return json.load(response)
state = call(r["status_url"])
if state["status"] == "complete":
print("Already complete; file:", state["file_id"])
raise SystemExit(0)
if state["status"] == "failed":
raise SystemExit("Session failed; open a fresh session and resend the file")
done = set(state["uploaded_parts"])
with file.open("rb") as stream:
for number in range(1, r["total_parts"] + 1):
chunk = stream.read(r["part_size"])
if number not in done:
call(r["part_upload_url"] + "/" + str(number), "PUT", chunk)
result = call(r["complete_url"], "POST", b"")
print("Stored file:", result["file"]["id"], "bytes:", result["file"]["size_bytes"])
Lassen Sie die lokale Datei unverändert. Gleiche Größe garantiert nicht gleichen Inhalt. Teilenummern beginnen bei eins und dürfen total_parts nicht überschreiten. Eine gespeicherte Teilenummer liefert bei Wiederholung ihren gespeicherten ETag mit already_uploaded: true. Ihre Bytes werden nicht ersetzt. HTTP 413 mit Part exceeds the 10 MB part size meldet einen zu großen Teil. Leere Teile werden mit Empty part data abgelehnt.
Zum Abschluss senden Sie POST an complete_url. Der Server verfolgt die Teile bereits. Es ist kein Client-ETag-Array nötig. Fehlende Teile melden Only N of M parts uploaded. Upload remaining parts before completing. Fragen Sie den Status ab, senden Sie fehlende Nummern und schließen Sie erneut ab. Wiederholen Sie die Initialisierung nicht als idempotente Aktion. Sie öffnet eine weitere Sitzung. Kein Idempotency-Key-Header sichert diesen Endpunkt ab.
Wartefristen, Konflikte und sichere Wiederaufnahme
GET /api/upload/{session_id}/status liefert status, bytes_uploaded, uploaded_parts, part_size, total_parts, has_multipart und file_id. file_id bleibt bis zum Abschluss null. Prüfen Sie diesen Endpunkt zuerst, wenn die endgültige Antwort verloren ging. Eine complete-Sitzung mit ID klärt das Ergebnis ohne Upload einer weiteren Version.
Eine nie gestartete ausstehende Sitzung kann nach 10 Minuten ohne Aktivität stillgelegt werden. Begonnene Multipart-Sitzungen können nach 24 Stunden ohne gespeicherten Schreibvorgang stillgelegt werden. Das ist keine genaue Gültigkeitszusage. Starten Sie stillgelegte Sitzungen mit neuer Initialisierung und senden Sie alle Teile neu. Ein verlassener Parallelitätsplatz der Zugangsdaten endet nach 15 Minuten ohne Erneuerung. Teilanfragen erneuern den Platz aktiver Uploads.
| Fehler | Wiederaufnahme |
|---|---|
403, You don't have upload permission in this workspace | Workspace-Admin um die nötige Aktion bitten oder erlaubtes Ziel wählen. |
403, You don't have access to the upload page | Die Rolle braucht für REST-Uploads Seitenzugriff und Upload-Berechtigung. |
404, Destination folder not found | Sichtbarkeit und Zugehörigkeit der ID zum Workspace prüfen. Keinen Ordnernamen einsetzen. |
403, folder_locked | Zielsperre vor Wiederholung mit berechtigtem Admin klären. |
400, File exceeds the … GB size limit for this workspace | Kleinere Datei nutzen oder Admin um Änderung der Workspace-Regel bitten. |
| 413 zur Dateigröße der Zugangsdaten | API-Schlüssel nur bei genehmigter höherer Grenze ersetzen. Der Server prüft auch empfangene Bytes. |
400 mit error_code: concurrent_upload_limit | Andere Transfers beenden oder abbrechen. max_concurrent_uploads in der Antwort prüfen. |
409, Upload session is already complete | Status abfragen und gespeicherte Datei-ID ermitteln. |
| 429 oder wiederholbares 503 | Retry-After beachten. Multipart-Zustand behalten und fehlende Teile wiederholen, statt parallele Ersatzsitzungen zu öffnen. |
Speicher-, Größen-/Erweiterungs-, Mitglieds- und Parallelitätsprüfungen kommen vor der Ziel-/Versionsprüfung. Der Abschluss prüft geltende Limits erneut gegen empfangene Bytes. Erfolgreiche Initialisierung verspricht daher keinen erfolgreichen Abschluss.
Ein gleichnamiger Upload kann bei ausreichendem Zugriff zur neuen Version einer bestehenden Datei werden. Hochladen erstellt also nicht immer neu. Senden Sie für gezielten Ersatz file_id und zuletzt gesehene expected_version bei der Initialisierung. Eine veraltete Version liefert 409 version_conflict. Laden Sie den Stand neu und entscheiden Sie über den Ersatz neuerer Daten. Nutzen Sie eindeutige Testnamen gegen versehentliche Versionsänderung. Die Workspace-Aufbewahrungsregel max_versions kann alte Versionsobjekte nach erfolgreichem Ersatz endgültig löschen. Ohne Einstellung sind 10 Versionseinträge Standard. Sichern Sie benötigte ältere Fassungen vor dem Ersatz. Nehmen Sie nicht an, dass jeder Upload unbegrenzten Verlauf bewahrt.
Senden Sie zum Verwerfen einer unfertigen Sitzung DELETE /api/upload/{session_id} mit derselben Autorisierung. Das bricht Teilspeicherung ab und legt die Sitzung still. Fehlende oder gescheiterte Sitzungen liefern ok: true mit already_gone: true. Fertige Sitzungen liefern 409 und werden hier nicht gelöscht. Abbrechen verwirft ungespeicherten Fortschritt. Es macht keine fertige Datei oder Version rückgängig.
Senden Sie beim Einzel-PUT optional X-Dosya-Sha256 mit genau 64 Hexzeichen der erwarteten SHA-256. Übereinstimmung setzt hash_verified: true. Abweichung liefert 400 hash_mismatch mit erwartetem und empfangenem Hash. Ohne Header bedeutet false, dass kein Client-Hash vorlag, nicht eine gescheiterte Prüfung. Multipart-Abschluss bietet nicht dieselbe Einzelupload-Hashgarantie. Prüfen Sie heruntergeladene Bytes separat, wenn Integrität wesentlich ist.
Halten Sie Tokens aus Debugprotokollen heraus und speichern Sie Sitzungsmetadaten vertraulich. Verlorene Tokens sind aus verdeckten Listeneinträgen nicht abrufbar. Widerrufen Sie kompromittierte Zugangsdaten. Senden Sie keine Upload-Autorisierungsheader an den Support.
Erwartetes Ergebnis
Eine fertige Sitzung nennt eine beständig gespeicherte Datei im gewählten Workspace und Ordner. Ihre Bytezahl entspricht dem empfangenen Inhalt. Ein vorhandenes gleichnamiges Ziel kann stattdessen eine neue Version erhalten. Bestätigen Sie ID, Größe und Version, bevor Sie den Transfer als erfolgreich markieren.
Weitere Anleitungen
War diese Anleitung hilfreich?
Bewertungen werden geladen …
Beim Abstimmen speichern wir ein notwendiges Abstimmungs-Cookie bis zu 180 Tage. So können Sie Ihre Antwort ändern.
Fragen und Antworten
Stellen Sie Fragen zu den Schritten dieser Anleitung. Fragen werden vor der Veröffentlichung geprüft.
Veröffentlichen Sie in Fragen keine Kontodaten, Zugangsdaten oder privaten Dateien. Nutzen Sie privaten Support für solche Angaben.
Fragen werden geladen …
Melden Sie sich bei Ihrem dosya-Konto an, um eine Frage zu stellen.