curlコマンド入門｜APIリクエストをターミナルで実行する方法

curlを使うと、APIに対してGET・POST・PUT・DELETEなどのHTTPリクエストをターミナルから直接送れます。 画面を開かずに動作確認したいとき、スクリプトに組み込みたいとき、レスポンスやステータスコードをすばやく見たいときに特に便利です。

PostmanのようなGUIツールがなくても、URL、ヘッダー、JSONボディ、認証情報をコマンド1本で扱えます。まずは「読む」「送る」「失敗を検知する」の3つを押さえると、実務でかなり使えるようになります。

• まず覚える形は curl URL
• JSONを送るなら --json または -H "Content-Type: application/json" --data ...
• APIテストでは -i -L --fail-with-body -w がよく効く
• バージョン差があるので、最初に curl --version を確認しておく

curlで何ができるか

curlはURLを相手にデータを送受信するCLIツールです。HTTP/HTTPSのAPI確認では、次の作業をひと通りこなせます。

• GETで一覧や詳細データを取得する
• POSTでフォームやJSONを送信する
• PUTやPATCHで更新リクエストを試す
• DELETEで削除APIの挙動を確認する
• Authorization や Content-Type などのヘッダーを付ける
• レスポンス本文だけでなく、HTTPステータスコードやレスポンスヘッダーも確認する

たとえば開発中のAPIで「正しいJSONが届いているか」「認証ヘッダーが通っているか」「404や500をスクリプトで失敗扱いにしたいか」を見るとき、curlはかなり速いです。

前提環境と最初に確認すること

最初に、自分の環境のcurlバージョンを見ます。

curl --version

2026年4月21日時点で公開されているオンラインのman pageは curl 8.16.0 を案内しています。ただし、手元のmacOS、Linux、Windows、Dockerイメージに入っているcurlは別バージョンのことがあります。

特に確認したいのは --json の有無です。これは公式man pageでは 7.82.0で追加 とされています。古い環境では使えないため、その場合は -H と --data を使います。

ここがポイント: API向けの記事やサンプルで --json をそのまま試して動かない場合、まず curl --version を見てください。書き方の問題ではなく、単純にバージョン差のことがあります。

シェルの違いにも少し注意が必要です。

• macOS/Linuxのbashやzshでは、JSON文字列はシングルクォートで囲うと扱いやすい
• Windows PowerShellではクォートの挙動が異なるため、必要ならJSONをファイルにして @file.json で渡すと安定しやすい
• 長いコマンドは1行で無理に詰めず、改行して書くと見直しやすい

基本の書き方

まずはGETリクエストです。URLだけなら最も短く書けます。

curl https://httpbin.org/get

このリクエストでは、送ったURLやヘッダーなどをJSONで返してくれます。APIの疎通確認には十分です。

クエリパラメータを付ける

URLに直接書いてもよいですが、値を安全にエンコードしたいなら -G と --data-urlencode が便利です。

curl -G https://httpbin.org/get \
  --data-urlencode "keyword=curl command" \
  --data-urlencode "page=1"

この形なら、スペースや日本語を含む値でも崩れにくくなります。

レスポンスヘッダーも見る

本文だけではなく、HTTPステータスや Content-Type も見たいことがあります。

• -i または --show-headers: レスポンスヘッダー付きで表示
• -I または --head: HEADリクエストでヘッダーだけ取得

curl -i https://httpbin.org/json

curl -I https://httpbin.org/json

APIがJSONを返す想定なのに Content-Type が違っていた、キャッシュ制御ヘッダーが付いていなかった、といった確認に使えます。

JSONを送る基本形

APIを触るときに最も多いのは、JSONをPOSTする場面です。

--json が使える環境

curl 7.82.0以降なら、--json がいちばん分かりやすいです。公式man pageでは、これは次の3つのショートカットです。

• --data-binary
• Content-Type: application/json
• Accept: application/json

curl https://httpbin.org/post \
  --json '{"name":"Masa","role":"developer"}'

