Web
curl — tester et déboguer une API HTTP
Requêtes HTTP, JSON, authentification, cookies, fichiers, erreurs et délais avec curl sur Windows, macOS et Linux.
44commandesMis à jour le7 septembre 2026NiveauIntermédiaire
Aucune commande ne correspond à ce choix et à votre recherche.
Quel échec renvoie curl ?
| Code de sortie | Signification |
|---|---|
0 |
Transfert réussi ; une réponse HTTP 404 reste possible sans option --fail |
6 |
Nom d’hôte introuvable |
7 |
Connexion impossible |
22 |
Erreur HTTP avec --fail ou --fail-with-body |
28 |
Délai dépassé |
60 |
Certificat TLS non validé : corriger le certificat ou l’autorité de confiance |
Exemples pour curl 7.82+, dans Bash/Zsh ou PowerShell. Le filtre Windows utilise curl.exe pour éviter les alias. Adaptez localhost:3000, les routes et les identifiants à votre API de test ; api.example.com est une adresse fictive.
| Fichier utilisé | Contenu attendu |
|---|---|
requete.json |
Corps JSON complet en UTF-8, conforme à votre API |
modification.json |
Champs que votre API accepte de modifier avec PATCH |
document.txt |
Fichier existant à téléverser |
entetes.local |
Une ligne Authorization: Bearer VOTRE_JETON, dans un fichier protégé et ignoré par Git |
L’envoi depuis un fichier évite les différences de guillemets entre shells. --json ne valide pas le JSON. Protégez aussi les fichiers de cookies, qui peuvent donner accès à une session.
Les relances automatiques d’un POST peuvent créer des doublons : suivez le mécanisme d’idempotence de l’API. curl n’applique pas CORS ; pour une requête bloquée dans le navigateur, consultez Corriger une erreur CORS.
Lire la réponse
10 commandes| Commande | Description | Exemple | Risque |
|---|---|---|---|
curl --versionmacOS · Linux | Vérifier la version ; les exemples --json demandent curl 7.82 ou plus récent. | curl --version | Sûr |
curl.exe --versionWindows | Vérifier la version ; les exemples --json demandent curl 7.82 ou plus récent. | curl.exe --version | Sûr |
curl -imacOS · Linux | Afficher les en-têtes et le corps de la réponse. Adapter la route à votre API. | curl -i http://localhost:3000/api/items | Sûr |
curl.exe -iWindows | Afficher les en-têtes et le corps de la réponse. Adapter la route à votre API. | curl.exe -i http://localhost:3000/api/items | Sûr |
curl -ImacOS · Linux | Envoyer HEAD : certains serveurs ne prennent pas cette méthode en charge. | curl -I http://localhost:3000/api/items | Sûr |
curl.exe -IWindows | Envoyer HEAD : certains serveurs ne prennent pas cette méthode en charge. | curl.exe -I http://localhost:3000/api/items | Sûr |
curl --get --data-urlencodemacOS · Linux | Encoder un paramètre de recherche au lieu de construire la query string à la main. | curl --get --data-urlencode "q=café filtre" http://localhost:3000/api/items | Sûr |
curl.exe --get --data-urlencodeWindows | Encoder un paramètre de recherche au lieu de construire la query string à la main. | curl.exe --get --data-urlencode "q=café filtre" http://localhost:3000/api/items | Sûr |
curl --locationmacOS · Linux | Suivre les redirections. Vérifier la destination avant tout appel authentifié. | curl --location --max-redirs 5 http://localhost:3000/api/items | Attention |
curl.exe --locationWindows | Suivre les redirections. Vérifier la destination avant tout appel authentifié. | curl.exe --location --max-redirs 5 http://localhost:3000/api/items | Attention |
Envoyer des données
10 commandes| Commande | Description | Exemple | Risque |
|---|---|---|---|
curl --json @fichiermacOS · Linux | Envoyer un POST JSON depuis un fichier UTF-8 ; ajoute Content-Type et Accept application/json. | curl --json "@requete.json" http://localhost:3000/api/items | Attention |
curl.exe --json @fichierWindows | Envoyer un POST JSON depuis un fichier UTF-8 ; ajoute Content-Type et Accept application/json. | curl.exe --json "@requete.json" http://localhost:3000/api/items | Attention |
curl --request PATCH --jsonmacOS · Linux | Modifier partiellement une ressource, si l’API prend en charge PATCH. Vérifier son identifiant. | curl --request PATCH --json "@modification.json" http://localhost:3000/api/items/42 | Attention |
curl.exe --request PATCH --jsonWindows | Modifier partiellement une ressource, si l’API prend en charge PATCH. Vérifier son identifiant. | curl.exe --request PATCH --json "@modification.json" http://localhost:3000/api/items/42 | Attention |
curl --request PUT --jsonmacOS · Linux | Envoyer la représentation complète attendue par l’API ; PUT peut remplacer la ressource. | curl --request PUT --json "@requete.json" http://localhost:3000/api/items/42 | Attention |
curl.exe --request PUT --jsonWindows | Envoyer la représentation complète attendue par l’API ; PUT peut remplacer la ressource. | curl.exe --request PUT --json "@requete.json" http://localhost:3000/api/items/42 | Attention |
curl --formmacOS · Linux | Téléverser un fichier en multipart. Laisser curl construire le Content-Type et sa boundary. | curl --form "fichier=@document.txt" http://localhost:3000/api/uploads | Attention |
curl.exe --formWindows | Téléverser un fichier en multipart. Laisser curl construire le Content-Type et sa boundary. | curl.exe --form "fichier=@document.txt" http://localhost:3000/api/uploads | Attention |
curl --request DELETEmacOS · Linux | Supprimer la ressource ciblée : utiliser seulement un identifiant de test dont la suppression est voulue. | curl --request DELETE http://localhost:3000/api/items/42 | Danger |
curl.exe --request DELETEWindows | Supprimer la ressource ciblée : utiliser seulement un identifiant de test dont la suppression est voulue. | curl.exe --request DELETE http://localhost:3000/api/items/42 | Danger |
Authentification et cookies
8 commandes| Commande | Description | Exemple | Risque |
|---|---|---|---|
curl --header @fichiermacOS · Linux | Lire les en-têtes sensibles dans un fichier local protégé et ignoré par Git ; ne pas le joindre à un ticket. | curl --header "@entetes.local" https://api.example.com/v1/me | Attention |
curl.exe --header @fichierWindows | Lire les en-têtes sensibles dans un fichier local protégé et ignoré par Git ; ne pas le joindre à un ticket. | curl.exe --header "@entetes.local" https://api.example.com/v1/me | Attention |
curl --usermacOS · Linux | Authentification Basic : curl demande le mot de passe. Utiliser HTTPS et ne pas placer le mot de passe dans la commande. | curl --user utilisateur https://api.example.com/v1/me | Attention |
curl.exe --userWindows | Authentification Basic : curl demande le mot de passe. Utiliser HTTPS et ne pas placer le mot de passe dans la commande. | curl.exe --user utilisateur https://api.example.com/v1/me | Attention |
curl --cookie-jarmacOS · Linux | Conserver les cookies reçus dans un fichier sensible. L’URL doit réellement renvoyer Set-Cookie. | curl --cookie-jar cookies.local http://localhost:3000/api/session | Attention |
curl.exe --cookie-jarWindows | Conserver les cookies reçus dans un fichier sensible. L’URL doit réellement renvoyer Set-Cookie. | curl.exe --cookie-jar cookies.local http://localhost:3000/api/session | Attention |
curl --cookiemacOS · Linux | Envoyer les cookies enregistrés à une route du même site. Le fichier représente potentiellement une session active. | curl --cookie cookies.local http://localhost:3000/api/me | Attention |
curl.exe --cookieWindows | Envoyer les cookies enregistrés à une route du même site. Le fichier représente potentiellement une session active. | curl.exe --cookie cookies.local http://localhost:3000/api/me | Attention |
Diagnostiquer HTTP et réseau
10 commandes| Commande | Description | Exemple | Risque |
|---|---|---|---|
curl --fail-with-bodymacOS · Linux | Renvoyer un code de sortie non nul sur HTTP 400 ou plus, tout en conservant le corps d’erreur. | curl --silent --show-error --fail-with-body http://localhost:3000/api/items | Sûr |
curl.exe --fail-with-bodyWindows | Renvoyer un code de sortie non nul sur HTTP 400 ou plus, tout en conservant le corps d’erreur. | curl.exe --silent --show-error --fail-with-body http://localhost:3000/api/items | Sûr |
curl --connect-timeout --max-timemacOS · Linux | Limiter la phase de connexion à 3 s et la durée totale à 10 s. | curl --connect-timeout 3 --max-time 10 http://localhost:3000/api/items | Sûr |
curl.exe --connect-timeout --max-timeWindows | Limiter la phase de connexion à 3 s et la durée totale à 10 s. | curl.exe --connect-timeout 3 --max-time 10 http://localhost:3000/api/items | Sûr |
curl --verbosemacOS · Linux | Afficher le diagnostic de connexion et les en-têtes ; peut exposer Authorization et les cookies. Nettoyer la sortie avant partage. | curl --verbose http://localhost:3000/api/items | Attention |
curl.exe --verboseWindows | Afficher le diagnostic de connexion et les en-têtes ; peut exposer Authorization et les cookies. Nettoyer la sortie avant partage. | curl.exe --verbose http://localhost:3000/api/items | Attention |
curl --retrymacOS · Linux | Réessayer cette lecture sur les erreurs transitoires prises en charge. Ne pas appliquer aveuglément aux opérations qui créent des données. | curl --retry 2 --retry-max-time 20 --max-time 10 http://localhost:3000/api/items | Sûr |
curl.exe --retryWindows | Réessayer cette lecture sur les erreurs transitoires prises en charge. Ne pas appliquer aveuglément aux opérations qui créent des données. | curl.exe --retry 2 --retry-max-time 20 --max-time 10 http://localhost:3000/api/items | Sûr |
curl --cacertmacOS · Linux | Utiliser le certificat PEM de l’autorité de confiance du projet ; conserver la vérification TLS. | curl --cacert autorite-locale.pem https://localhost:3443/api/items | Sûr |
curl.exe --cacertWindows | Utiliser le certificat PEM de l’autorité de confiance du projet ; conserver la vérification TLS. | curl.exe --cacert autorite-locale.pem https://localhost:3443/api/items | Sûr |
Enregistrer et mesurer
6 commandes| Commande | Description | Exemple | Risque |
|---|---|---|---|
curl --outputmacOS · Linux | Écrire le corps dans un fichier. Écrase le fichier cible s’il existe ; un succès réseau ne garantit pas une réponse HTTP valide. | curl --fail-with-body --output reponse.json http://localhost:3000/api/items | Attention |
curl.exe --outputWindows | Écrire le corps dans un fichier. Écrase le fichier cible s’il existe ; un succès réseau ne garantit pas une réponse HTTP valide. | curl.exe --fail-with-body --output reponse.json http://localhost:3000/api/items | Attention |
curl --dump-headermacOS · Linux | Séparer les en-têtes du corps. Les deux fichiers peuvent contenir des données sensibles et seront écrasés. | curl --dump-header reponse.headers --output reponse.json http://localhost:3000/api/items | Attention |
curl.exe --dump-headerWindows | Séparer les en-têtes du corps. Les deux fichiers peuvent contenir des données sensibles et seront écrasés. | curl.exe --dump-header reponse.headers --output reponse.json http://localhost:3000/api/items | Attention |
curl --write-outmacOS · Linux | Afficher statut HTTP, durée totale en secondes et code après sauvegarde du corps. | curl --silent --show-error --output reponse.json --write-out "HTTP %{http_code} - total %{time_total}s" http://localhost:3000/api/items | Attention |
curl.exe --write-outWindows | Afficher statut HTTP, durée totale en secondes et code après sauvegarde du corps. | curl.exe --silent --show-error --output reponse.json --write-out "HTTP %{http_code} - total %{time_total}s" http://localhost:3000/api/items | Attention |