Die Dokumentation einer API zeigt einen einzeiligen curl-Befehl, der eine Bestellung anlegt. Sie fügen ihn ein, ergänzen Ihren Schlüssel, drücken Enter, und der Server antwortet mit 415 Unsupported Media Type oder mit 400 und invalid JSON, obwohl das JSON korrekt aussieht. Auf dem Linux-Laptop eines Kollegen funktioniert dieselbe Zeile. Mit der API ist alles in Ordnung: Der Befehl hat einen anderen Body oder einen anderen Content-Type gesendet, als Sie denken, und unter Windows hat die Shell die Anführungszeichen aus Ihrem JSON entfernt, bevor curl es überhaupt gesehen hat.
Dieser Artikel behandelt Formulardaten mit -d, JSON mit --json oder -H plus -d, Bodys aus Dateien, Uploads mit -F, Header und Authentifizierung, die Frage, wann -X POST nötig ist, das Lesen der Antwort und das Setzen von Anführungszeichen in cmd und PowerShell. Jeder Befehl lief mit curl 8.22.0 unter Windows 11, in cmd und in Windows PowerShell 5.1, gegen einen kleinen Echo-Server auf unserem eigenen Rechner, der Methode, Content-Type-Header und empfangenen Body ausgab.
Was ist eine POST-Anfrage?
Eine POST-Anfrage ist eine HTTP-Anfrage, die Daten in ihrem Body transportiert und den Server bittet, etwas damit zu tun: eine Bestellung anlegen, ein Formular speichern, einen Job starten. RFC 9110, der HTTP-Standard, definiert POST als Aufforderung an die Zielressource, die im Body enthaltene Darstellung zu verarbeiten, und zwar nach ihren eigenen Regeln.
GET fragt nur etwas ab und hat keinen Body. POST ist außerdem nicht idempotent: Derselbe POST, zweimal gesendet, kann zwei Bestellungen anlegen. Wenn Anfragen, Endpoints und Statuscodes neu für Sie sind, beginnen Sie mit Was ist eine API und wie funktioniert sie?.
Zwei Teile eines POST zählen am meisten. Der Body sind die Daten. Der Header Content-Type sagt dem Server, wie er sie lesen soll: als Formularfelder, als JSON oder als Multipart-Upload. Die meisten Probleme mit curl-POST-Anfragen sind ein Widerspruch zwischen beiden.
Wie sendet curl eine POST-Anfrage?
curl wechselt von selbst zu POST, wenn Sie eine Body-Option angeben; Sie beschreiben die Daten, curl leitet die Methode daraus ab:
- Sie ergänzen eine Body-Option.
-d,--data-binary,--data-urlencode,--jsonoder-Fmacht die Anfrage zum POST. - curl wählt einen
Content-Type. Die-d-Familie sendetapplication/x-www-form-urlencoded,--jsonsendetapplication/json,-Fsendetmultipart/form-datamit einer Boundary. - curl bereitet den Body vor. Mehrere
-d-Teile verbindet es mit&, aus Dateien, die per-d @gelesen werden, entfernt es die Zeilenumbrüche, und mit--data-binaryund--jsonbleiben Dateien unverändert. - curl sendet die Anfrage.
POST /orders HTTP/1.1, die Header einschließlichContent-Length,Content-Typeund Ihrer-H-Werte, danach der Body. - Der Server liest zuerst
Content-Type. Eine JSON-API, die als Formular gekennzeichnete Daten erhält, lehnt sie mit 415 ab oder scheitert mit 400 am Parsen. - curl gibt den Body der Antwort aus. Status und Header bleiben verborgen, solange Sie nicht mit
-i,-voder-wdanach fragen.
Welche curl-Option passt für den Body der Anfrage?
Wählen Sie die Option, die zu dem passt, was der Server erwartet. Das kam bei unserem Echo-Server jeweils an:
| Option | Gesendeter Content-Type | Umgang mit dem Body | Einsatz |
|---|---|---|---|
-d / --data | application/x-www-form-urlencoded | Wie getippt; @file verliert Zeilenumbrüche | Formulare wie im Browser |
--data-urlencode | application/x-www-form-urlencoded | Wert per Prozentkodierung kodiert | Werte mit Leerzeichen oder & |
--data-binary | application/x-www-form-urlencoded | Byte für Byte | Dateien, die exakt bleiben müssen |
--json | application/json | Byte für Byte, ergänzt Accept | JSON-APIs (ab 7.82.0) |
-F / --form | multipart/form-data | In benannte Teile zerlegt | Datei-Uploads |
Alle sind in der curl-Manpage beschrieben, der Referenz für jede Option in diesem Artikel.
Wie senden Sie Formulardaten mit -d?
-d sendet eine Zeichenkette als Body und kennzeichnet sie als Formulardaten, das Format, das ein Browser für ein einfaches HTML-Formular verwendet:
curl -d "name=Ada&city=Paris" https://api.example.com/signupUnser Server erhielt POST, Content-Type: application/x-www-form-urlencoded und name=Ada&city=Paris. Mehrere -d-Optionen werden mit & verbunden, -d "a=1" -d "b=2" kam also als a=1&b=2 an.
-d sendet Text so, wie Sie ihn tippen; ein Wert mit Leerzeichen, & oder = zerfällt daher in falsche Felder. --data-urlencode kodiert den Wert für Sie:
curl --data-urlencode "q=red shoes & bags" https://api.example.com/searchDer Server erhielt q=red+shoes+%26+bags, ein einziges Feld mit erhaltenem Kaufmanns-Und. Will ein Endpoint die Felder stattdessen in der Adresse, ergänzen Sie -G: Aus -G -d "q=shoes" -d "page=2" wurde GET /search?q=shoes&page=2 ohne Body.
Wie senden Sie JSON per POST mit curl?
Nutzen Sie --json ab curl 7.82.0, oder setzen Sie den Header in älteren Versionen selbst. -d allein sagt nie „das ist JSON“:
# Falsch für die meisten JSON-APIs: JSON-Body, aber als Formular gekennzeichnet
curl -d '{"sku":"A-100","qty":2}' https://api.example.com/orders
# Funktioniert mit jeder curl-Version
curl -H "Content-Type: application/json" -d '{"sku":"A-100","qty":2}' https://api.example.com/orders
# Ab curl 7.82.0
curl --json '{"sku":"A-100","qty":2}' https://api.example.com/ordersAuf unserem Testrechner kam der erste Befehl als application/x-www-form-urlencoded an, und unser reiner JSON-Test-Endpoint lehnte ihn mit 415 ab. Der zweite kam als application/json mit Accept: */* an, der dritte zusätzlich mit Accept: application/json, und der Endpoint antwortete mit 201 Created.
--json steht für --data-binary plus diese beiden Header, und ein Header, den Sie mit -H setzen, ersetzt den, den curl ergänzen würde. Prüfen Sie Ihre Version mit curl --version: Ubuntu 22.04 etwa liefert curl 7.81.0 aus, eine Version vor --json. Skripte für ältere Server sollten deshalb bei der -H-Form bleiben.
Wie senden Sie JSON aus einer Datei?
Übergeben Sie die Datei mit @: --json @order.json in neuen Versionen, --data-binary @order.json mit einem Content-Type-Header in alten. Verzichten Sie auf -d @order.json, wenn die Bytes exakt bleiben müssen:
curl --json @order.json https://api.example.com/orders
curl -H "Content-Type: application/json" --data-binary @order.json https://api.example.com/ordersMit einer vierzeiligen order.json lieferte -d @order.json 29 Bytes in einer Zeile, weil curl bei so gelesenen Dateien Wagenrückläufe und Zeilenumbrüche entfernt. --data-binary und --json lieferten alle 33 Bytes. Einem JSON-Parser ist das egal, einer signierten Anfrage oder einer CSV-Datei nicht.
Eine Datei beendet auch die meisten Probleme mit Anführungszeichen, weil die Shell das JSON nie anfasst. @- liest den Body aus der Standardeingabe, sodass ein Skript ihn erzeugen kann: python make_order.py | curl --json @- https://api.example.com/orders.
Wie ergänzen Sie Header in einer curl-POST-Anfrage?
Geben Sie jedem Header ein eigenes -H "Name: value"; wiederholen Sie die Option so oft wie nötig:
curl --json @order.json \
-H "Idempotency-Key: 7f3c9a10" \
-H "X-Request-Source: nightly-sync" \
https://api.example.com/ordersEin Header, den Sie setzen, ersetzt curls eigenen Header gleichen Namens; so ändern Sie Accept oder User-Agent. Ein leerer Wert entfernt ihn: Mit -H "Content-Type:" erhielt unser Server gar keinen Content-Type.
-H-Header werden nach einer Weiterleitung erneut gesendet. curl hält Authorization und Cookie zurück, wenn die Weiterleitung zu einem anderen Host führt, ein Schlüssel in einem Header wie X-API-Key reist aber mit. Seien Sie also vorsichtig, wenn Sie -L ergänzen.
Wie laden Sie eine Datei mit curl -F hoch?
Nutzen Sie -F mit @ vor dem Dateinamen. curl sendet dann multipart/form-data, das Format eines HTML-Formulars mit Dateifeld:
curl -F "title=Q3 report" -F "file=@report.pdf" https://api.example.com/uploadsJedes -F wird zu einem benannten Teil. Wir haben eine Textdatei hochgeladen, report.txt, und unser Server sah einen Textteil title und einen Dateiteil file mit filename="report.txt" und Content-Type: text/plain, den curl aus der Dateiendung erraten hatte. Setzen Sie den Typ, wenn die Vermutung falsch ist: -F "file=@scan.bin;type=application/pdf".
< statt @ setzt den Inhalt einer Datei in ein normales Textfeld, etwa -F "notes=<notes.txt". -F und -d lassen sich nicht kombinieren: Unser curl brach mit You can only select one HTTP request method! ab, bevor es irgendetwas sendete. Der Feldname muss der Dokumentation der API entsprechen.
Wie authentifizieren Sie eine POST-Anfrage mit curl?
Senden Sie, was die API verlangt: -u user:pass für Basic-Authentifizierung oder einen Authorization-Header für ein Token. Mit -u user:pass erhielt unser Server Authorization: Basic dXNlcjpwYXNz, nur die Base64-Form von user:pass; verwenden Sie das also ausschließlich über HTTPS.
Ein Bearer-Token lesen Sie am besten aus einer Umgebungsvariable, damit es nicht in Ihrem Shell-Verlauf landet:
export API_TOKEN="ihr-token"
curl --json @order.json -H "Authorization: Bearer $API_TOKEN" https://api.example.com/orders--oauth2-bearer "$API_TOKEN" erzeugt denselben Header. Manche APIs wollen den Schlüssel in einem eigenen Header, etwa X-API-Key.
Wann brauchen Sie -X POST?
Mit einer Body-Option fast nie. Mit -v gab unser curl bei -X POST -d "x=1" den Hinweis Note: Unnecessary use of -X or --request, POST is already inferred. aus; laut Manpage ändert -X nur das Wort in der Anfragezeile. Nützlich ist es für andere Methoden mit Body: curl -X PUT --json '{"qty":3}' ... kam als PUT mit dem JSON an.
Schädlich wird -X zusammen mit -L (Weiterleitungen folgen). Wir haben an eine Adresse gesendet, die mit 302 Found antwortete:
- Mit
-L -d "x=1"folgte curl mit einem GET ohne Body, wie es die Manpage für 301, 302 und 303 beschreibt. - Mit
-L -X POST -d "x=1"war die nächste Anfrage ein POST mit leerem Body: Die Methode war erzwungen, die Daten nicht. - Mit
-L --post302 -d "x=1"war die nächste Anfrage ein POST mit dem ursprünglichen Body.
Wenn ein POST eine Weiterleitung überstehen muss, nutzen Sie also --post301, --post302 oder --post303, oder senden Sie direkt an die endgültige Adresse.
Wie sehen Sie Status und Header der Antwort?
Ergänzen Sie -i für Statuszeile und Antwort-Header, -v für Anfrage und Antwort oder -w nur für ausgewählte Werte:
curl -i --json @order.json https://api.example.com/orders
curl -s -o /dev/null -w "%{http_code}\n" --json @order.json https://api.example.com/ordersDer erste Befehl gab vor dem JSON HTTP/1.1 201 Created aus. Der zweite gab nur 201 aus: -s blendet die Fortschrittsanzeige aus, -o /dev/null verwirft den Body (-o NUL unter Windows). "%{http_code} %{content_type} %{time_total}s\n" lieferte uns 201 application/json 0.001347s.
Ergänzen Sie in Skripten --fail-with-body: curl beendet sich bei Status 400 oder höher mit einem Fehler, gibt die Meldung des Servers aber trotzdem aus. Für eine Anfrage, die sich seltsam verhält, nutzen Sie -v; die Zeilen, die mit > beginnen, sind genau das, was curl gesendet hat.
Wie schreiben Sie curl-POST-Befehle unter Windows?
Windows 10 und 11 bringen echtes curl als curl.exe mit, doch in Windows PowerShell 5.1 ist das Wort curl ein Alias für das Cmdlet Invoke-WebRequest. Auf unserem Rechner scheiterte curl -d "x=1" ... in PowerShell 5.1 mit A positional parameter cannot be found that accepts argument 'x=1'. Tippen Sie curl.exe, wie es auch curls Seite zum Windows-Build empfiehlt.
Das größere Problem sind die Anführungszeichen. JSON in einfachen Anführungszeichen, die Form aus jedem Linux-Beispiel, verhält sich in jeder Shell anders:
| Shell | Form, die funktionierte | Was die naive Form sendete |
|---|---|---|
| cmd.exe | -d "{\"sku\":\"A-100\"}" | '{sku:A-100}' |
| PowerShell 5.1 | --json '{\"sku\":\"A-100\"}' | {sku:A-100} |
| PowerShell 7.3+ | --json '{"sku":"A-100"}' | Hier nicht getestet |
| Jede Shell | --json "@order.json" | Die Datei, unverändert |
In cmd sind einfache Anführungszeichen keine Begrenzer, sie wurden also Teil des Bodys, und die inneren doppelten Anführungszeichen verschwanden. In PowerShell 5.1 kam '{"sku":"A-100","qty":2}' bei unserem Server als {sku:A-100,qty:2} an, und der JSON-Endpoint antwortete mit 400. Jedes innere Anführungszeichen als \" zu maskieren, löste beide Fälle.
Microsofts Referenz about_Parsing erklärt den Grund: PowerShell 7.3 hat geändert, wie Argumente mit eingebetteten Anführungszeichen an Programme wie curl.exe übergeben werden, eine inkompatible Änderung gegenüber 5.1. PowerShell 7 war auf unserem Testrechner nicht installiert; diese Zeile folgt daher der Dokumentation. Setzen Sie in PowerShell alles, was mit @ beginnt, in Anführungszeichen, etwa "@order.json"; schreiben Sie in einer .cmd-Batchdatei %%{http_code} für -w. Die sicherste Gewohnheit unter Windows ist die Datei: Dann bleibt der Shell nichts mehr, was sie kaputt machen könnte.
Wie senden Sie eine curl-POST-Anfrage über einen Proxy?
Ergänzen Sie -x mit der Proxy-Adresse; die Body-Optionen bleiben gleich:
curl -x http://user:pass@pr.proxynet.io:8000 \
--json @order.json https://api.example.com/ordersBei einem HTTPS-Ziel bittet curl den Proxy zuerst um einen CONNECT-Tunnel und sendet den POST dann innerhalb der verschlüsselten Verbindung; der Proxy sieht also den Hostnamen, nicht aber Ihr JSON. SOCKS5, Umgebungsvariablen und .curlrc behandelt cURL mit Proxy verwenden.
Ein Proxy hilft, wenn die Anfrage von einer bestimmten Adresse oder aus einem bestimmten Land kommen muss, zum Beispiel um zu sehen, wie Ihr eigener Checkout einem Käufer in einer anderen Region antwortet. Ein HTTPS-Proxy nimmt genau diese Optionen, mit Benutzername und Passwort oder mit der IP Ihres Servers auf der IP-Whitelist.
Braucht der Test Privatanschlüsse in einem gewählten Land oder einer Stadt, nutzt ein Residential-Proxy dieselbe -x-Zeile, mit Land und Sitzung im Benutzernamen.
Wo werden curl-POST-Anfragen eingesetzt?
Entwickler probieren eine API mit einem curl-POST aus, bevor sie Code schreiben, weil der Befehl nichts verbirgt. Supportteams fragen nach dem fehlschlagenden curl-Befehl, da er das Problem auf jedem Rechner reproduziert. Webhook-Empfänger testet man, indem man ein Beispielereignis an den eigenen Endpoint sendet. Deploy-Skripte rufen interne APIs auf, um Jobs zu starten oder Releases zu veröffentlichen, und Monitoring-Jobs senden eine Testbestellung an ein Staging-System und schlagen Alarm, wenn die Antwort nicht mehr 201 lautet.
Häufige Fehler bei curl-POST-Anfragen und ihre Lösungen
- 415 Unsupported Media Type. JSON mit
-dund Formular-Kennzeichnung gesendet. Nutzen Sie--jsonoder-H "Content-Type: application/json". - 400 Bad Request mit JSON-Parse-Fehler. Von der Shell entfernte Anführungszeichen oder ein Tippfehler im JSON. Prüfen Sie mit
-voder verschieben Sie das JSON in eine Datei. - Der POST kommt als GET an. Eine Weiterleitung mit 301, 302 oder 303 zusammen mit
-L. Senden Sie an die endgültige URL oder nutzen Sie die Optionen--post30x. - Leerer Body nach einer Weiterleitung.
-X POSTmit-L; lassen Sie-Xweg. - 401 oder 403. Fehlendes oder falsches Token, oder
$API_TOKENist in dieser Shell leer. Geben Sie die Variable zuerst aus. A positional parameter cannot be found.curlin PowerShell 5.1 hatInvoke-WebRequesterreicht; tippen Siecurl.exe.- Ein Teil eines Headers wird als zweite Adresse behandelt.
-H Content-Type: application/jsonohne Anführungszeichen wird am Leerzeichen getrennt. Setzen Sie jeden-H-Wert in Anführungszeichen. --jsonwird als unbekannt abgelehnt. curl älter als 7.82.0; nutzen Sie-Hplus--data-binary.
Entscheidungshilfe
| Bedarf | Empfehlung |
|---|---|
| Formularfelder senden | -d "a=1" -d "b=2" |
Formularwert mit Leerzeichen oder & | --data-urlencode |
| JSON senden, curl ab 7.82.0 | --json @file.json |
| JSON senden, älteres curl | -H "Content-Type: application/json" --data-binary @file.json |
| Datei hochladen | -F "file=@name.ext" |
| Authentifizierung per Token | -H "Authorization: Bearer $API_TOKEN" |
| PUT oder PATCH mit Body | -X PUT --json ... |
| POST, der eine Weiterleitung übersteht | -L --post302 (oder 301/303) |
| Nur der Statuscode | -s -o /dev/null -w "%{http_code}\n" |
| JSON unter Windows | curl.exe mit Datei und @ |
Häufige Fragen
Wie sende ich eine POST-Anfrage mit curl?
Geben Sie curl einen Body, dann sendet es einen POST: curl -d "name=Ada" https://api.example.com/form für Formulardaten oder curl --json '{"name":"Ada"}' https://api.example.com/users für JSON. -X POST ist nicht nötig.
Was ist der Unterschied zwischen -d und --json in curl?
Die Kennzeichnung unterscheidet sich. -d sendet Content-Type: application/x-www-form-urlencoded und entfernt Zeilenumbrüche aus Dateien; --json sendet Content-Type: application/json plus Accept: application/json und lässt Dateien unverändert. --json braucht curl 7.82.0 oder neuer.
Wie sende ich eine JSON-Datei per POST mit curl?
Nutzen Sie curl --json @data.json https://api.example.com/items. Bei curl älter als 7.82.0 nehmen Sie -H "Content-Type: application/json" --data-binary @data.json. Verzichten Sie auf -d @data.json, wenn es auf die exakten Bytes ankommt.
Wie sehe ich die Antwort-Header einer curl-POST-Anfrage?
Ergänzen Sie -i, um Statuszeile und Header vor dem Body auszugeben, oder -v, um Anfrage- und Antwort-Header zusammen zu sehen. Nur für den Statuscode nutzen Sie -s -o /dev/null -w "%{http_code}".
Warum funktioniert mein curl-POST unter Linux, aber nicht in PowerShell?
In Windows PowerShell 5.1 bedeutet curl Invoke-WebRequest, und 5.1 entfernt die doppelten Anführungszeichen innerhalb von JSON in einfachen Anführungszeichen, bevor curl.exe es erhält. Tippen Sie curl.exe, maskieren Sie innere Anführungszeichen als \" oder übergeben Sie das JSON aus einer Datei.
Wie übertrage ich einen curl-POST-Befehl nach Python?
Ordnen Sie jeden Teil zu: Aus --json wird json=, aus -d wird data=, aus -H wird headers= und aus -F wird files=. Eine vollständige Zuordnung mit getesteten Beispielen finden Sie in JSON mit Python Requests per POST senden.
Fazit
curl sendet einen POST, sobald es einen Body hat: -d für Formulardaten, --json für JSON ab 7.82.0, -H "Content-Type: application/json" mit --data-binary in älteren Versionen, -F für Uploads. Die meisten Fehler liegen an der Kennzeichnung, nicht an den Daten: Als Formular gesendetes JSON ergibt 415, -d @ verliert Zeilenumbrüche, und -X POST mit -L sendet nach einer Weiterleitung einen leeren POST. Was hinausging, prüfen Sie mit -v. Unter Windows tippen Sie curl.exe und legen JSON in eine Datei; muss die Anfrage von einer bestimmten Adresse oder aus einem bestimmten Land kommen, ergänzen Sie -x und lassen den Rest unverändert.




