cURL

cURL is a versatile command-line tool available on virtually every operating system. It is ideal for quick tests, shell scripts, and CI/CD pipelines.

Basic Example

Generate a PDF and save it to a file:

curl -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Hello from DoCreate</h1><p>Generated with cURL.</p>",
    "css": "h1 { color: #2563eb; } p { color: #555; }"
  }' \
  --output document.pdf

If the request succeeds, the file document.pdf will be created in the current directory.

Using Environment Variables

Avoid pasting your API key directly into commands. Store it in an environment variable instead:

export DOCREATE_API_KEY="your_api_key_here"

curl -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer $DOCREATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Secure Example</h1>",
    "css": "h1 { color: #333; }"
  }' \
  --output document.pdf

Reading HTML from a File

For larger templates, store your HTML in a file and reference it in the request:

# Create a JSON payload file
cat > payload.json << 'EOF'
{
  "html": "<h1>Invoice #1042</h1><p>Date: 2026-02-17</p><table><tr><th>Item</th><th>Amount</th></tr><tr><td>Web Development</td><td>$2,500.00</td></tr></table>",
  "css": "body { font-family: Arial, sans-serif; padding: 40px; } h1 { color: #1a1a1a; } table { width: 100%; border-collapse: collapse; } th, td { border: 1px solid #ddd; padding: 8px; }"
}
EOF

# Send the request using the file
curl -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer $DOCREATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json \
  --output invoice.pdf

The @ prefix tells cURL to read the request body from the specified file.

With Verbose Output

Use the -v flag to see full request and response headers, which is helpful for debugging:

curl -v -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer $DOCREATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Debug Test</h1>"}' \
  --output test.pdf

Checking for Errors

By default, cURL does not treat HTTP error codes (4xx, 5xx) as failures. Use --fail to make cURL return a non-zero exit code on HTTP errors:

curl --fail -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer $DOCREATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Test</h1>"}' \
  --output test.pdf

if [ $? -ne 0 ]; then
  echo "PDF generation failed"
  exit 1
fi

Alternatively, use -w to inspect the HTTP status code:

HTTP_CODE=$(curl -s -o output.pdf -w "%{http_code}" \
  -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer $DOCREATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Test</h1>"}')

if [ "$HTTP_CODE" -ne 200 ]; then
  echo "Error: HTTP $HTTP_CODE"
  cat output.pdf  # Error responses are JSON
  exit 1
fi

echo "PDF generated successfully"

Setting a Timeout

For complex templates, you may want to increase the timeout:

curl -X POST https://api.docreate.io/api/pdf/external \
  -H "Authorization: Bearer $DOCREATE_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 30 \
  -d '{"html": "<h1>Large Document</h1>"}' \
  --output document.pdf

Shell Script Example

A complete shell script for generating PDFs in a CI/CD pipeline or batch process:

#!/bin/bash
set -euo pipefail

API_URL="https://api.docreate.io/api/pdf/external"
OUTPUT_DIR="./generated"

if [ -z "${DOCREATE_API_KEY:-}" ]; then
  echo "Error: DOCREATE_API_KEY is not set"
  exit 1
fi

mkdir -p "$OUTPUT_DIR"

generate_pdf() {
  local filename="$1"
  local html="$2"
  local css="${3:-}"

  local payload
  payload=$(jq -n --arg html "$html" --arg css "$css" \
    '{html: $html, css: $css}')

  local http_code
  http_code=$(curl -s -o "$OUTPUT_DIR/$filename" -w "%{http_code}" \
    -X POST "$API_URL" \
    -H "Authorization: Bearer $DOCREATE_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$payload")

  if [ "$http_code" -ne 200 ]; then
    echo "Failed to generate $filename (HTTP $http_code)"
    return 1
  fi

  echo "Generated $OUTPUT_DIR/$filename"
}

generate_pdf "report.pdf" "<h1>Monthly Report</h1><p>February 2026</p>" "h1 { color: #333; }"
generate_pdf "summary.pdf" "<h1>Summary</h1><p>All systems operational.</p>"