curl을 사용하여 POST 요청을 보내는 방법: 전체 참조

현재 전 세계 어딘가에서 약 200억 개의 curl 설치가 실행되고 있습니다. 이 수치는 curl 개발자인 다니엘 스텐버그가 거의 혼자서 관리하고 있는 도구에 대한 정보입니다. curl은 라우터, 자동차, 위성, 스마트 TV, 대부분의 공용 웹을 지원하는 Linux 서버, 그리고 모든 주요 LLM 런타임에 탑재되어 있습니다. 이러한 설치 환경에서 사용되는 수많은 HTTP 동사 중 POST가 가장 중요한 역할을 합니다. 대부분의 개발자는 curl POST를 사용하여 API를 처음 테스트, 디버깅 또는 통합합니다.

Postman의 2025년 API 현황 보고서에 따르면 REST API 도입률은 93%에 달합니다. 현재 82%의 조직이 최소한 부분적으로 API 우선 방식으로 운영하고 있습니다. POST는 서버에 데이터를 생성, 제출 또는 전송할 때 사용하는 기본 명령어입니다. AI 워크로드는 이러한 추세를 더욱 가속화했습니다. AI 사용으로 인한 API 트래픽은 2024년에 73% 증가했으며(Postman, 2024), 모든 LLM(Learning Language Management) 제공업체의 문서는 이제 표준적인 "첫 번째 호출"로 curl POST 코드 조각을 포함하고 있습니다.

이 문서에서는 curl을 사용한 POST 요청의 모든 형태를 최소한의 한 줄 요청부터 실제 암호화폐 결제 API를 호출하는 예제까지 자세히 살펴봅니다. 목표는 단순히 읽는 것이 아니라, 복사해서 붙여넣을 수 있는 형태로 만드는 것입니다. 서버에 처음 데이터를 전송하거나 새벽 2시에 웹훅 핸들러를 재구축하는 경우에도 아래의 예제들은 실제로 필요한 모든 것을 다룹니다.

아래 표는 POST 요청을 보낼 때 가장 자주 사용되는 curl 명령줄 옵션에 대한 간략한 설명입니다. 각 옵션은 다음 섹션에서 자세히 설명합니다.

curl POST 요청과 HTTP 메서드 이해하기

curl의 POST 요청은 명령줄에서 POST 메서드를 사용하여 전송되는 HTTP POST 요청입니다. curl 도구 자체는 20개 이상의 프로토콜(HTTP는 그중 하나일 뿐)을 통해 "데이터를 전송"하는 역할을 한다고 설명합니다. POST는 "여기에 데이터가 있으니, 이 데이터를 사용하여 무언가를 하세요"라는 의미입니다. 페이로드는 요청 본문에 포함되며, URL에는 절대 포함되지 않습니다. 이러한 특성 때문에 POST는 리소스 생성, 폼 제출, 자격 증명을 전달하는 모든 작업에 사용됩니다. GET 요청은 데이터를 쿼리 문자열에 저장하므로 모든 프록시와 브라우저 기록에 노출됩니다. POST는 그렇지 않습니다.

대부분의 튜토리얼은 작지만 유용한 세부 사항을 간과합니다. `-d` 옵션을 전달하면 curl이 자동으로 POST 방식으로 전환합니다. 명시적으로 `-X POST`를 사용하여 사용할 사용자 지정 요청 메서드를 지정하는 것은 선택 사항입니다. 하지만 페이로드 옆에 `-X POST`가 있으면 의도를 한눈에 파악할 수 있기 때문에 많은 예제에서 여전히 이 옵션을 포함합니다.

PUT과 POST는 자주 혼동되는 명령어이므로 명확하게 구분하는 것이 좋습니다. PUT은 특정 위치의 리소스를 덮어쓰는 작업이고, POST는 새로운 리소스를 생성하거나 처리될 데이터를 특정 엔드포인트로 전송하는 작업입니다.

curl의 기본 POST 구문과 -d 플래그의 실제 사용법

curl POST 요청의 최소 형식은 한 줄입니다.

```

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

```

