So senden Sie eine POST-Anfrage mit curl: vollständige Referenz

Weltweit sind derzeit schätzungsweise 20 Milliarden Installationen von curl im Einsatz. Diese Zahl stammt von Daniel Stenberg, dem Entwickler des Tools, der es nahezu im Alleingang betreut. curl ist in Routern, Autos, Satelliten, Smart-TVs, den Linux-Servern, die den Großteil des öffentlichen Webs betreiben, und allen gängigen LLM-Laufzeitumgebungen vorinstalliert. Von allen HTTP-Verben, die diese Installationen verwenden, ist POST die wichtigste. Die meisten Entwickler testen, debuggen oder integrieren eine API zum ersten Mal mit einem curl POST-Request.

Laut dem Postman-Bericht „State of the API 2025“ liegt die Verbreitung von REST bei 93 %. 82 % der Unternehmen arbeiten mittlerweile zumindest teilweise API-orientiert. POST ist das Verb, das man verwendet, wenn man Daten erstellt, übermittelt oder an einen Server sendet. KI-Workloads haben diesen Trend weiter beschleunigt. Der API-Traffic, der auf KI-Nutzung zurückzuführen ist, wuchs 2024 um 73 % (Postman, 2024), und die Dokumentation jedes LLM-Anbieters beginnt mittlerweile mit einem curl-POST-Codeausschnitt als Standard-Erstaufruf.

Diese Referenz beschreibt alle möglichen Formen einer POST-Anfrage mit curl – von der minimalen Einzeiler-Anfrage bis hin zu einem funktionierenden Aufruf an eine echte Krypto-Zahlungs-API. Ziel: Eine Anleitung zum Kopieren, nicht nur zum Lesen. Egal, ob Sie zum ersten Mal Daten an einen Server senden oder nachts um 2 Uhr einen Webhook-Handler neu erstellen – die folgenden Beispiele decken alles ab, was Sie benötigen.

Die folgende Tabelle ist die Kurzfassung. Sie bietet einen Überblick über die wichtigsten Befehlszeilenoptionen von curl, die am häufigsten beim Senden von POST-Anfragen verwendet werden. Jede Option wird in den folgenden Abschnitten ausführlich erläutert.

Die curl POST-Anfrage und die HTTP-Methode verstehen

Eine curl-POST-Anfrage ist eine HTTP-POST-Anfrage, die mit der POST-Methode über die Kommandozeile gesendet wird. Das curl-Tool selbst beschreibt seine Aufgabe als „Datenübertragung“ über mehr als zwei Dutzend Protokolle, von denen HTTP nur eines ist. POST bedeutet: Hier sind Daten, mach etwas damit. Die Nutzdaten werden im Anfragetext und niemals in der URL gespeichert. Aufgrund dieser Eigenschaft eignet sich POST für die Ressourcenerstellung, Formularübermittlungen und alles, was Anmeldeinformationen enthält. GET speichert die Daten in der Abfragezeichenfolge, die für jeden Proxy und jeden Browserverlauf sichtbar ist. POST hingegen nicht.

Die meisten Tutorials lassen ein kleines, aber nützliches Detail aus. Mit `-d` wechselt curl automatisch zu POST. Die explizite Angabe von `-X POST`, die eine benutzerdefinierte Anfragemethode festlegt, ist optional. Viele Beispiele verwenden sie dennoch, da die Verwendung von `-X POST` neben der Nutzlast die Absicht sofort verdeutlicht.

PUT und POST werden so oft verwechselt, dass es sich lohnt, genauer hinzusehen. PUT ersetzt eine Ressource an einem bekannten Ort. POST erstellt eine neue Ressource oder sendet Daten zur Verarbeitung an einen generischen Endpunkt.

Grundlegende curl POST-Syntax und der -d-Flag in der Praxis

Der minimale curl POST-Befehl besteht aus einer Zeile:

```

curl -d "username=arya&age=16" https://api.example.com/users

```

