Developer docs

Jobs API

Jobs API reference: POST /v1/jobs to upload PDFs and start redaction, GET a job to poll its status, DELETE it when done. Parameters, responses and examples.

Jobs API

Jobs are the core async unit in the Redact PDF AI API.

Each job can include one or many PDF documents.

POST /v1/jobs

Create a redaction job by uploading files as multipart/form-data.

Headers

  • X-API-Key (required)
  • X-Idempotency-Key (optional, recommended)

Form fields

  • files (required): one or more PDF, JPEG or PNG files. Scans and phone photos are fine; the output is a redacted PDF either way.

  • pii_categories (optional): JSON array string, for example ["Person","Email","PhoneNumber"]. See PII categories.

  • pii_included_terms (optional): JSON array string of terms to always redact, even when not detected as PII. See Redaction rules.

  • pii_excluded_terms (optional): JSON array string of terms to never redact, even when detected as PII. See Redaction rules.

  • retention (optional): ephemeral or studio (default ephemeral)

  • mode (optional): redact (default) draws black boxes; pseudonymize replaces each person, organization, address, email, phone number, date, IBAN and card number with a consistent tag such as [Person 1]. See the Pseudonymize guide.

  • detect_only (optional): true for a dry run. See Detect only below.

Omitted pii_* fields fall back to the API key owner's dashboard defaults.

cURL example

curl -sS -X POST "https://www.redact-pdf.ai/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Idempotency-Key: customer-123-invoice-456" \
  -F 'files=@/absolute/path/document.pdf;type=application/pdf' \
  -F 'pii_categories=["Person","Email","PhoneNumber","Address"]' \
  -F 'pii_included_terms=["Project Titan"]' \
  -F 'pii_excluded_terms=["Acme Corp"]' \
  -F 'retention=ephemeral'

Response example

{
  "job_id": "b3f2b2e0-6f30-4f3e-8a7b-2f2a20a7d91c",
  "status": "analyzing",
  "retention": "ephemeral",
  "created_at": "2026-02-14T12:05:44Z",
  "documents": [
    {
      "id": "7f4f4f85-6b7a-4f88-9a8a-7b9a6a2d2fd0",
      "file_name": "document.pdf",
      "status": "uploaded",
      "page_count": 3,
      "error_message": null
    }
  ]
}

Large files: direct-to-blob upload

For large PDFs, avoid streaming bytes through the API. Use the two-step flow so the file goes straight to storage:

  1. POST /v1/jobs/init with file metadata (JSON) — returns a job_id and one short-lived upload_url per file. Accepts the same redaction config (pii_categories, pii_included_terms, pii_excluded_terms, retention, mode) and X-Idempotency-Key. PDFs only (images use multipart POST /v1/jobs).
  2. PUT each file directly to its upload_url (x-ms-blob-type: BlockBlob).
  3. POST /v1/jobs/{job_id}/commit — verifies the blobs landed and releases the job. Idempotent; safe to retry.
# 1. reserve
curl -sS -X POST "https://www.redact-pdf.ai/v1/jobs/init" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"files":[{"filename":"big.pdf","content_type":"application/pdf","size_bytes":12345678}],"retention":"ephemeral"}'

# 2. upload straight to the returned upload_url
curl -sS -X PUT "<upload_url>" \
  -H "x-ms-blob-type: BlockBlob" -H "Content-Type: application/pdf" \
  --data-binary @big.pdf

# 3. commit
curl -sS -X POST "https://www.redact-pdf.ai/v1/jobs/JOB_ID/commit" \
  -H "X-API-Key: YOUR_API_KEY"

GET /v1/jobs/{job_id}

Get current status for a job and all documents.

cURL example

curl -sS -X GET "https://www.redact-pdf.ai/v1/jobs/JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Job lifecycle

Documents move through:

  • uploaded
  • analyzing
  • redacting
  • redacted (terminal success)
  • detected (terminal for a detect-only job: entities ready, no PDF yet)
  • error (terminal failure)

A job is considered complete when all documents are terminal.

Detect only (dry run)

Send detect_only=true (form field on POST /v1/jobs, JSON field on POST /v1/jobs/init and POST /v1/uploads/{upload_id}/jobs) to ask "what would be redacted?" before producing a file. The job runs the same detection with the same settings, stores the result, and renders no PDF: its documents end detected and the job reports "detect_only": true.

  1. Read what was found with GET /v1/documents/{doc_id}/entities: categories, pages, boxes and counts.
  2. If it is right, call POST /v1/jobs/{job_id}/redact to produce the PDFs with the same settings. They are frozen onto the job at detection, so a change to your dashboard defaults in between does not apply.
  3. If it is not, send overrides to the same call (pii_categories, pii_included_terms, pii_excluded_terms, mode), or delete the job.
curl -sS -X POST "https://www.redact-pdf.ai/v1/jobs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F 'files=@/absolute/path/document.pdf;type=application/pdf' \
  -F 'detect_only=true'

# once GET /v1/jobs/JOB_ID says "detected":
curl -sS "https://www.redact-pdf.ai/v1/documents/DOC_ID/entities" -H "X-API-Key: YOUR_API_KEY"

curl -sS -X POST "https://www.redact-pdf.ai/v1/jobs/JOB_ID/redact" -H "X-API-Key: YOUR_API_KEY"

Billing. A detection counts the document's pages exactly like a redaction (same quota, same free first document, same free re-upload of a file already billed). The redaction that follows is free: a document is charged once, whether it is detected, redacted, or both.

Retention. With retention=ephemeral (the default) the original waits one hour after the detection for POST /v1/jobs/{job_id}/redact, then it is deleted with its OCR text and the detected names, whatever your account's retention setting. With studio, it follows your account's retention window. The hour runs from the job's last activity and the whole job expires at once (never part of it). Once the originals are gone the job is expired: POST /v1/jobs/{job_id}/redact answers 410 and GET /v1/documents/{doc_id}/entities answers 404.

The redaction analyses the document again with the frozen settings (the OCR is cached), so it removes what the detection reported unless you pass overrides. Masks edited in the Studio in between are replaced.

POST /v1/jobs/{job_id}/redact

  • Optional JSON body: pii_categories, pii_included_terms, pii_excluded_terms, mode. With overrides the documents are analysed again (quickly: the OCR is cached).
  • 200: the job, now analyzing. Poll it until redacted, then download as usual. A repeat without overrides returns the job as it is, so retries are safe.
  • 409: detection still running, nothing was detected, or overrides sent for a job already released
  • 410: the originals were deleted; upload the file again
  • 402: quota exceeded

DELETE /v1/jobs/{job_id}

Delete a job and purge associated data (subject to retention policy).

cURL example

curl -sS -X DELETE "https://www.redact-pdf.ai/v1/jobs/JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Response example

{
  "success": true
}

Errors

Common status codes:

  • 400: invalid request
  • 401: unauthorized
  • 402: quota exceeded
  • 404: job not found
  • 429: rate limited

See Error handling for retry strategy.