レスポンスでは、送信したJSONが json フィールドなどに入って返ります。自分が送った内容をすぐ見返せるので、APIテストの最初の一歩に向いています。

古い環境での書き方

--json がない場合は、ヘッダーと本文を明示します。

curl https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{"name":"Masa","role":"developer"}'

ファイルからJSONを送る

長いJSONをコマンドラインに直接書くと、クォートミスや履歴流出の原因になります。実務ではファイル経由のほうが安全です。

payload.json

{
  "name": "Masa",
  "role": "developer"
}

送信コマンド:

curl https://httpbin.org/post \
  --json @payload.json

古い環境なら次の形です。

curl https://httpbin.org/post \
  -H "Content-Type: application/json" \
  --data-binary @payload.json

HTTPメソッドごとの使い分け

curlはオプションに応じてメソッドを自動で選ぶことがあります。公式の everything curl でも、-d や -F でPOST、-I でHEAD、-T でPUTになると説明されています。

GET

curl https://httpbin.org/get

読み取り系APIの確認に使います。

POST

curl https://httpbin.org/post \
  --json '{"title":"hello"}'

作成系API、検索API、Webhookのテストでよく使います。

PUT

curl https://httpbin.org/put \
  -X PUT \
  --json '{"status":"updated"}'

更新系APIの確認に使います。

DELETE

curl https://httpbin.org/delete \
  -X DELETE

削除系APIの疎通確認に使います。

-X を多用しないほうがよい理由

everything curl では、-X はリクエスト行のメソッド文字列を変えるだけで、挙動そのものを自動で最適化するわけではない点が強調されています。つまり、必要なときだけ使う のが基本です。

たとえばPOSTなら、--data や --json を使えばcurl側が自然にPOSTとして送ります。毎回 -X POST を足さなくても動く場面が多いです。

ヘッダーと認証の付け方

APIではヘッダー指定がほぼ必須です。curlでは -H または --header を使います。

curl https://httpbin.org/headers \
  -H "X-Client: sample" \
  -H "Accept: application/json"

Bearerトークンを付ける例です。

curl https://example.com/api/tasks \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

ここで大事なのは、トークンをコマンドに直書きしない ことです。

• シェル履歴に残る
• 画面共有やログに写りやすい
• コピペ時に漏えいしやすい

環境変数に入れる、.env や秘密情報管理サービスで注入する、といった方法を使ったほうが安全です。

実務でよく使うオプション

curlはURLだけでも使えますが、API作業では次のオプションを覚えると一気に実用的になります。

エラーを失敗として扱う

curlはデフォルトでは、HTTP 404や500でも「通信自体ができた」ならエラー終了にしません。公式FAQでもその挙動が説明されています。

スクリプトで失敗検知したいなら、次を付けます。

curl --fail-with-body https://httpbin.org/status/404

--fail-with-body は、レスポンス本文を残しつつ終了コードをエラーにできます。APIのエラー本文を見ながらCIやシェルスクリプトで失敗判定したいときに便利です。

リダイレクトを追う

APIエンドポイントや認証前段でリダイレクトが入ることがあります。

curl -L https://httpbin.org/absolute-redirect/1

-L または --location を付けると、Location ヘッダーに従って再リクエストします。

余計な進捗表示を消して、エラーだけ出す

ログに使うならこの組み合わせが定番です。

curl -sS https://httpbin.org/get

• -s: 進捗やエラーメッセージを抑制
• -S: -s と併用したときにエラー表示は残す

ステータスコードだけを見たい

--write-out を使うと、レスポンスコードを取り出せます。

curl -s -o /dev/null -w "%{response_code}\n" https://httpbin.org/status/201

シェルスクリプトではかなり実用的です。本文を捨てて、201なのか404なのかだけを機械的に判定できます。

詳細な通信内容を追う

接続先、リクエストヘッダー、TLS周りの様子を見たいなら -v を使います。

curl -v https://httpbin.org/get