Das war's. POST-Anfrage, URL-codierter Body, ganz einfach. `-d` hat drei Funktionen: Es fügt die Nutzdaten in den Anfrage-Body ein, ändert die Anfragemethode auf POST und fügt `Content-Type: application/x-www-form-urlencoded` als Standard-Header hinzu. Ich verwende trotzdem meist die etwas ausführlichere Version, da die POST-Absicht in einer Code-Review besser lesbar ist.

```

curl -X POST -d "username=arya&age=16" https://api.example.com/users

```

Gleiche Datenmengen. Gleiche Anfrageargumente. Verwenden Sie die Variante, die Ihr Team am einfachsten analysieren kann. Der Parameter `-d` ist das Arbeitspferd zum Senden von Daten an einen Server von der Kommandozeile aus und deckt neunzig Prozent aller Aufgaben ab, die Backend-Entwickler mit curl erledigen: Shell-Aufrufe, Webhook-Tests, Makefile-Ziele, GitHub-Actions-Schritte.

Drei enge Verwandte von `-d`. `--data-binary` erhält Ihre Bytes; das Standard-`-d` entfernt Zeilenumbrüche und verfälscht die Binärdaten. `--data-urlencode` kodiert die Daten prozentual: `--data-urlencode "name=I am Daniel"` wird zu `name=I%20am%20Daniel`. `--data-raw` dient als Ausweg, wenn ein Wert mit `@` beginnt und curl die Datei nicht lesen soll. Mehrere `-d`-Flags werden mit `&` verknüpft. Geeignet für Formulare. Nicht für JSON.

Noch ein letzter Haken: Anführungszeichen. Einfache Anführungszeichen um die Nutzdaten verhindern, dass die Shell `$` oder Backslashes interpretiert. Vergisst man sie, verbringt man die Nacht damit, sich zu fragen, warum die Hälfte der POST-Daten fehlt.

Diese Details sind wichtig, da curl selbst einer der am gründlichsten getesteten HTTP-Clients weltweit ist. Stenbergs Rückblick vom Dezember 2025 zählte acht Releases in diesem Jahr. Neun CVEs, alle mit niedriger oder mittlerer Risikobewertung. 2.179 aktive Testfälle, 232 mehr als zwölf Monate zuvor. Release 8.11.1 vom Dezember 2024 behob CVE-2024-11053 (ein Leck von Anmeldeinformationen in netrc und redirect). Die aktuelle stabile Version (Stand Ende April 2026) ist curl 8.20.0. Nutzer älter als Version 7.82.0 haben weiterhin keine `--json`-Option und verwenden das ältere Drei-Flag-Muster.

Senden von JSON-Daten mit curl unter Verwendung von --json oder -H

JSON wird 2026 die Lingua franca für REST-APIs sein. Es gibt zwei Möglichkeiten, JSON mit curl per POST-Anfrage zu senden. Welche Methode verwendet wird, hängt ausschließlich von der auf dem Rechner installierten curl-Version ab.

Klassisches Drei-Flaggen-Muster, funktioniert überall ab CentOS 6:

```

curl -X POST \

-H "Content-Type: application/json" \

-d '{"title":"Tea","quantity":2}' \

https://api.example.com/orders

```

Moderne Kurzschrift, verfügbar seit curl 7.82.0 (März 2022):

```

curl --json '{"title":"Tea","quantity":2}' https://api.example.com/orders

```

Der Parameter `--json` bewirkt drei Dinge: Er setzt `Content-Type: application/json`, `Accept: application/json` und sendet den Nachrichtentext. Außerdem werden die Nutzdaten verkettet: Wird `--json` mehrmals verwendet, ist dies nützlich, wenn JSON-Teile an einen Streaming-Endpunkt weitergeleitet werden.

Bei in einer Datei gespeicherten JSON-Daten muss dem Dateipfad ein `@` vorangestellt werden. Das Posten von Daten aus einer Datei wird zum Standardmuster, sobald das JSON-Objekt zu groß zum Inline-Einfügen ist, sich in der Versionskontrolle befindet oder von einem anderen Skript generiert wird:

