REST API · v1

Developer API
Reference

Everything you need to integrate text redaction, document redaction, file conversion, and OCR into your pipeline. All endpoints are REST-based, JSON-native, and authenticated via API key.

Base URL

https://backend.shroudly.app

Version:v1

Format:REST · JSON

Auth:Bearer Token

◈Text3 EP

Plain Text Redaction

⌖Document2 EP

Document Redaction

▣Convert2 EP

File Conversion

⟁OCR2 EP

OCR Readable PDFs

Authentication & Credits

Access & Billing

⬡

Authentication

Every request requires your API key passed as the x-api-key header. Keys are scoped to your account and can be rotated from the dashboard at any time.

x-api-key:••••••••••••••••••••••••••••••

01Sign up or log in at shroudly.app

02Navigate to Tool Portal → API Keys

03Generate a new key and copy it immediately. It won't be shown again

04Pass it as x-api-key header in every request to backend.shroudly.app

◈

Credits & Billing

The Shroudly API runs on a credit system. Each job consumes credits based on the module and input size. Credits reset monthly on your billing cycle. Free accounts receive 10 credits per month to get started.

OperationUnitCredits

Text RedactionPer request1

Document RedactionPer file1

File ConversionPer file1

OCR ProcessingPer file1

Free

10 / mo

Starter

500 / mo

Pro

2,000 / mo

Enterprise

Custom

HTTP Status Codes

200Success

400Bad Request

401Invalid API Key

402Insufficient Credits

413File Too Large

422Unsupported Format

429Rate Limited

500Server Error

◈

Redaction

Redaction2 ENDPOINTS

Redact sensitive entities from plain text or uploaded documents (PDF, DOCX). Choose specific entity types or let the engine auto-detect across 50+ PII, PHI, and financial categories.

Submit plain text for redaction. Pass entity types to target specific PII categories, or omit to run full auto-detection. Returns a job ID — poll /jobs/:id for the result.

Request Parameters

ParameterTypeRequiredDescription

Param: x-api-key

Type: string (header)

Required: Yes

Desc: Your Shroudly API key.

Param: text

Type: string (multipart)

Required: No

Desc: Plain text to redact. Provide either text or file, not both.

Param: file

Type: file (multipart)

Required: No

Desc: PDF or DOCX document to redact.

Param: redactionTypes

Type: string[] (multipart)

Required: No

Desc: Entity type codes to target. e.g. ["NAME","SSN","EMAIL_ADDRESS"]. Omit for auto-detection.

Param: compliance_pack

Type: enum (multipart)

Required: No

Param: output_mode

Type: enum (multipart)

Required: No

Desc: Optional worker output mode. One of: "redact" | "mask" | "blackout".

Param: redact_links

Type: boolean (multipart)

Required: No

Desc: Optional flag controlling URL/link redaction. Defaults to false.

curl -X POST https://backend.shroudly.app/redaction/process \
  -H "x-api-key: YOUR_API_KEY" \
  -F "text=John Smith, SSN 123-45-6789, email john@example.com" \
  -F "redactionTypes=NAME" \
  -F "redactionTypes=SSN" \
  -F "redactionTypes=EMAIL_ADDRESS"

200 Response

{
  "jobId":    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "module":   "redaction",
  "status":   "queued",
  "queuedAt": "2026-05-04T12:00:00.000Z"
}

Upload a PDF or DOCX for document-level redaction. The engine preserves layout and returns a pixel-perfect redacted clone accessible via a time-limited Azure SAS URL in the job result.

Request Parameters

ParameterTypeRequiredDescription

Param: x-api-key

Type: string (header)

Required: Yes

Desc: Your Shroudly API key.

Param: file

Type: file (multipart)

Required: Yes

Desc: PDF or DOCX document to redact.

Param: redactionTypes

Type: string[] (multipart)

Required: No

Desc: Entity types to target. Omit for full auto-detection.

Param: compliance_pack

Type: enum (multipart)

Required: No

Param: output_mode

Type: enum (multipart)

Required: No

Desc: Optional worker output mode. One of: "redact" | "mask" | "blackout".

Param: redact_links

Type: boolean (multipart)

Required: No

Desc: Optional flag controlling URL/link redaction. Defaults to false.

Param: redact_faces

Type: boolean (multipart)

Required: No

Desc: Optional worker flag controlling face redaction. Defaults to false.

Param: redact_retinas

Type: boolean (multipart)

Required: No

Desc: Optional worker flag controlling retina/eye redaction. Defaults to false.

Param: redact_bodies

Type: boolean (multipart)

Required: No

Desc: Optional worker flag controlling body redaction. Defaults to false.

Param: redact_full_bodies

Type: boolean (multipart)

Required: No

Desc: Optional worker flag controlling full-body redaction. Defaults to false.

curl -X POST https://backend.shroudly.app/redaction/process \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/contract.pdf" \
  -F "redactionTypes=NAME" \
  -F "redactionTypes=EMAIL_ADDRESS" \
  -F "redact_faces=true" \
  -F "redact_retinas=true" \
  -F "redact_bodies=true" \
  -F "redact_full_bodies=true"

200 Response

{
  "jobId":    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "module":   "redaction",
  "status":   "queued",
  "queuedAt": "2026-05-04T12:00:00.000Z"
}

⟁

OCR

OCR1 ENDPOINT

Transform scanned or image-heavy PDFs into fully searchable, machine-readable documents. Supports 12 languages, configurable output formats (text, JSON, Markdown, combined), table and formula recognition.

Upload a PDF for OCR processing. Configure language, output format, page limits, and extraction options. Returns a job ID — poll /jobs/:id for the completed output download URL.

Request Parameters

ParameterTypeRequiredDescription

