HTTPie: test an API simply

HTTPie is a command-line HTTP client designed to simplify interactions with RESTful APIs (in French). Unlike tools such as curl, it relies on a clear syntax, coloured output and native support for JSON (in French), which makes exchanges more readable and easier to debug. Whether to test an API quickly, send requests with authentication or automate checks in a script, HTTPie is a valuable ally for system administrators and developers.

What you will learn

• Install HTTPie and run a first request.
• Read a coloured response (headers + JSON body).
• Send JSON data and forms simply.
• Handle authentication and persistent sessions.
• Compare HTTPie with curl to choose the right tool.

This guide is validated with HTTPie 3.2.4, the latest published version (November 2024), replayed on Debian 13 against a local httpbin service.

Installing HTTPie

HTTPie can be installed on most operating systems, whether Linux, macOS or Windows. Here are the different recommended methods.

On Linux

On Debian, Ubuntu and derivatives:

sudo apt update
sudo apt install httpie

On Fedora:

sudo dnf install httpie

On RHEL 10 and AlmaLinux 10, no httpie package exists, neither in the base repositories nor in EPEL (No matching Packages to list, checked on AlmaLinux 10.2): go through pipx or Nix.

On Arch Linux:

sudo pacman -S httpie

On macOS

With Homebrew, the installation is quick:

brew install httpie

On Windows

Use choco (Chocolatey):

choco install httpie

Or scoop:

scoop install httpie

Universal method with pipx

If you have Python installed, prefer pipx, which isolates HTTPie in its own virtual environment. A direct pip install httpie is refused on Debian 13 with error: externally-managed-environment, to protect the system's Python packages:

pipx install httpie

Then check that everything works:

http --version

This command must return the version number of HTTPie, proving that the installation succeeded.

Basic syntax and simple requests

To illustrate the basic syntax of HTTPie, we will use the free test API JSONPlaceholder, often used to simulate HTTP requests.

Simple GET request

To fetch the list of posts:

http https://jsonplaceholder.typicode.com/posts

To fetch a specific post (for example, ID 1):

http https://jsonplaceholder.typicode.com/posts/1

GET request with parameters

To add a filter (for example, the posts of user 1):

http https://jsonplaceholder.typicode.com/posts userId==1

Note: == is used for URL parameters.

POST request with JSON data

To create a new post, you can send a JSON object like this:

http POST https://jsonplaceholder.typicode.com/posts \
  title="Titre de test" body="Ceci est un post." userId:=1

The = sends a character string, whereas := forces sending an integer or raw JSON.

PUT request for an update

To modify an existing post:

http PUT https://jsonplaceholder.typicode.com/posts/1 \
  title="Titre mis à jour" body="Contenu modifié" userId:=1

DELETE request

To delete a post (even though this API does not really delete it):

http DELETE https://jsonplaceholder.typicode.com/posts/1

Adding HTTP headers

You can set custom headers, such as accepting JSON:

http GET https://jsonplaceholder.typicode.com/posts Accept:application/json

In a terminal, HTTPie shows the response received, headers then body, in a readable and coloured way. Add -v to also see the request sent, which is very handy for quick debugging.

Controlling the display with --print

The --print option picks the parts displayed: H for the request headers, B for its body, h for the response headers, b for its body. --print=hb reproduces the terminal display, --print=h keeps only the headers. When the output goes into a pipe or a file, HTTPie only writes the body, hence | jq working well:

http --print=h GET https://jsonplaceholder.typicode.com/posts/1

Handling JSON data and forms

HTTPie greatly eases sending JSON data and forms, thanks to a simple and expressive syntax.

Sending JSON data

By default, HTTPie sends the data as JSON with the POST command:

http POST https://jsonplaceholder.typicode.com/posts \
  title="Nouveau post" body="Contenu du post" userId:=1

• The = sign indicates a character string.
• The := sign sends a raw value (integer, boolean, JSON, etc.).

This sends a JSON body equivalent to:

{
  "title": "Nouveau post",
  "body": "Contenu du post",
  "userId": 1
}

Submitting HTML forms

To send data like an HTML form (application/x-www-form-urlencoded), use the -f option:

http -f POST https://example.com/form login=admin password=1234

Uploading files

To send a file with a form field, use @:

http -f POST https://example.com/upload fichier@chemin/vers/fichier.txt

This creates a multipart request with the file attached in the fichier field.

Adding headers for the content type

You can also set the content type if needed:

http POST https://api.exemple.com/donnees Content-Type:application/json nom="Jean"

HTTPie often detects the right format automatically, but you can force the header if needed.

Authentication and persistent sessions

HTTPie supports several authentication methods, ideal to interact with secured APIs. It can also keep persistent sessions to avoid repeating the credentials.

Basic authentication (Basic Auth)

To use basic HTTP authentication, simply give the user:password pair:

http -a admin:secret https://example.com/protected