```

curl -X POST -H "Content-Type: application/json" -d @order.json https://api.example.com/orders

curl --json @order.json https://api.example.com/orders

```

Das zweite Muster liest die Daten aus einer Datei namens `order.json` und sendet sie mit allen erforderlichen Headern. Bei großen oder potenziell binären JSON-Inhalten ist `--data-binary @file.json` die sicherere Option. Dabei werden keine Zeilenumbrüche entfernt, Sonderzeichen nicht interpretiert und die rohen Binärdaten an einen Endpunkt gesendet, der Bytes anstelle von Formularfeldern erwartet. Ein drittes Muster liest die Daten von stdin über `-d @-`. Dies ist praktisch, wenn die Ausgabe eines anderen Befehls direkt an einen curl POST-Request weitergeleitet wird.

Die folgende Tabelle ordnet die vier gängigen JSON-Formen einem einzelnen Endpunkt zu:

Das ist wichtiger denn je. Alle großen LLM-Anbieter – OpenAI, Anthropic, Mistral, Google – veröffentlichen ihre API-Dokumentation mit einem curl-POST-Beispiel, das genau diese Struktur verwendet. KI-gesteuerter Traffic trug 2024 um 73 % zum gesamten API-Aufrufvolumen bei (Postman). curl ist heute die Standardreferenz für die Frage: „Wie rufe ich diesen Endpunkt auf?“

Content-Type, Header und die Annahmen von curl

Die meisten „415 Unsupported Media Type“-Antworten lassen sich auf einen fehlenden Header zurückführen. Mit `-d` versieht curl Ihre Anfrage stillschweigend mit dem Header `Content-Type: application/x-www-form-urlencoded`. Senden Sie einen JSON-Body ohne `-H "Content-Type: application/json"` oder `--json`, erhalten Sie den Fehler 415 zurück. Keine Warnung, nur die Ablehnung.

Weitere Metadaten werden ebenfalls mit dem Body übermittelt: Content-Length, der Authorization-Header und die X-Request-Id für die Nachverfolgung. Die korrekte Erfassung dieser Metadaten ist die halbe Miete jeder API-Integration. Das JSON-Objekt selbst ist der einfachere Teil.

`-H` fügt benutzerdefinierte Header hinzu. Bei Bedarf wiederholen. Headernamen sind nicht case-sensitiv; Werte hingegen schon. Die schnellste Methode, einen falsch konfigurierten POST-Request zu debuggen: Führen Sie ihn einmal mit `-v` aus, lesen Sie die Anfragezeile und vergleichen Sie sie mit der API-Dokumentation. In acht von zehn Fällen tritt der Fehler innerhalb von Sekunden auf.

Zwei weitere Hinweise. Die Content-Length wird von curl automatisch anhand der Body-Größe festgelegt; sie muss selten manuell angepasst werden. `Accept: application/json` weist den Server an, im JSON-Format statt im HTML-Format zu antworten. Fügen Sie dazu ein weiteres `-H` hinzu oder verwenden Sie `--json`, wodurch Content-Type und Accept gleichzeitig gesetzt werden.

Formulardaten und Datei-Uploads mit curl POST -F

Für HTML-Formulardaten mit Dateien ist die Option `-F` die richtige Wahl. Sie erzeugt eine `multipart/form-data`-Anfrage. Der Inhaltstyp unterscheidet sich vom standardmäßigen `-d`-Typ (form-urlencoded). Es handelt sich um ein anderes Verständnismodell. Kurze Tutorials vermischen die beiden Konzepte oft genug, um tatsächliche Fehler zu verursachen.

`-F` einmal pro Feld. Einfaches Formularfeld:

```

curl -F "name=Arya" https://api.example.com/submit

```

Ein Datei-Upload:

```

curl -F "file=@/path/to/image.png" https://api.example.com/upload

```