Param: x-api-key

Type: string (header)

Required: Yes

Desc: Your Shroudly API key.

Param: file

Type: file (multipart)

Required: Yes

Desc: PDF to process. Maximum 20 MB.

Param: mimeType

Type: string (multipart)

Required: No

Desc: Optional MIME type override. Example: "application/pdf".

Param: languageHints

Type: string[] (multipart)

Required: No

Desc: Optional language hints array. Example: ["eng", "urd"]. Max 10 items.

Param: language

Type: string (multipart)

Required: No

Desc: ISO 639-1 language code. e.g. "en", "fr", "de". Defaults to "en".

Param: outputFormat

Type: enum (multipart)

Required: No

Desc: One of: "text" | "json" | "markdown" | "combined". Defaults to "markdown".

Param: maxPages

Type: number (multipart)

Required: No

Desc: Max pages to process. Omit to process all.

Param: extractText

Type: boolean (multipart)

Required: No

Desc: Extract plain text layer. Defaults to true.

Param: extractTables

Type: boolean (multipart)

Required: No

Desc: Extract table structures.

Param: extractImages

Type: boolean (multipart)

Required: No

Desc: Extract embedded images.

Param: extractFormulas

Type: boolean (multipart)

Required: No

Desc: Extract mathematical formulas.

Param: detectTables

Type: boolean (multipart)

Required: No

Desc: Enable table detection.

Param: enableTableRecognition

Type: boolean (multipart)

Required: No

Desc: Enable advanced table structure recognition.

Param: enableFormulaRecognition

Type: boolean (multipart)

Required: No

Desc: Enable formula recognition model.

Param: forceOcr

Type: boolean (multipart)

Required: No

Desc: Force OCR even when text may already be embedded. Defaults to false.

curl -X POST https://backend.shroudly.app/ocr/process \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/scanned.pdf" \
  -F "language=en" \
  -F "outputFormat=text" \
  -F "extractText=true"

200 Response

{
  "jobId":    "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "module":   "ocr",
  "status":   "queued",
  "queuedAt": "2026-05-04T12:00:00.000Z"
}

▣

File Conversion

Convert1 ENDPOINT

Convert between PDF, Word, Excel, PowerPoint, HTML, JPG, and PDF/A. Supported routes: PDF→Word, PDF→Excel, PDF→PowerPoint, PDF→JPG, PDF→PDF/A, PDF→Text, Word→PDF, Excel→PDF, PowerPoint→PDF, JPG→PDF, HTML→PDF.

Upload a file with outputFormat and an optional inputFormat override. Returns a job ID immediately — poll /jobs/:id for completion and the download URL of the converted file.

Request Parameters

ParameterTypeRequiredDescription

Param: x-api-key

Type: string (header)

Required: Yes

Desc: Your Shroudly API key.

Param: file

Type: file (multipart)

Required: Yes

Desc: The source file. Maximum 20 MB.

Param: inputFormat

Type: string (multipart)

Required: No

Param: outputFormat

Type: string (multipart)

Required: Yes

# PDF → Word
curl -X POST https://backend.shroudly.app/conversion/process \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "inputFormat=pdf" \
  -F "outputFormat=word"
# Word → PDF
curl -X POST https://backend.shroudly.app/conversion/process \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/report.docx" \
  -F "inputFormat=docx" \
  -F "outputFormat=pdf"

200 Response

{
  "jobId":    "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "module":   "conversion",
  "status":   "queued",
  "queuedAt": "2026-05-04T12:00:00.000Z"
}

◎

Jobs

Jobs2 ENDPOINTS

Retrieve and monitor processing jobs. All three modules queue jobs asynchronously and return a jobId immediately. Poll these endpoints for status, output download URLs, and credit usage.

Returns a paginated list of all jobs for the authenticated account, ordered by creation date descending.

Request Parameters

ParameterTypeRequiredDescription

Param: x-api-key

Type: string (header)

Required: Yes

Desc: Your Shroudly API key.

Param: page

Type: number (query)

Required: No

Desc: Page number. Defaults to 1.

Param: limit

Type: number (query)

Required: No

Desc: Items per page. Defaults to 20. Max 100.

curl -X GET "https://backend.shroudly.app/jobs?page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

200 Response

{
  "items": [
    {
      "jobId":           "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "module":          "redaction",
      "status":          "completed",
      "creditsRequired": 2,
      "creditsReserved": true,
      "failureCode":     null,
      "queuedAt":        "2026-05-04T12:00:00.000Z",
      "completedAt":     "2026-05-04T12:00:03.412Z"
    }
  ],
  "total": 36,
  "page":  1,
  "limit": 20
}

Returns full details for a single job including status, output download URL (when completed), credit usage, failure code, and timestamps. Poll until status is "completed" or "failed".

Request Parameters

ParameterTypeRequiredDescription

Param: x-api-key

Type: string (header)

Required: Yes

Desc: Your Shroudly API key.

Param: id

Type: string (path)

Required: Yes

Desc: The jobId returned when the job was created.

curl -X GET https://backend.shroudly.app/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: YOUR_API_KEY"

200 Response

{
  "jobId":           "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "module":          "redaction",
  "status":          "completed",
  "creditsRequired": 2,
  "creditsReserved": true,
  "failureCode":     null,
  "outputUrl":       "https://shroudlystorage.blob.core.windows.net/outputs/redacted.pdf?sv=...&sig=...",
  "queuedAt":        "2026-05-04T12:00:00.000Z",
  "completedAt":     "2026-05-04T12:00:03.412Z"
}

Developer APIReference

Access & Billing

Authentication

Credits & Billing

Redaction

OCR

File Conversion

Jobs

Developer API
Reference