curlでPOSTリクエストを送信する方法：完全リファレンス
現在、世界中で約200億個のcurlがインストールされ、稼働している。この数字は、ツール開発者であり、ほぼ独力でメンテナンスを行っているダニエル・ステンバーグ氏によるものだ。curlは、ルーター、自動車、衛星、スマートテレビ、公共ウェブの大部分を支えるLinuxサーバー、そして主要なLLMランタイムすべてに搭載されている。これらのインストール環境でやり取りされるHTTP動詞の中で、POSTが最も重要な役割を果たしている。ほとんどの開発者は、初めてAPIをテスト、デバッグ、または統合する際に、curlのPOSTを使用する。
Postmanの2025年版「APIの現状レポート」によると、RESTの採用率は93%に達しています。現在、組織の82%が少なくとも部分的にAPIファーストで運用しています。POSTは、サーバーにデータを作成、送信、または転送する際に必ず使用する動詞です。AIワークロードはこの傾向をさらに加速させました。AIの使用に起因するAPIトラフィックは2024年に73%増加し（Postman、2024）、現在ではすべてのLLMプロバイダーのドキュメントが、標準的な「最初の呼び出し」としてcurl POSTスニペットで始まっています。
このリファレンスでは、curl を使用した POST リクエストのあらゆる形式を、1 行の最小限のリクエストから実際の暗号通貨決済 API への呼び出しまで、詳しく解説します。目的は、ただ読むだけでなく、そのまま貼り付けて使えるようにすることです。初めてサーバーにデータを送信する場合でも、午前 2 時に Webhook ハンドラーを再構築する場合でも、以下のパターンは実際に必要な内容を網羅しています。
以下の表は簡略版です。POSTリクエスト送信時に最もよく使用されるcurlコマンドラインオプションを、フラグと用途別にまとめたチートシートです。各オプションについては、以降のセクションで詳しく説明します。
| フラグ | その機能 | 手を伸ばすと |
|---|---|---|
| `-X POST`、`--request POST` | HTTPリクエストメソッドをPOSTに強制します | 明示的な方法、または珍しい動詞 |
| `-d`、`--data` | リクエストボディにデータを送信し、POSTを自動的に設定します | フォームフィールド、インラインJSON、シンプルなペイロード |
| `--data-binary` | 改行を削除せずにファイルまたはバイナリデータを送信します | ファイルアップロード、大きなJSON、生バイナリデータ |
| `--data-urlencode` | 値を送信する前にURLエンコードします | スペースや特殊文字を含む値 |
| `--json` | `Content-Type: application/json` と `Accept: application/json` を指定してデータを送信する | curl 7.82.0以降、JSON API |
| `-H`、`--header` | カスタムHTTPヘッダーを追加します | コンテンツタイプ、認証、APIキー |
| `-F`、`--form` | フォームフィールドまたはファイルを含む multipart/form-data を送信します | ファイルアップロード、HTML形式のフォーム |
| `-u`、`--user` | HTTP基本認証資格情報を送信します | レガシーAPI、シンプルなユーザー名とパスワードによる認証 |
| `-i`、`--include` | 出力にレスポンスヘッダーを含める | サーバー応答の検査 |
| `-v`、`--verbose` | リクエストとレスポンスの全文（ヘッダーを含む）を出力します。 | POSTリクエストの失敗をデバッグする |
curlのPOSTリクエストとHTTPメソッドを理解する
curl の POST リクエストは、コマンドラインから POST メソッドで送信される HTTP POST リクエストです。curl ツール自体は、その役割を 20 種類以上のプロトコル間で「データを転送する」ことだと説明していますが、HTTP はそのうちの 1 つにすぎません。POST は、「ここにデータがあります。これを使って何かしてください」という意味です。ペイロードはリクエストボディに含まれ、URL には決して含まれません。この特性により、POST はリソースの作成、フォームの送信、認証情報を含むあらゆる処理を扱います。GET はデータをクエリ文字列に格納するため、すべてのプロキシとすべてのブラウザ履歴から見ることができます。POST はそうではありません。
ほとんどのチュートリアルでは、小さくても重要な詳細が省略されています。`-d` オプションを渡すと、curl は自動的に POST メソッドに切り替わります。カスタムのリクエスト メソッドを指定する `-X POST` はオプションです。多くの例では、ペイロードの横に `-X POST` があると意図が一目でわかるため、依然としてこのオプションが含まれています。
PUTとPOSTはよく混同されるため、明確にしておく価値があります。PUTは既知の場所にあるリソースを置き換えます。POSTは新しいリソースを作成するか、汎用エンドポイントで処理されるデータを送信します。
基本的なcurl POST構文と-dフラグの実践例
curl POSTの最小要件は1行です。
「`」
curl -d "username=arya&age=16" https://api.example.com/users
「`」
以上です。POSTリクエスト、form-urlencodedボディ、面倒なことは一切ありません。`-d`は3つの役割を果たします。ペイロードをリクエストボディに詰め込み、リクエストメソッドをPOSTに切り替え、デフォルトのヘッダーとして`Content-Type: application/x-www-form-urlencoded`を追加します。私は通常、少し冗長なフォームを貼り付けます。なぜなら、POSTインテントはコードレビューで読みやすいからです。
「`」
curl -X POST -d "username=arya&age=16" https://api.example.com/users
「`」
同じバイト列がネットワーク上を流れます。同じリクエスト引数です。チームがスキャンしやすい方を使用してください。`-d` フラグは、コマンドラインからサーバーにデータを送信するために使用される主力オプションであり、バックエンド開発者が curl に渡すものの 90% を処理します。シェル呼び出し、Webhook テスト、Makefile ターゲット、GitHub Actions ステップなどです。
`-d` の近縁のオプションが 3 つあります。`--data-binary` はバイト列をそのまま保持します。通常の `-d` は改行を削除し、バイナリ ペイロードを破損します。`--data-urlencode` はパーセント エンコードを行います。`--data-urlencode "name=I am Daniel"` は `name=I%20am%20Daniel` として届きます。`--data-raw` は、値が `@` で始まり、curl がファイルを読み込まない場合の回避策です。複数の `-d` フラグは `&` で結合されます。フォームには適していますが、JSON には適していません。
最後に一つ注意点があります。引用符です。ペイロードをシングルクォートで囲むと、シェルが「$」やバックスラッシュを解釈しなくなります。これを忘れると、POSTデータの半分が欠落している理由を午前2時に悩むことになります。
これらの詳細は重要です。なぜなら、curl 自体が地球上で最も徹底的にテストされている HTTP クライアントの 1 つだからです。Stenberg の 2025 年 12 月の回顧録では、その年に 8 つのリリースが記録されています。 9 つの CVE があり、すべて低または中程度と評価されています。 アクティブなテスト ケースは 2,179 件で、12 か月前より 232 件増加しています。 2024 年 12 月のリリース 8.11.1 では、CVE-2024-11053 (netrc とリダイレクトの認証情報漏洩) が修正されました。 2026 年 4 月下旬の現在の安定版は curl 8.20.0 です。 7.82.0 より前のバージョンを使用しているユーザーは、まだ `--json` フラグがなく、古い 3 つのフラグ パターンにフォールバックします。
curlで--jsonまたは-Hオプションを使用してJSONデータを送信する
JSONは2026年のREST APIの共通言語です。curlを使ってJSONをPOSTする方法は2つあります。どちらを使うかは、マシンにインストールされているcurlのバージョンによって決まります。
定番の3フラグパターン。CentOS 6以降であればどこでも動作します。
「`」
curl -X POST \
-H "Content-Type: application/json" \
-d '{"title":"Tea","quantity":2}' \
https://api.example.com/orders
「`」
最新の速記法は、curl 7.82.0（2022年3月）以降で利用可能です。
「`」
curl --json '{"title":"Tea","quantity":2}' https://api.example.com/orders
「`」
`--json` フラグは、次の 3 つの機能を提供します。`Content-Type: application/json` を設定します。`Accept: application/json` を設定します。リクエストボディを送信します。また、`--json` フラグを複数回渡すと、ペイロードが連結されます。JSON チャンクをストリーミングエンドポイントにパイプする場合に便利です。
ファイルに保存された JSON ペイロードの場合は、ファイルパスの前に `@` を付けます。JSON オブジェクトが大きすぎてインラインで貼り付けられない場合、バージョン管理システムに保存されている場合、または別のスクリプトによって生成された場合は、ファイルからデータを投稿するのが標準的なパターンになります。
「`」
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
「`」
2 番目のパターンは、`order.json` という名前のファイルからデータを読み込み、必要なすべてのヘッダーを付けて送信します。JSON コンテンツが大きい場合やバイナリになる可能性がある場合は、`--data-binary @file.json` の方が安全です。これは、改行を削除せず、特殊文字を解釈せず、フォーム フィールドではなくバイトを期待するエンドポイントに生のバイナリ データを送信します。3 番目のパターンは、`-d @-` を使用して標準入力からデータを読み込みます。別のコマンドの出力を curl POST に直接パイプする場合に便利です。
以下の表は、一般的な4つのJSON形式を1つのエンドポイントに対応付けたものです。
| パターン | 指示 | いつ使用するか |
|---|---|---|
| インライン、クラシック | `-X POST -H "Content-Type: application/json" -d '{"k":"v"}'` | 最大限の互換性、あらゆるcurlバージョン |
| インライン、モダン | `--json '{"k":"v"}'` | curl 7.82.0以降、最も簡潔な構文 |
| ファイルから、安全 | `-X POST -H "..." -d @payload.json` | ペイロードはバージョン管理システムで管理されている。 |
| ファイルから、バイナリセーフ | `-X POST -H "..." --data-binary @payload.json` | 大きなファイル、改行を含むペイロード |
これは以前よりも重要になっています。主要なLLMプロバイダー（OpenAI、Anthropic、Mistral、Google）はすべて、APIドキュメントの冒頭で、まさにこの形式を使用したcurl POSTの例を示しています。AI駆動のトラフィックは、2024年にAPI呼び出し全体の73%を占めました（Postman調べ）。curlは今や「このエンドポイントを呼び出すにはどうすればいいか」という質問に対する標準的な参照となっています。
Content-Type、ヘッダー、そしてcurlが想定すること
ほとんどの「415 Unsupported Media Type」応答は、ヘッダーが1つ不足していることが原因です。`-d`オプションを使用すると、curlはリクエストに`Content-Type: application/x-www-form-urlencoded`というタグを静かに追加します。`-H "Content-Type: application/json"`または`--json`オプションなしでJSONボディを送信すると、415エラーが返されます。警告はなく、拒否されるだけです。
その他のメタデータも本文に含まれます。Content-Length、Authorizationヘッダー、トレース用のX-Request-Idなどです。これらのメタデータを正しく取得することが、API統合の半分を占めます。JSONオブジェクト自体は、比較的簡単な半分です。
`-H` オプションはカスタムヘッダーを追加します。必要に応じて繰り返してください。ヘッダー名は大文字と小文字を区別しませんが、値は区別します。設定ミスのある POST リクエストをデバッグする最も簡単な方法は、`-v` オプションを付けて一度実行し、リクエスト行を読み、API ドキュメントと比較することです。10 回中 8 回は、数秒でバグが明らかになります。
あと2点補足です。Content-Lengthはcurlによってボディサイズから自動的に設定されるため、上書きすることはほとんどありません。`Accept: application/json`は、サーバーにHTMLではなくJSONで応答するように指示するものです。そのためには`-H`を追加するか、Content-TypeとAcceptを同時に設定する`--json`を使用してください。
curl POST -F を使用したフォームデータとファイルのアップロード
ファイルを含むHTML形式のフォームデータの場合、適切なフラグは`-F`です。これは`multipart/form-data`リクエストを生成します。これは、`-d`がデフォルトで生成するform-urlencodedとは異なるコンテンツタイプです。考え方も異なります。1段落程度のチュートリアルでは、この2つを混同することが多く、実際にバグが発生する原因となります。
`-F` はフィールドごとに1回だけ使用します。プレーンフォームフィールド:
「`」
curl -F "name=Arya" https://api.example.com/submit
「`」
ファイルアップロード:
「`」
curl -F "file=@/path/to/image.png" https://api.example.com/upload
「`」
`@` プレフィックスは、curl にディスクからファイルを読み込み、その内容をリクエストボディに含めるように指示します。curl はファイル名から MIME タイプを自動的に検出しますが、必要に応じて明示的に上書きしてください。
「`」
curl -F "[email protected];type=image/png" https://api.example.com/upload
「`」
複数の `-F` フラグを指定すると、複数のフィールドまたはファイルを 1 つのリクエストにまとめることができます。
「`」
curl -F "title=Holiday" -F "[email protected]" -F "[email protected]" https://api.example.com/album
「`」
マルチパートラッパーを使用しない生のファイルコンテンツ（JSONファイルやバイナリブロブをストリーミングエンドポイントに送信する際によく必要となるもの）の場合は、代わりに`--data-binary @file.bin`を使用してください。これにより、明示的に設定したContent-Typeとともに、ファイルバイトがリクエストボディとしてそのまま送信されます。
curl POSTにおける認証：基本認証、ベアラー認証、APIキー
2026年には、3つの認証方式がほぼすべてのREST APIを網羅するでしょう。基本認証（ユーザー名とパスワードをbase64エンコードしてヘッダーに格納）：
「`」
curl -u "myuser:mypass" -X POST -d "..." https://api.example.com/login
「`」
ほとんどの最新API（OAuth発行の認証情報を含む）で使用されるベアラートークンは、カスタムのAuthorizationヘッダーに付随します。
「`」
curl -H "Authorization: Bearer $TOKEN" --json '{"q":"hello"}' https://api.example.com/query
「`」
APIキーは通常、サービス固有のヘッダーに存在します。
「`」
curl -H "X-API-Key: $PLISIO_KEY" --json @invoice.json https://api.plisio.net/api/v1/invoices/new
「`」
環境変数またはシークレットマネージャからの認証情報を使用し、決してインラインで入力しないでください。なぜでしょうか？GitGuardianの2025年版「シークレットの蔓延状況」によると、2024年にGitHubに漏洩した新たなシークレットは2380万件に上り、2023年比で25%増加しました。そのうち90%以上は、漏洩後5日間有効でした。curlスクリプト内のインライン認証情報は、これらの漏洩の主な原因となっています。以下のセキュリティセクションでは、ワークフローについて説明します。
実際のcurl POSTの例：Plisio決済API
実例のない参考資料は理論に過ぎません。以下のcurl POSTは、PlisioのREST APIを介して暗号通貨決済請求書を発行します。Plisioの手数料は一律0.5%です。カード決済処理業者の手数料は通常2～4%です。Plisioは30種類以上の暗号通貨に対応し、19のeコマースプラットフォームとの連携機能を提供しています。
暗号通貨 API が練習のターゲットとして機能している理由。ステーブルコインは 2025 年中に約 28 兆ドルの実質経済量を移動しました。Chainalysis は、2023 年以降の成長率を 133% と推定しています。暗号通貨決済ゲートウェイ市場は 2025 年に 20 億ドル近くで推移し、2026 年に 23 億 9000 万ドルに達する見込みです (The Business Research Company による)。BitPay、Coinbase Commerce、Plisio: どれでも選んでください。最新のゲートウェイとの最初の統合手順は、ほぼ常に curl POST です。
新規請求書を作成するための最小限の呼び出し：
「`」
curl -X POST https://api.plisio.net/api/v1/invoices/new \
-H "Content-Type: application/json" \
-H "認証: 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"
}'
「`」
呼び出しが成功すると、HTTP 201が返されます。レスポンスボディはJSONオブジェクトで、生成された請求書ID、顧客が支払いを行う`invoice_url`、送金先ウォレットアドレス、有効期限タイムスタンプが含まれます。これを`jq`にパイプして、必要なフィールドを抽出してください。
「`」
... | jq '.data.invoice_url'
「`」
これが全体のパターンです。エンドポイントとペイロードを入れ替えるだけで、BitPayの課金、Coinbase Commerceのチェックアウト、Stripeの支払いインテントなど、あらゆる決済方法にそのまま適用できます。フラグは変更されず、JSONデータのみが変わります。
curl POSTリクエストのデバッグ: -v、--trace、errors
POSTリクエストの失敗はデバッグの難題です。闇雲に再試行するのは最悪の選択です。コマンドラインの4つのオプションで、必要な処理のほとんどをカバーできます。
`-v` は、リクエスト行、すべてのリクエストヘッダー、およびレスポンスステータスを出力します。これは最初に試すべきフラグです。`--trace-ascii -` はより強力なオプションで、POST のボディを含む会話全体を標準出力に出力します。レスポンスヘッダーをボディの上にインライン表示するには、`curl -i` を使用します。また、`-w "%{http_code}\n"` は HTTP ステータスコードのみを出力します。これは、API に対して CI チェックをスクリプト化する場合に役立ちます。
よく見かけるステータスコードについて説明します。400: サーバーはリクエストを解析しましたが、ペイロードを拒否しました。401: 認証ヘッダーが欠落しているか無効です。415: Content-Type が間違っています。500: 入力時にサーバーがクラッシュしました。それぞれ特定のレイヤーが除外されるため、最初の失敗時に `-v` を実行する価値の半分になります。
curl POSTのセキュリティ：APIキー、シークレット、および情報漏洩
どの参考文献もこのセクションを飛ばしている。どの事件の事後分析でもこのセクションに言及している。2024年12月：米国財務省の情報漏洩は、流出したBeyondTrust APIキーに起因していたことが判明。まさに本番環境のスクリプトの`-H "Authorization: Bearer ..."`ヘッダー内に存在する種類の認証情報である。
防御策は地味だ。環境変数からトークンを読み取り、AWS Secrets Manager、HashiCorp Vault、1Password CLIなどのシークレットマネージャーに保存する。`gitleaks`または`trufflehog`を実行するプリコミットフックを常に実行させておく。シェル履歴に存在したトークンはすべてローテーションする。どれも刺激的なものではないが、すべて効果がある。2026年にバックエンド開発者が身につけるべき最も重要な習慣は、送信するすべてのcurl POSTリクエストにこれを適用することだ。