Das Präfix `@` weist curl an, die Datei von der Festplatte zu lesen und ihren Inhalt in den Anfragetext einzufügen. curl erkennt den MIME-Typ automatisch anhand des Dateinamens; bei Bedarf kann dieser explizit überschrieben werden.

```

curl -F "[email protected];type=image/png" https://api.example.com/upload

```

Mehrere `-F`-Flags packen mehrere Felder oder Dateien in eine Anfrage:

```

curl -F "title=Holiday" -F "[email protected]" -F "[email protected]" https://api.example.com/album

```

Für den reinen Dateiinhalt ohne Multipart-Wrapper, was häufig beim Senden einer JSON-Datei oder eines Binärdatenblocks an einen Streaming-Endpunkt erforderlich ist, verwenden Sie stattdessen `--data-binary @file.bin`. Dadurch werden die Dateibytes unverändert als Anfragetext gesendet, zusammen mit dem von Ihnen explizit festgelegten Content-Type.

Authentifizierung in curl POST: Basic, Bearer, API-Schlüssel

Drei Authentifizierungsformen decken im Jahr 2026 nahezu jede REST-API ab. Basisauthentifizierung (Benutzername plus Passwort, Base64-kodiert in einem Header):

```

curl -u "myuser:mypass" -X POST -d "..." https://api.example.com/login

```

Bearer-Token, die von den meisten modernen APIs, einschließlich aller von OAuth ausgestellten Anmeldeinformationen, verwendet werden, basieren auf einem benutzerdefinierten Authorization-Header:

```

curl -H "Authorization: Bearer $TOKEN" --json '{"q":"hello"}' https://api.example.com/query

```

API-Schlüssel befinden sich typischerweise in einem dienstspezifischen Header:

```

curl -H "X-API-Key: $PLISIO_KEY" --json @invoice.json https://api.plisio.net/api/v1/invoices/new

```

Anmeldeinformationen aus einer Umgebungsvariablen oder einem Geheimnismanager, niemals direkt im Code eingeben. Warum? Laut dem GitGuardian-Bericht „State of Secrets Sprawl 2025“ wurden 2024 23,8 Millionen neue Geheimnisse auf GitHub öffentlich zugänglich gemacht – ein Anstieg von 25 % gegenüber 2023. Mehr als 90 % dieser Geheimnisse waren auch fünf Tage nach ihrer Veröffentlichung noch gültig. Direkt in curl-Skripten eingegebene Anmeldeinformationen sind eine der Hauptursachen für diese Lecks. Der folgende Abschnitt zum Thema Sicherheit beschreibt den Workflow.

Praxisbeispiel für einen curl POST-Request: Plisio-Zahlungs-API

Referenzdokumente ohne praktisches Beispiel sind rein theoretisch. Der untenstehende curl POST-Befehl erstellt eine Krypto-Zahlungsrechnung über die REST-API von Plisio. Plisio berechnet pauschal 0,5 %; Zahlungsdienstleister verlangen üblicherweise 2–4 %. Plisio unterstützt über dreißig Kryptowährungen und bietet Integrationen für neunzehn E-Commerce-Plattformen.

Warum Krypto-APIs als Übungsziele geeignet sind. Stablecoins bewegten im Jahr 2025 ein reales Wirtschaftsvolumen von rund 28 Billionen US-Dollar. Chainalysis prognostizierte ein Wachstum von 133 % CAGR seit 2023. Der Markt für Krypto-Zahlungsgateways erreichte 2025 ein Volumen von fast 2 Milliarden US-Dollar und wird laut The Business Research Company bis 2026 voraussichtlich 2,39 Milliarden US-Dollar erreichen. BitPay, Coinbase Commerce, Plisio: Wählen Sie einen Anbieter. Der erste Integrationsschritt mit einem modernen Gateway ist fast immer ein curl POST-Request.

Der minimale Aufruf zum Erstellen einer neuen Rechnung:

