How to Send a DELETE Request Using cURL (with Headers, Authentication, JSON, and Safe Troubleshooting)

Send a DELETE request with cURL by selecting the method explicitly and supplying the resource URL:

curl --request DELETE https://api.example.com/resource/123

The shorter equivalent is curl -X DELETE https://api.example.com/resource/123. Replace the URL with the endpoint documented by your API. DELETE asks the server to remove the resource identified by that URL; cURL only sends the request, while the API determines whether deletion is authorized and successful.

#	Preview	Product	Price
1		Dan Gookin's Guide to Curl Programming	$11.95	Buy on Amazon
2		Curly Girl: The Handbook	$8.19	Buy on Amazon
3		The C Programming Language	$42.74	Buy on Amazon
4		Curl by Example	$0.99	Buy on Amazon
5		A Practical Guide to Curl (Programming Series)	$24.99	Buy on Amazon

The basic DELETE command

--request DELETE (or -X DELETE) changes the HTTP method word sent by cURL. A complete minimal command is:

curl --request DELETE https://api.example.com/resource/123

Use --request when readability matters in scripts. -X is convenient interactively, but it only changes the method word; it does not redesign how cURL handles data, redirects, authentication, or response output. Keep a DELETE command simple unless the endpoint documentation requires additional options.

#1 Best Overall

Dan Gookin's Guide to Curl Programming

$11.95

Buy on Amazon

What the URL means

The URL identifies the resource the server should act on. Check path parameters, API version, tenant or account identifiers, and whether the endpoint expects a trailing slash. Accidentally targeting a collection, another environment, or another account can delete the wrong object.

Inspect the response

By default, cURL writes the response body to your terminal. Add headers or verbose diagnostics when investigating an endpoint:

curl --include --request DELETE https://api.example.com/resource/123

curl --verbose --request DELETE https://api.example.com/resource/123

--include prints response headers with the body. --verbose shows connection, request, and response details; do not paste its output publicly if it contains credentials or sensitive data.

Add required headers

APIs commonly require an Accept header and an authentication header. Use one --header (or -H) option per field:

curl --request DELETE 
  --header 'Accept: application/json' 
  --header 'Authorization: Bearer REDACTED_TOKEN' 
  https://api.example.com/resource/123

Use the authentication scheme specified by the service. A bearer token is only an example; some APIs require an API-key header, signed request, session cookie, or another mechanism. Never substitute a token format merely because it appears in a different API’s documentation.

Basic authentication

For an endpoint that explicitly documents HTTP basic authentication, cURL’s -u or --user option supplies the username and password:

Rank #2

Sale

Curly Girl: The Handbook

• Workman publishing
• Binding: paperback
• Language: english

$8.19

Buy on Amazon

curl --request DELETE 
  --user "$API_USER:$API_PASSWORD" 
  https://api.example.com/resource/123

Environment variables keep the secret out of the command text you save. Shell history, process listings, CI logs, and verbose output can still expose credentials, so use your platform’s secret store and redact logs.

Can a DELETE request contain JSON?

There is no generally defined, portable meaning for a DELETE request body. HTTP specifications do not assign common semantics to DELETE content, and servers may reject a request that contains one. Many APIs therefore encode the target and deletion options in the URL and headers instead.

When the API explicitly documents a body

If the endpoint contract specifically requires JSON, send exactly the documented media type and schema:

curl --request DELETE 
  --header 'Content-Type: application/json' 
  --header 'Accept: application/json' 
  --header 'Authorization: Bearer REDACTED_TOKEN' 
  --data '{"reason":"duplicate"}' 
  https://api.example.com/resource/123

--data makes cURL send content; the Content-Type header tells the server how to parse it. This pattern is not portable to arbitrary DELETE endpoints. Test it against a non-production resource first and follow the API’s documented field names, validation rules, and size limits.

Prefer query parameters only when documented

Some services document options such as a purge flag or version in query parameters. Do not invent parameters: an undocumented value may be ignored or may change which resource is selected.

Authentication and authorization checks

1. Confirm that the token, key, or user is allowed to delete this specific resource.
2. Check whether the API requires a scope such as delete:resources, an account identifier, or an anti-forgery mechanism.
3. Use the service’s staging or test project before production.
4. Verify the URL and request body immediately before execution.

A successful HTTP status only describes what the target API reported. cURL cannot determine whether a business workflow, asynchronous deletion, retention policy, or downstream cleanup has completed. Read the response body and the endpoint documentation.

Rank #3

The C Programming Language

$42.74

Buy on Amazon

DELETE is idempotent, but it is not safe

HTTP defines DELETE as idempotent: repeating the same request is intended to have the same effect as making it once. That does not make it harmless. The first successful request can remove data, trigger billing changes, revoke access, or start an irreversible workflow. Idempotence also does not guarantee that every repeated response has the same status code; the server may report “not found” after the first deletion.

Before running a destructive command, confirm the environment, resource identifier, authorization scope, backup or recovery plan, and the API’s response semantics. For automation, add an explicit approval step or allow-list rather than accepting arbitrary URLs.

Redirects: do not follow blindly

cURL does not automatically follow redirects. --location enables following them:

curl --location --request DELETE https://api.example.com/resource/123