HTTPie automatically encodes the credentials in Base64. Written this way, however, the password stays in the shell history and in the process arguments, visible through ps aux. In interactive use, give only the user, http -a admin https://example.com/protected: the HTTPie 3.2.4 documentation states that it then asks for the password through a masked prompt.

Token authentication (Bearer)

Modern APIs often use Bearer tokens in the Authorization header:

http GET https://api.example.com/secure Authorization:"Bearer VOTRE_JETON"

Using persistent sessions

With the --session option, HTTPie can save a session (cookies, headers) to a file:

http --session=ma-session -a admin:secret https://example.com/login

The following requests automatically reuse this session:

http --session=ma-session https://example.com/protected

This lets you simulate authenticated browsing, as in a browser. The session file, stored under ~/.config/httpie/sessions/<host>/, nevertheless keeps the admin:secret pair in clear text in its raw_auth field: treat it as a secret, with chmod 600, and delete it after use.

Example with a real API: GitHub

Authentication with a GitHub personal access token:

http GET https://api.github.com/user Authorization:"Bearer MON_JETON_GITHUB"

This request returns the information of the profile associated with the token.

Sessions and authentication let you test secured APIs without typing the credentials again on each request, while keeping a user context.

Advanced features

HTTPie offers several powerful options to refine your requests, automate tasks or work in particular conditions.

Offline mode (--offline)

Useful to preview the request without sending it. It shows exactly what would be sent:

http --offline POST https://example.com apiKey=1234 data="test"

HTTPie generates and prints the complete HTTP request without any network connection.

Downloading files (--download)

To download a file while honouring the Content-Disposition header:

http --download GET https://example.com/fichier.zip

The file is automatically named and saved locally.

Sending requests with multiple files

HTTPie supports multipart for several files:

http -f POST https://example.com/upload \
  fichier1@doc.pdf fichier2@image.jpg

Using proxies

To go through an HTTP or HTTPS proxy:

http --proxy=https:http://localhost:8080 GET https://example.com

The prefix before the colon designates the scheme of the target URL, not that of the proxy. A --proxy=http:... only applies to http:// URLs: on an https:// URL, it is ignored without any message and the request goes out directly.

Skipping SSL verification

For test environments or self-signed servers:

http --verify=no https://localhost:8443

Setting a timeout

To control the maximum waiting time:

http --timeout=5 GET https://example.com

These features let you adapt HTTPie to advanced scenarios, including network debugging, connectivity testing or error simulation in a pipeline.

Integration into DevOps workflows

HTTPie fits easily into shell scripts and CI/CD pipelines, which makes it a valuable tool for DevOps and system administrators.

Automating API tests in a script

HTTPie can be used in a Bash script to check the availability of a service:

#!/bin/bash
http --ignore-stdin --check-status --timeout=5 GET https://api.monsite.com/health || echo "Service indisponible"

The --check-status option returns a non-zero error code if the HTTP response is a failure code: 4 for a 4xx, 5 for a 5xx, handy for automated tests.

In a script or a CI job, also add --ignore-stdin. When standard input is not a terminal, HTTPie reads it as the request body: a simple http GET then goes out as a POST, and a key=value field causes the error Request body (from stdin, --raw or a file) and request data (key=value) cannot be mixed.

Integration into a CI/CD pipeline

In a CI configuration file (such as GitLab CI, GitHub Actions or Jenkins), HTTPie lets you test API calls after a deployment. The secret comes from a masked CI variable, never from a value written in clear text in the file, which anyone with access to the repository could read:

test_api:
  script:
    - http --ignore-stdin --check-status POST https://api.monsite.com/reload secret="$RELOAD_SECRET"

Checking a deployment

To check that the latest version of an API is online:

http GET https://api.monsite.com/version

You can even extract specific data thanks to jq:

http GET https://api.monsite.com/version | jq .version

Comparison with Postman and Insomnia

Tool	Interface	Automation	Terminal
HTTPie	CLI	Yes	Yes
Postman	GUI	Medium	No
Insomnia	GUI	Medium	No

Swipe to see more

HTTPie is often preferred for server environments, pipelines and command-line tests, whereas Postman is better suited to visual use on a local workstation.

This flexibility makes HTTPie a tool perfectly aligned with modern DevOps practices.

Key points

1. HTTPie is a command-line HTTP client more readable than curl: coloured output, native JSON, a clean syntax.
2. http GET <url> is enough for a request; a key=value field becomes JSON, a key:value a header.
3. The --print=hb option controls the display (headers h, body b) to show only what is useful.
4. Persistent sessions keep the authentication between requests.
5. HTTPie complements curl: curl for portable scripts and low level, HTTPie for API testing comfort.

Knowledge check

Check that the essentials of this guide are acquired. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions

6 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

More information

These two links lead to the official documentation of the HTTPie CLI and to its source repository.

• Official documentation
• Project

×

See in the glossary →