Curl GET JSON Example

Fetching JSON is a GET with one header that says what you want back. The rest is making the answer usable: readable in a terminal, filterable in a pipeline, and honest about failures.

Last updated . How this page is checked.

The command

curl -H "Accept: application/json" https://httpbin.org/json

Opens the request console with this request filled in. It is sent from api-tester.com's server rather than from your machine, so it shows what the endpoint returns, not how your own network or curl build behaves.

What the flags do

FlagWhat it does
-H "Accept: application/json"Asks for JSON. Many APIs return it anyway; some default to XML or HTML without this.
-sSilent, so the progress meter does not end up in your pipe.
--compressedRequest gzip or brotli and decompress automatically.
-fExit non-zero on a 4xx or 5xx instead of printing the error body as if it were data.

Pretty-printing and filtering

APIs send JSON minified. Pipe it to jq to indent and colour it, or to pull out one field. If jq is not installed, Python's built-in formatter does the indenting.

curl -s https://httpbin.org/json | jq .
curl -s https://httpbin.org/json | jq -r '.slideshow.title'
curl -s https://httpbin.org/json | python3 -m json.tool

Making failures visible

Curl exits with status 0 for any completed HTTP exchange, including a 500. In a pipeline that means an HTML error page gets handed to jq, which then fails with a confusing parse error. -f turns HTTP errors into a non-zero exit; --fail-with-body (curl 7.76+) does the same while still printing the error body, which is usually the JSON that explains what went wrong.

curl -sS --fail-with-body -H "Accept: application/json" \
  https://httpbin.org/status/503 | jq . || echo "request failed"

Common mistakes

  • Accept describes the response, Content-Type the request body. A GET has no body, so Content-Type on it does nothing useful.
  • Binary gibberish in the terminal means the server sent a compressed response. Add --compressed.
  • A 406 Not Acceptable means the server cannot produce the format you asked for; check the spelling of the media type.

Related curl examples

Curl POST JSON Example

Sending JSON takes two things: the JSON itself and a header saying that is what it is.

Curl GET Request Example

GET is what curl does when you give it nothing but a URL.

Curl Send Header Example

-H adds a header line to the request.

Curl Bearer Token Auth Header Example

A bearer token is a credential you present in a header; whoever holds it is treated as its owner.

All Curl Examples

49 worked examples, grouped by what you are trying to do.

More under Request bodies

References

  • curl man page: -H — Adding a request header such as Accept.
  • MDN: Accept — How a client states which response formats it wants.
  • jq manual — The filter language used to format and query the response.

These links leave api-tester.com, which is independent of the projects they point to.

FAQ

How do I get JSON from an API with curl?

Send a GET request with an Accept header: curl -H "Accept: application/json" URL. The response body is printed to the terminal.

How do I pretty-print JSON from curl?

Pipe the output to jq, for example curl -s URL | jq . — the -s flag keeps the progress meter out of the pipe.

How do I make curl fail when the API returns an error?

Add -f to exit with a non-zero status on HTTP 4xx and 5xx responses, or --fail-with-body to do so while still printing the error response.