Name the PDF file with curl

Without a caller filename the download is named after the conversion id. The filename field renames it at the source: letters, digits, dot, dash, and underscore, up to 100 characters, echoed on the receipt and carried verbatim by the download's Content-Disposition header, where curl's -OJ reads it.

The recipe

ORIGIN="https://webcapture.io"

RECEIPT=$(curl -sS -X POST "$ORIGIN/v1/convert" \
  -H "Authorization: Bearer wc_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/", "filename": "invoice-2026.pdf"}')
echo "$RECEIPT"
# {"id": "cnv_4a7c90be", "bytes": 88210, "attempts": 1,
#  "remaining": 47, "filename": "invoice-2026.pdf",
#  "download": ".../v1/conversions/cnv_4a7c90be.pdf"}

ID=$(printf '%s' "$RECEIPT" | sed -E 's/.*"id": *"([^"]+)".*/\1/')
case "$ID" in cnv_*) ;; *) echo "convert failed: $RECEIPT" >&2; exit 1 ;; esac

# -OJ takes the name from the response's Content-Disposition header:
curl -sS -OJ -H "Authorization: Bearer wc_your_key" \
  "$ORIGIN/v1/conversions/$ID.pdf"
# invoice-2026.pdf lands in the working directory

The name is stored with the conversion, so every later download of this artifact carries it, and ?disposition=attachment on the download url flips the header's token from inline to attachment without touching the name. The filename is presentation only: the url itself is still the id-based one.

Same-key GET: 401 without it; 404 for another key.

The fields this recipe uses

• filename: 1 to 100 characters of letters, digits, dot, dash or underscore; echoed on the receipt and carried by the download's Content-Disposition header.

Related

• Next: Get a free key to run this curl recipe, or read the API docs.
• More recipes: curl: convert from a URL, Python: save to a file, curl: print page ranges.
• The webcapture API reference: every field the convert endpoint admits, with the response shapes and the error table.
• The recipes hub: the same endpoint in the other languages.
• Going deeper: the webcapture vs PDFShift comparison marks filename support on both sides, with the billing contracts beside it.
• The free URL to PDF tool: try the render in a browser before you wire the call.

Method

Source: convert field reference, checked 2026-10-05. Corrections.