```

curl -X POST https://api.plisio.net/api/v1/invoices/new \

-H "Content-Type: application/json" \

-H "Authorization: Bearer $PLISIO_API_KEY" \

-d '{

"source_currency": "USD",

"source_amount": 49.99,

"order_number": "INV-1042",

"currency": "BTC",

"email": "[email protected]",

"order_name": "Annual subscription"

}'

```

Ein erfolgreicher Aufruf liefert den HTTP-Statuscode 201. Der Antworttext ist ein JSON-Objekt: eine generierte Rechnungs-ID, die `invoice_url`, über die der Kunde bezahlt, die Ziel-Wallet-Adresse und ein Ablaufdatum. Leiten Sie die Daten an `jq` weiter, um das benötigte Feld zu extrahieren.

```

... | jq '.data.invoice_url'

```

Das ist das gesamte Muster. Man tauscht den Endpunkt und die Nutzdaten aus, und die Struktur lässt sich direkt auf eine BitPay-Zahlung, einen Coinbase Commerce-Checkout oder eine Stripe-Zahlungsabsicht übertragen. Die Flags ändern sich nicht; nur das JSON ändert sich.

Debuggen einer curl POST-Anfrage: -v, --trace, errors

Ein fehlgeschlagener POST-Request stellt ein Debugging-Rätsel dar. Blindlings erneut zu versuchen, ist der schlechteste Ansatz. Vier Optionen in der Kommandozeile decken die meisten benötigten Fälle ab.

`-v` gibt die Anfragezeile, alle Anfrageheader und den Antwortstatus aus. Dies ist die erste Option, die Sie verwenden sollten. `--trace-ascii -` ist die umfassendere Option: Sie gibt die gesamte Kommunikation, einschließlich des Bodys einer POST-Anfrage, auf der Standardausgabe aus. Verwenden Sie `curl -i`, um die Antwortheader oberhalb des Bodys anzuzeigen. Und `-w "%{http_code}\n"` gibt nur den HTTP-Statuscode aus, was beim Skripten von CI-Prüfungen einer API hilfreich ist.

Zu den am häufigsten auftretenden Statuscodes: 400: Der Server hat Ihre Anfrage analysiert, die Nutzdaten jedoch abgelehnt. 401: Fehlender oder ungültiger Authentifizierungsheader. 415: Falscher Content-Type. 500: Der Server ist aufgrund Ihrer Eingabe abgestürzt. Jeder dieser Codes schließt eine bestimmte Ebene aus, was der Hälfte des Nutzens der Option `-v` beim ersten Fehler entspricht.

curl POST-Sicherheit: API-Schlüssel, Geheimnisse und Datenlecks

Dieser Abschnitt wird in keiner Quelle erwähnt. In jeder Nachbesprechung eines Vorfalls wird er jedoch erwähnt. Dezember 2024: Der Datenverlust beim US-Finanzministerium lässt sich auf einen durchgesickerten BeyondTrust-API-Schlüssel zurückführen. Genau die Art von Zugangsdaten, die in Produktionsskripten in den Headern `-H "Authorization: Bearer ..."` enthalten sind.

Die Verteidigung ist unspektakulär. Lesen Sie Tokens aus Umgebungsvariablen. Speichern Sie sie in einem Geheimnismanager wie AWS Secrets Manager, HashiCorp Vault oder der 1Password CLI. Lassen Sie einen Pre-Commit-Hook mit `gitleaks` oder `trufflehog` laufen. Rotieren Sie alle Tokens, die jemals in der Shell-Historie gespeichert waren. Nichts davon ist aufregend. Aber es funktioniert. Diese Vorgehensweise bei jeder einzelnen curl-POST-Anfrage anzuwenden, ist die wichtigste Gewohnheit, die sich ein Backend-Entwickler im Jahr 2026 aneignen kann.

Simon Chartan

A journalist with a strong technical background and a passion for decentralized finance. With degrees in MBA and Master of Engineering in Data Science, the author combines analytical expertise with a clear, engaging writing style. At Plisio, they cover topics such as cryptocurrency, blockchain, DeFi, and digital finance—helping readers make sense of a rapidly evolving fintech landscape.