cURL Quickstart
This quickstart covers the full async flow using cURL.
TL;DR — full flow in one script
Create a job, wait for it, and download the result. Set the three variables and
run it (needs python3, preinstalled on macOS/Linux). Each statement is on its
own line, so it's safe to copy-paste as a block:
KEY="YOUR_API_KEY"
BASE="https://www.redact-pdf.ai"
FILE="/absolute/path/contract.pdf"
RESP=$(curl -sS -X POST "$BASE/v1/jobs" -H "X-API-Key: $KEY" -F "files=@$FILE;type=application/pdf" -F "retention=ephemeral")
JOB=$(printf '%s' "$RESP" | python3 -c "import sys,json;print(json.load(sys.stdin)['job_id'])")
DOC=$(printf '%s' "$RESP" | python3 -c "import sys,json;print(json.load(sys.stdin)['documents'][0]['id'])")
echo "job=$JOB doc=$DOC"
until [ "$(curl -sS -H "X-API-Key: $KEY" "$BASE/v1/jobs/$JOB" | python3 -c 'import sys,json;print(json.load(sys.stdin)["status"])')" = "redacted" ]; do echo " ...processing"; sleep 3; done
curl -sS -OJ -H "X-API-Key: $KEY" "$BASE/v1/documents/$DOC/output" # saves <original-name>-redacted.pdf
No API key? Try it keyless first:
curl -sS https://www.redact-pdf.ai/v1/demoredacts a built-in sample and returns the detected PII. Get a real key at Dashboard → Settings → API keys.
The step-by-step version below explains each call.
1) Set environment variables
export REDACT_API_KEY="YOUR_API_KEY"
export REDACT_BASE_URL="https://www.redact-pdf.ai"
2) Create a job and upload PDFs
POST /v1/jobs accepts multipart/form-data and one or more files.
curl -sS -X POST "$REDACT_BASE_URL/v1/jobs" \
-H "X-API-Key: $REDACT_API_KEY" \
-H "X-Idempotency-Key: demo-job-001" \
-F 'files=@/absolute/path/contract.pdf;type=application/pdf' \
-F 'files=@/absolute/path/invoice.pdf;type=application/pdf' \
-F 'pii_categories=["Person","Email","PhoneNumber","Address"]' \
-F 'retention=ephemeral'
Example response:
{
"job_id": "b3f2b2e0-6f30-4f3e-8a7b-2f2a20a7d91c",
"status": "analyzing",
"retention": "ephemeral",
"documents": [
{
"id": "7f4f4f85-6b7a-4f88-9a8a-7b9a6a2d2fd0",
"file_name": "contract.pdf",
"status": "uploaded"
},
{
"id": "95457f6e-bd9f-4c95-b1b2-b6e86f0137d2",
"file_name": "invoice.pdf",
"status": "uploaded"
}
]
}
3) Poll job status
JOB_ID="b3f2b2e0-6f30-4f3e-8a7b-2f2a20a7d91c"
curl -sS -X GET "$REDACT_BASE_URL/v1/jobs/$JOB_ID" \
-H "X-API-Key: $REDACT_API_KEY"
Wait until each document reaches a terminal state:
- success:
redacted - failure:
error
4) Download each redacted output
DOC_ID="7f4f4f85-6b7a-4f88-9a8a-7b9a6a2d2fd0"
curl -sS -L "$REDACT_BASE_URL/v1/documents/$DOC_ID/output" \
-H "X-API-Key: $REDACT_API_KEY" \
-o contract-redacted.pdf
The response sets Content-Disposition to the original name plus -redacted
(e.g. contract-redacted.pdf), Unicode-safe for non-ASCII names. To let cURL use
that name automatically instead of -o, use -OJ:
curl -sS -OJ "$REDACT_BASE_URL/v1/documents/$DOC_ID/output" -H "X-API-Key: $REDACT_API_KEY"
5) Optionally delete the job
curl -sS -X DELETE "$REDACT_BASE_URL/v1/jobs/$JOB_ID" \
-H "X-API-Key: $REDACT_API_KEY"