それでも追い切れないときは --trace-ascii も候補です。長くなるので、ファイルに出すほうが見やすくなります。

再現しやすい最小サンプル集

ここでは、実務でそのまま転用しやすい最小例をまとめます。

1. GETで一覧を取る

curl https://httpbin.org/get

用途:

• APIの疎通確認
• URL到達可否の確認
• ターミナルからの即席テスト

2. クエリ付きGET

curl -G https://httpbin.org/get \
  --data-urlencode "status=open" \
  --data-urlencode "limit=10"

用途:

• 絞り込み条件の確認
• 日本語やスペースを含む検索条件の送信

3. JSONをPOSTする

curl https://httpbin.org/post \
  --json '{"task":"backup","dry_run":true}'

用途:

• 作成APIの確認
• Webhook送信の試験
• バッチ前の手動チェック

4. 認証ヘッダー付きで叩く

curl https://example.com/api/me \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

用途:

• ログイン後APIの疎通確認
• 権限不足やトークン期限切れの切り分け

5. ステータスコードを確認する

curl -s -o /dev/null -w "%{response_code}\n" https://httpbin.org/status/204

用途:

• CIでのヘルスチェック
• API監視の簡易確認

よくある失敗と対処

JSONのクォートが壊れる

特にPowerShellや複数行コマンドで起こりやすい失敗です。

対処:

• JSONを1行で無理に書かない
• payload.json に分けて @payload.json で送る
• まずは最小のキー1つで試す

Content-Type を付け忘れる

JSONを送っているつもりでも、サーバー側ではフォーム扱いになることがあります。

対処:

• 新しいcurlなら --json を使う
• 古いcurlなら -H "Content-Type: application/json" を明示する

-X POST だけ付けて本文を送っていない

メソッドだけPOSTにしても、必要なデータがなければAPI側のバリデーションで落ちることがあります。

対処:

• --data --data-binary --json のどれで送るかを先に決める
• -v や https://httpbin.org/anything で実際に何が送られているか見る

404や500なのにシェルでは成功扱いになる

curlの標準挙動です。本文は返るので、一見うまくいったように見えます。

対処:

• スクリプトでは --fail-with-body を基本候補にする
• 併せて -w "%{response_code}" で記録する

認証情報をコマンドに直書きしてしまう

一度履歴やスクリーンショットに残ると回収が面倒です。

対処:

• 環境変数を使う
• サンプルでは必ずダミー値を使う
• 共有資料には実トークンを載せない

curlと他の方法の使い分け

curlが常に最適とは限りません。向いている場面はかなりはっきりしています。

• curl: 1本のコマンドで素早く試したい、スクリプト化したい、CIで使いたい
• Postman: 複数APIをコレクション管理したい、GUIで整理したい、チーム共有したい
• エディタ拡張のHTTPクライアント: リクエストをファイルで管理したい、コードレビューに載せたい

単発確認や自動化はcurl、継続的なAPI運用はGUIや定義ファイル型ツール と考えると整理しやすいです。

まずはこの4本を使えれば十分

最後に、初心者が最初に手元で試すならこの4本で足ります。

• curl https://httpbin.org/get
• curl -i https://httpbin.org/json
• curl https://httpbin.org/post --json '{"hello":"world"}'
• curl -s -o /dev/null -w "%{response_code}\n" https://httpbin.org/status/200

この4本で、取得、ヘッダー確認、JSON送信、ステータス確認まで一通り触れます。そこから認証ヘッダー、リダイレクト、失敗判定を足していけば、日常的なAPI確認はかなり回せます。

次に見るべきポイントは、自分の現場のAPIで どのヘッダーが必須か、エラー時にどんなJSONが返るか、自動化するならどの終了コードで落としたいか の3つです。curlはそこを最短距離で確認できる道具です。

参照リンク

• curl man page
• curl FAQ
• everything curl: HTTP basics
• everything curl: Method
• everything curl: Request method
• httpbin.org
• httpbin.io