curl POST JSON: как отправить запрос из командной строки

Категория: Bash · Язык: Bash · Обновлено:

Чтобы отправить JSON методом POST через curl, укажите заголовок типа содержимого и тело запроса: curl -X POST -H "Content-Type: application/json" -d '{"name":"Анна"}' URL. В новых версиях curl (с 7.82) то же делает короткий ключ --json.

Базовый запрос

Bash
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Анна", "role": "admin"}'

Без заголовка Content-Type: application/json многие серверы ответят ошибкой 400 или 415, потому что curl по умолчанию отправляет данные как обычную форму. Если указан -d, метод POST выбирается автоматически, поэтому -X POST можно не писать.

Короткая запись --json

Bash
curl --json '{"name": "Анна"}' https://api.example.com/users

Ключ --json сам добавляет заголовки Content-Type и Accept со значением application/json и отправляет тело. Он доступен в curl версии 7.82 и новее.

Тело из файла

Bash
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @user.json

Символ @ перед именем файла говорит curl взять тело из файла. Содержимое отправляется без изменений.

Авторизация

Bash
curl -H "Authorization: Bearer token123" https://api.example.com/secure
curl -u anna:secret https://api.example.com/basic

Первый вариант передаёт токен в заголовке, второй использует базовую авторизацию.

Код ответа и тело

Bash
curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/users
curl -i https://api.example.com/users
curl -sS --fail-with-body https://api.example.com/users

Ключ

Что делает

-s

Тихий режим, без индикатора загрузки

-S

Показывать ошибки даже в тихом режиме

-i

Вывести заголовки ответа вместе с телом

-o /dev/null

Отбросить тело

-w "%{http_code}"

Напечатать код ответа

--fail-with-body

Завершиться с ошибкой на 4xx и 5xx, но показать тело

Параметры в адресе, форма и файл

Bash
curl -G https://api.example.com/search --data-urlencode "q=привет мир"
curl -F "file=@report.txt" -F "title=Отчёт" https://api.example.com/upload

Ключ -G превращает данные в параметры адреса, --data-urlencode кодирует их. Ключ -F отправляет форму multipart/form-data, в том числе файл.

Кавычки в Windows

В командной строке Windows одинарные кавычки не работают как обёртка. Используйте двойные и экранируйте внутренние:

Bash
curl.exe -X POST -H "Content-Type: application/json" -d "{\"name\": \"Анна\"}" https://api.example.com/users

В PowerShell вызывайте именно curl.exe, иначе сработает псевдоним Invoke-WebRequest. Для длинного JSON надёжнее хранить тело в файле и использовать -d @user.json.

Частые вопросы

Почему сервер не видит мой JSON?

Обычно не указан Content-Type: application/json, либо в теле лишние кавычки из-за оболочки. Проверьте запрос ключом -v, он показывает отправленные заголовки.

Как отправить переменную в теле?

Используйте двойные кавычки и экранирование, либо соберите JSON через jq: jq -n --arg name "$NAME" '{name: $name}' | curl --json @- URL.

Как отправить запрос с тайм-аутом?

Добавьте --max-time 10 для общего времени и --connect-timeout 3 для установки соединения.