이게 전부입니다. POST 요청에, 본문은 폼 URL 인코딩을 사용하고, 복잡할 것도 없습니다. `-d` 옵션은 세 가지 역할을 합니다. 페이로드를 요청 본문에 넣고, 요청 방식을 POST로 바꾸고, 기본 헤더로 `Content-Type: application/x-www-form-urlencoded`를 추가합니다. 하지만 코드 리뷰 시에는 POST 의도를 더 명확하게 보여주기 때문에 저는 보통 조금 더 자세한 코드를 붙여넣습니다.

```

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

```

전송되는 바이트도 동일하고, 요청 인자도 동일합니다. 팀에서 스캔하기 더 쉽다고 생각하는 방식을 사용하세요. `-d` 플래그는 명령줄에서 서버로 데이터를 전송할 때 가장 많이 사용되는 옵션으로, 백엔드 개발자가 curl에 입력하는 대부분의 요청(셸 호출, 웹훅 테스트, Makefile 대상, GitHub Actions 단계 등)을 처리합니다.

`-d` 옵션의 세 가지 유사 옵션입니다. `--data-binary`는 바이트를 그대로 유지하지만, 일반 `-d`는 줄 바꿈을 제거하고 바이너리 페이로드를 손상시킵니다. `--data-urlencode`는 백분율 인코딩을 적용합니다. 예를 들어 `--data-urlencode "name=I am Daniel"`는 `name=I%20am%20Daniel`로 변환됩니다. `--data-raw`는 값이 `@`로 시작할 때 curl이 파일을 읽지 않아야 하는 경우에 사용하는 예외 옵션입니다. 여러 개의 `-d` 플래그는 `&`로 결합됩니다. 폼 작성에는 적합하지만 JSON에는 절대 사용하지 마세요.

마지막으로 한 가지 주의할 점은 따옴표 사용법입니다. 페이로드를 작은따옴표로 묶으면 셸이 '$'나 백슬래시를 잘못 해석하게 됩니다. 따옴표를 사용하지 않으면 새벽 2시에 POST 데이터의 절반이 누락된 이유를 찾느라 시간을 허비하게 될 겁니다.

이러한 세부 사항은 curl 자체가 전 세계에서 가장 철저하게 테스트된 HTTP 클라이언트 중 하나이기 때문에 중요합니다. 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` 플래그를 사용할 수 없으며, 이전의 세 가지 플래그를 사용하는 방식으로 돌아갑니다.

curl 명령어를 사용하여 JSON 데이터를 전송할 때 --json 또는 -H 옵션을 사용합니다.

JSON은 2026년 REST API의 공통 언어입니다. curl을 사용하여 JSON을 POST하는 방법은 두 가지가 있습니다. 어떤 방법을 사용할지는 컴퓨터에 설치된 curl 버전에 따라 완전히 달라집니다.

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` 플래그는 세 가지 기능을 수행합니다. `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

```

두 번째 패턴은 `order.json`이라는 파일에서 데이터를 읽어 필요한 헤더와 함께 전송합니다. 대용량 또는 바이너리 JSON 콘텐츠의 경우 `--data-binary @file.json` 옵션이 더 안전합니다. 이 옵션은 줄 바꿈을 제거하지 않고 특수 문자를 해석하지 않으며, 폼 필드가 아닌 바이트를 예상하는 엔드포인트로 원시 바이너리 데이터를 전송합니다. 세 번째 패턴은 `-d @-` 옵션을 통해 표준 입력(stdin)에서 데이터를 읽습니다. 다른 명령의 출력을 curl POST 요청으로 바로 파이프할 때 유용합니다.

아래 표는 네 가지 일반적인 JSON 형식을 단일 엔드포인트에 매핑한 것입니다.

이는 예전보다 훨씬 더 중요해졌습니다. OpenAI, Anthropic, Mistral, Google 등 모든 주요 LLM 제공업체는 API 문서 서두에 바로 이 형태를 사용하는 curl POST 예제를 제공합니다. 2024년에는 AI 기반 트래픽이 전체 API 호출량을 73% 증가시켰습니다(Postman). 이제 curl은 "이 엔드포인트를 어떻게 호출하나요?"라는 질문에 대한 표준 참조 도구가 되었습니다.

