# REST API

## REST lifecycle
Authorization: Bearer API_KEY on every /v1 request.
POST /v1/files: multipart file, bounded upload. Returns file_id.
POST /v1/redactions: JSON file_id, mode; Idempotency-Key header (8–100 word/hyphen characters; ASCII recommended).
Returns job with id, status, stage, done, total, error, mode, redactions, download_url.
GET /v1/redactions/{id}: poll queued/running to completed/failed.
GET /v1/redactions/{id}/file: authenticated download after completed.
Reuse creation key only with the same file and mode. Persist IDs.
A local timeout does not cancel remote processing. No cancellation endpoint.
No webhook, no public download URL, no remote URL import.

## Authentication, limits and data
Guest keys are session-bound, up to 24h. New guest key revokes the previous guest key. Account API keys last one year and are individually revocable at /account.html.
Current trial: global queue 12; per session 2 active / 20 daily jobs.
No permanent API credentials or deployed billing assumed.
Terminal jobs and associated files are eligible for cleanup after 24h. An independent worker checks every 60 seconds; failures are retried. Active jobs and files referenced by active/newer jobs are retained.
Files are processed only on servers managed by RedactTool, using its proprietary redaction engine and dedicated processing pipeline.
Production confidential uploads need verified HTTPS transport.
Do not put credentials in URLs, client-side bundles or prompts.
No SOC2/HIPAA/zero-retention/zero-miss claim is made. Submitted documents are not used for model training. Inference is self-hosted; document content is not sent to third-party LLM APIs.


Errors: 401 authentication; 404 inaccessible/missing/expired object; 409 idempotency conflict or result not ready; 413/415/422 input validation; 429 capacity or trial limit. HTTP error body uses detail; failed jobs use error.