Developer docs

Retention

What is kept and for how long: ephemeral jobs delete the original after redaction, outputs follow your 3, 7 or 14-day window (or stay until deleted when it is off), DELETE /v1/jobs removes files and records at once.

Retention

What Redact PDF AI keeps, for how long, and how to delete it sooner. Two settings decide it: the retention mode of each job, and the retention window of your account.

At a glance

Whatephemeral job (API default)studio jobWhen it is deleted at the latest*
Original fileDeleted as soon as the redaction succeedsKept for review in the StudioEnd of your retention window
Cached text extraction of the originalDeleted with the originalKeptEnd of your retention window
Redacted PDFKeptKeptEnd of your retention window
Text version (output.md, pseudonymize mode)KeptKeptEnd of your retention window
Correspondence entities (tag → original name, pseudonymize mode)Kept, because the table is an output you still have to downloadKeptEnd of your retention window
Detected names of a redact-mode jobNever stored: only mask positions, categories and tags are keptNever stored—
Mask positions and categories (no text), the job's always-redact and never-redact term listsKeptKeptOnly when you delete the job or your account

* With automatic deletion turned off, this column does not apply: files stay until you delete the job or your account. A document stuck in analyzing or redacting (a processing failure we have to fix) is also skipped by the sweep until it leaves that status.

Your retention window is 14 days by default. You can set it to 3, 7 or 14 days, or turn automatic deletion off. DELETE /v1/jobs/{job_id} deletes all of it at once, whatever the window.

Retention modes

Set retention on POST /v1/jobs (or on POST /v1/jobs/init for direct uploads). It applies to every document of the job.

ephemeral (default)

For pure API workflows, where nobody reviews the result in the Studio.

  • When a document is redacted successfully, the worker deletes the original file and its cached text extraction straight away. For a redact-mode job it also deletes the entity records (tags and keys; redact mode never stores the detected names). The file's fingerprint (SHA-256) is removed from the document and from its billing record as well.
  • This early delete is best effort and is not retried: if it fails, the worker logs it and the original goes at the end of your retention window instead. With automatic deletion off, that original stays until you delete the job.
  • The redacted PDF stays available for download until your retention window ends.
  • In pseudonymize mode, the text version and the correspondence table also stay until your window ends, so you can download them and restore names later.
  • A detect-only job (detect_only=true) produces no PDF, so it keeps its original at most one hour after the detection, waiting for POST /v1/jobs/{job_id}/redact. After that hour the original, its cached text and the detected names are deleted, whatever your retention setting, and the job can no longer be redacted (410).
  • If a redaction fails, the original is kept so the job can be retried or inspected. It is then deleted at the end of your retention window like any other file.
  • Without the original, the Studio cannot edit the masks of an ephemeral document. Use studio if a person needs to review.

studio

For hybrid pipelines where a person checks or adjusts redactions in the web Studio (see the Studio handoff guide).

  • The original, the masks, the redacted PDF and, in pseudonymize mode, the entities are all kept so the document can be re-edited and re-rendered.
  • The files, the text and the detected names are deleted at the end of your retention window (see "What deleted covers" below). The job record, its mask positions and categories stay until you 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/contract.pdf;type=application/pdf' \
  -F 'retention=studio'

Your account's retention window

Every document's files are deleted automatically once it has had no activity for the length of your window. The clock is the document's last update: the end of processing, a later view, download, review or edit in the web app, or the first download of the redacted PDF over the API (later API downloads do not restart it). The worker checks every few minutes.

  • Options: 3, 7 or 14 days, or off (no automatic deletion).
  • Default: 14 days.
  • Where to change it: Dashboard → Settings → File retention. The change applies to existing documents as well as new ones. It is an account setting, not an API parameter.
  • The window applies to documents sent through the web app, the API and the AI assistant integrations alike.

With automatic deletion off, files stay until you delete them. Ephemeral jobs still delete their originals right after a successful redaction; an original whose early delete failed then stays until you delete the job.

Delete a job now

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

This removes, for every document of the job: the original, the redacted PDF, its text version, the cached text extraction, any restored texts made through the hosted connector, the masks, the correspondence entities and the document and job records themselves, the job's term lists included. Billing records are kept, without the file's fingerprint and no longer linked to the document.

File deletes are best effort: if the storage service refuses one at that moment, the failure is logged and the records are removed regardless. A redacted PDF, text version or cached extraction left behind this way is removed by an hourly cleanup. An original left behind is not retried; it goes when you delete your account.

The call returns 409 while the job is still processing. Poll GET /v1/jobs/{job_id} until every document is redacted or error, then delete. The hosted connector's delete_job tool calls the same endpoint.

What "deleted" covers

When the retention window ends, the worker deletes:

  • the original file and the redacted PDF,
  • the text version of a pseudonymized output,
  • the cached text extraction of the original,
  • restored texts made through the hosted connector,
  • the correspondence entities (the detected names behind each tag) and the key that links masks to them,
  • the file fingerprint stored on the document.

What remains is the record that a document existed, so billing and usage history stay correct: its status, page count, dates, mask positions and categories (no text), the job's always-redact and never-redact term lists, and the usage log. The file name is replaced. The term lists are whatever you sent in pii_included_terms and pii_excluded_terms; if they contain names, delete the job when you are done.

The usage log is the one place a fingerprint survives automatic deletion: it keeps a one-way fingerprint of the file so the same file is not charged twice when you upload it again. Deleting the job yourself, or an ephemeral job's original being deleted, removes that fingerprint too. Separately, a job created with an idempotency key (the MCP server derives one from the file and the settings) keeps that key, which is a one-way hash, for 24 hours so a retried call returns the same job; deleting the job removes it at once.

Deleted data can remain in our hosting providers' database and storage backups until the backup cycle ends, currently at most 30 days (Data Processing Agreement, section 8.4).

Deleting your account (Dashboard → Settings) removes every remaining document and the data derived from it, your API keys and the access of connected AI assistants.

Short-lived links and uploads

These have their own, shorter lifetimes:

WhatLifetime
Download links created by the API or the hosted connector (/v1/dl/...)15 minutes; ask for a new one, the file stays until your window ends
Upload link for the hosted connector (create_upload_link)30 minutes to use the page; the browser's write URL lasts 15 minutes
A file put on an upload link that never became a jobDeleted after 1 hour
Restored texts made by the hosted connector's restore_namesDeleted after 1 hour
Direct uploads (POST /v1/jobs/init) never committedThe job and its files are deleted after 1 hour

Keyless demo

POST /v1/demo/redact (and the try_demo tool with a file) redacts the first page with no account:

  • The uploaded original is deleted right after processing. The response says whether that delete succeeded (original_deleted). If it failed, the demo sweep removes it 14 days after the upload.
  • The link to the redacted first page is valid for 7 days (link_expires_in_days).
  • The redacted first page is deleted after 14 days.

GET /v1/demo and /v1/demo/sample.pdf use a fixed synthetic sample and store nothing.

Good practice

  • Treat outputs as sensitive data: the redacted PDF is safe to share, but the correspondence table re-identifies it.
  • Download what you need, then call DELETE /v1/jobs/{job_id} rather than waiting for the window.
  • Use ephemeral unless a person needs the Studio.
  • Keep long-term copies in your own storage, under your own retention policy.

Related pages