Content-Type, 헤더 및 curl이 가정하는 사항

대부분의 "415 Unsupported Media Type" 오류는 헤더 하나가 누락되었기 때문입니다. `-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번) 몇 초 안에 오류를 발견할 수 있습니다.

두 가지 추가 사항입니다. Content-Length는 curl이 본문 크기에 따라 자동으로 설정하므로, 일반적으로 재정의할 필요가 없습니다. `Accept: application/json`은 서버가 HTML 대신 JSON 형식으로 응답하도록 지시하는 옵션입니다. 이를 위해서는 `-H` 옵션을 추가하거나, Content-Type과 Accept를 함께 설정하는 `--json` 옵션을 사용할 수 있습니다.

curl POST -F를 사용한 폼 데이터 및 파일 업로드

HTML 스타일 폼 데이터를 파일로 전송할 때는 `-F` 플래그를 사용하는 것이 좋습니다. 이 플래그는 `multipart/form-data` 요청을 생성합니다. 이는 `-d` 플래그가 기본값으로 사용하는 URL 인코딩된 콘텐츠 유형과는 다릅니다. 개념적인 접근 방식도 다릅니다. 간단한 튜토리얼에서 이 두 가지를 혼동하는 경우가 많아 실제 버그가 발생하기도 합니다.

필드당 한 번씩 `-F` 옵션을 사용합니다. 일반 형식 필드:

```

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` 플래그를 사용하면 여러 필드 또는 파일을 하나의 요청으로 묶을 수 있습니다.

```

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년에는 거의 모든 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에 유출된 새로운 시크릿은 2,380만 개에 달하며, 이는 2023년 대비 25% 증가한 수치입니다. 이 중 90% 이상은 유출 후 5일이 지나도 유효한 상태를 유지했습니다. curl 스크립트에 자격 증명을 직접 입력하는 것이 이러한 유출의 주요 원인입니다. 아래 보안 섹션에서 워크플로를 자세히 설명합니다.

실제 curl POST 예시: Plisio 결제 API

실제 예제가 없는 참고 문서는 이론에 불과합니다. 아래 curl POST 요청은 Plisio의 REST API를 통해 암호화폐 결제 청구서를 생성합니다. Plisio는 0.5%의 고정 수수료를 부과하며, 카드 결제 처리 업체는 일반적으로 2~4%의 수수료를 부과합니다. Plisio는 30개 이상의 암호화폐를 지원하고 19개의 전자상거래 플랫폼과 연동됩니다.

암호화폐 API가 연습 대상으로 적합한 이유. 스테이블코인은 2025년까지 약 28조 달러의 실질 경제 거래량을 기록할 것으로 예상됩니다. 체이나리시스는 2023년 이후 연평균 133%의 성장률을 전망했습니다. 암호화폐 결제 게이트웨이 시장은 2025년에 약 20억 달러 규모에 이를 것으로 예상되며, 2026년에는 23억 9천만 달러에 이를 것으로 전망됩니다(비즈니스 리서치 컴퍼니 자료). BitPay, Coinbase Commerce, Plisio 등 어떤 게이트웨이든 첫 번째 통합 단계는 거의 항상 curl POST 요청을 보내는 것입니다.

새 송장을 생성하기 위한 최소한의 호출:

```

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

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

-H "인증: 베어러 $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 요청 실패는 디버깅 퍼즐과 같습니다. 이유 없이 무턱대고 재시도하는 것은 최악의 선택입니다. 명령줄에서 사용할 수 있는 네 가지 옵션으로 대부분의 문제를 해결할 수 있습니다.

`-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`와 같은 사전 커밋 훅을 실행합니다. 셸 히스토리에 남아 있는 모든 토큰을 주기적으로 교체합니다. 이 모든 과정은 흥미롭지 않지만 효과적입니다. 모든 curl POST 요청에 이 방법을 적용하는 것은 2026년에 백엔드 개발자가 갖춰야 할 가장 중요한 습관입니다.

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.