# 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:

```bash
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/demo`
> redacts 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

```bash
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.

```bash
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:

```json
{
  "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

```bash
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

```bash
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`:

```bash
curl -sS -OJ "$REDACT_BASE_URL/v1/documents/$DOC_ID/output" -H "X-API-Key: $REDACT_API_KEY"
```

## 5) Optionally delete the job

```bash
curl -sS -X DELETE "$REDACT_BASE_URL/v1/jobs/$JOB_ID" \
  -H "X-API-Key: $REDACT_API_KEY"
```

## Next steps

- [Jobs API reference](https://www.redact-pdf.ai/docs/api-reference/jobs.md)
- [Documents API reference](https://www.redact-pdf.ai/docs/api-reference/documents.md)
- [Error handling guide](https://www.redact-pdf.ai/docs/guides/error-handling.md)