REST API reference.

Four endpoints, one owner-scoped workflow. All requests require Authorization: Bearer YOUR_KEY.

POST/v1/files

Multipart field file. Returns 201 with file_id, bytes, and extension. Supply a bounded upload with Content-Length.

Copyable example

curl -X POST "$REDACTTOOL_BASE_URL/v1/files" \
  -H "Authorization: Bearer $REDACTTOOL_API_KEY" \
  -F "file=@sample.docx"

POST/v1/redactions

JSON file_id and mode: exactly blackout or placeholder. Send an 8–100 character Idempotency-Key; use letters, digits, underscores or hyphens.

Copyable example

curl -X POST "$REDACTTOOL_BASE_URL/v1/redactions" \
  -H "Authorization: Bearer $REDACTTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-request-001" \
  -d '{"file_id":"YOUR_FILE_ID","mode":"placeholder"}'

GET/v1/redactions/{id}

Poll until completed or failed. The stage and done/total fields provide progress; do not assume every stage has a fixed number of seconds.

Copyable example

{
  "id": "example-job",
  "status": "completed",
  "stage": "completed",
  "done": 1,
  "total": 1,
  "error": null,
  "mode": "placeholder",
  "redactions": 3,
  "download_url": "/v1/redactions/example-job/file"
}

Illustrative response. Stage names and counters depend on the processing path.

GET/v1/redactions/{id}/file

Download with the same Bearer key. A returned path does not make the file publicly accessible.

Errors you should handle

Status	Meaning / action
401	Missing or expired authentication. Obtain valid credentials.
404	Missing, expired, or another owner's object. Do not infer ownership.
409	Idempotency conflict or result not ready. Check the error detail.
413 / 415 / 422	Size, format, or input validation. Correct the request.
429	Capacity or trial limit. Back off; do not loop indefinitely.

HTTP errors use {"detail":"error_code"}. A job can return HTTP 200 with status: failed; check its error field.

← Website Quickstart →