Use this only when the endpoint’s redirect behavior is understood. cURL warns that a method selected with --request is used for requests while following redirects. A redirect can therefore send DELETE to a later location, potentially causing an unintended side effect or crossing an authority boundary. First inspect redirects in a safe environment, then configure the API’s canonical URL instead of relying on automatic forwarding when possible.

Response handling in scripts

Keep body and status separate

Capture the body and print the HTTP status so a script can make an explicit decision:

status=$(curl --silent --show-error 
  --output response.json 
  --write-out '%{http_code}' 
  --request DELETE 
  --header "Authorization: Bearer $API_TOKEN" 
  https://api.example.com/resource/123)

printf 'HTTP status: %sn' "$status"
cat response.json

Interpret the status according to the API contract. Common possibilities include a success response with a body, a success response with no body, an authorization failure, a missing resource, validation failure, rate limiting, or a server error. Do not treat an empty body as proof that deletion failed or succeeded.

Rank #4

Curl by Example

$0.99

Buy on Amazon

Write a response to a file

curl --request DELETE 
  --header 'Accept: application/json' 
  https://api.example.com/resource/123 
  --output delete-response.json

Protect response files if they contain identifiers, audit details, or personal data.

Equivalent examples in Python and Node.js

These examples use the same method, URL, and bearer-token concept. They are useful when a larger application already manages retries, secrets, and structured response handling.

Python with requests

import os
import requests

url = "https://api.example.com/resource/123"
headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
}

response = requests.delete(url, headers=headers, timeout=30)
print(response.status_code)
print(response.text)

Add a JSON body only if the API documents one, for example with json={"reason": "duplicate"}. Set a finite timeout and handle the service’s documented status codes.

Node.js with fetch

const response = await fetch('https://api.example.com/resource/123', {
  method: 'DELETE',
  headers: {
    'Accept': 'application/json',
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
});

console.log(response.status);
console.log(await response.text());

In production code, check response.ok or the exact statuses documented by the API, and handle network errors separately from HTTP errors.

Common errors and fixes

401 Unauthorized or 403 Forbidden

• Verify the token has not expired and is sent in the required header or authentication scheme.
• Check scopes, roles, account IDs, IP restrictions, and environment-specific credentials.
• Ensure shell quoting did not remove or alter the credential.

404 Not Found

• Check the resource ID, API version, region, tenant, and trailing slash.
• Some APIs intentionally return 404 when the resource is already deleted or hidden from the caller; follow that API’s documentation.

400 or 415 after adding JSON

• Remove the body unless the endpoint explicitly requires it.
• Validate JSON syntax and use the documented Content-Type.
• Confirm property names, required fields, and whether the API expects query parameters instead.

405 Method Not Allowed

The URL may not support DELETE, or a gateway may expose a different route. Check the endpoint documentation and allowed methods. Changing -X to another spelling will not make an unsupported operation work.

301, 302, or 307 responses

Use the canonical API URL, inspect the Location header, and avoid --location until you know where the destructive request will go. A proxy, HTTP-to-HTTPS redirect, or missing path segment is often the cause.

Best Value

Sale

A Practical Guide to Curl (Programming Series)

• Used Book in Good Condition

$24.99

Buy on Amazon

Timeouts, connection failures, or TLS errors

• Confirm DNS, proxy, firewall, and VPN settings.
• Use --verbose for diagnosis without exposing its output.
• Retry only when the API documents safe retry behavior. Idempotence reduces duplicate-effect risk but does not solve partial workflows, authorization changes, or network ambiguity.

Performance, retries, and operational safety

DELETE is normally a single HTTP request, so command performance is dominated by DNS, TLS setup, network latency, and server processing. For many resources, use an API’s documented bulk or asynchronous deletion endpoint rather than launching uncontrolled parallel commands. Respect rate limits and record the URL, timestamp, status, and request identifier without logging secrets.

When a connection breaks after the request may have reached the server, do not blindly repeat it. First query the resource or audit endpoint if the API provides one, then follow its retry guidance. A client-side timeout does not prove that the server did nothing.

Or skip the browser setup

If your next task is capturing a clean screenshot of an API result or documentation page, ScreenshotNeo provides a screenshot API and MCP server rather than requiring you to configure a browser. One GET request returns PNG, JPEG, WebP, or PDF:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo documentation for parameters. It accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

Frequently Asked Questions

Should I use -X DELETE or --request DELETE?

They select the same HTTP method. --request is more self-documenting; neither option changes the endpoint’s contract or authorization rules.

What should I do if the command returns no response body?

Check the HTTP status and headers with --include or --write-out. Many deletion endpoints intentionally return an empty body; the API documentation defines whether that status represents success.

Is it safe to retry a timed-out DELETE?

Not automatically. The request may have reached the server. Query the resource or audit state first when possible and follow the API’s retry guidance.

Quick Recap

Bestseller No. 1

Dan Gookin's Guide to Curl Programming

$11.95

SaleBestseller No. 2

Curly Girl: The Handbook

Workman publishing; Binding: paperback; Language: english

$8.19

Bestseller No. 3

The C Programming Language

$42.74

Bestseller No. 4

Curl by Example

$0.99

SaleBestseller No. 5

A Practical Guide to Curl (Programming Series)

Used Book in Good Condition

$24.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.