Direct API calls use Authorization: Bearer $NUTRIENT_API_KEY.
export NUTRIENT_API_KEY="nutr_sk_..."
MCP setups commonly use @nutrient-sdk/dws-mcp-server with NUTRIENT_DWS_API_KEY.
Scripts live in scripts/ relative to this SKILL.md. Use the directory containing this SKILL.md as the working directory:
cd <directory containing this SKILL.md> && uv run scripts/<script>.py --help
Page ranges use start:end with 0-based indexes and end-exclusive semantics. Negative indexes count from the end.
When to use
Generate PDFs from HTML templates, uploaded assets, or remote URLs.
Convert Office, HTML, image, and PDF files between supported formats.
OCR scans and extract text, tables, or key-value pairs.
Redact PII, watermark, sign, fill forms, merge, split, rotate, flatten, or encrypt PDFs.
Produce delivery targets like PDF/A, PDF/UA, optimized PDFs, or linearized PDFs.
Check credits before large, batch, or AI-heavy runs.
Tool preference
Prefer scripts/*.py for covered single-operation workflows.
Use assets/templates/custom-workflow-template.py for multi-step jobs that should still run through the Python client.
Use the modular references/ docs and direct API payloads for capabilities that do not yet have a dedicated helper script, especially HTML/URL generation and compliance tuning.
Use local PDF utilities only for lightweight inspection. Use Nutrient when output fidelity or compliance matters.
Single-operation scripts
convert.py -> convert between pdf, pdfa, pdfua, docx, xlsx, pptx, png, jpeg, webp, html, and markdown
Multi-Step Workflow Rule
Do not add new committed pipeline scripts under scripts/.
When the user asks for multiple operations in one run:
Copy assets/templates/custom-workflow-template.py to a temporary location such as /tmp/ndp-workflow-<task>.py.
Implement the combined workflow in that temporary script.
Run it with uv run /tmp/ndp-workflow-<task>.py ....
Return generated output files.
Delete the temporary script unless the user explicitly asks to keep it.
PDF Requirements
split.py requires a multi-page PDF and cannot extract ranges from a single-page document.
delete-pages.py must retain at least one page and cannot delete the entire document.
sign.py only accepts local file paths for the main PDF.
Decision rules
Prefer a helper script when one already covers the requested operation cleanly.
If you control the source markup, prefer HTML generation over browser print workflows.
Use remote file.url inputs when the source already lives at a stable URL and you want to avoid local uploads.
Use output.type for conversion and finalization targets. Use actions for transformations when building direct API payloads.
OCR before text extraction, key-value extraction, or semantic redaction on scans.
Prefer preset or regex redaction when the target is explicit. Use AI redaction only for contextual or natural-language requests.
Use the PDF manipulation reference for merge, split, rotate, flatten, and page-range workflows instead of inferring those payloads from conversion examples.
Treat PDF/A and PDF/UA as compliance targets, not cosmetic export formats. Choose the target up front and validate final artifacts when requirements are contractual.
For PDF/UA, clean born-digital inputs and structured HTML usually tag better than rasterized or flattened source PDFs.
For delivery optimization, linearize or optimize unsigned output artifacts instead of mutating already signed files.
When the user asks for multiple steps, keep destructive or final steps late in the sequence. Use the workflow recipes when ordering is ambiguous.
Anti-patterns
Do not OCR born-digital PDFs just because the task mentions extraction. Extract first and OCR only if the text layer is missing.
Do not flatten forms or annotations until the user confirms the artifact no longer needs to stay editable.
Do not sign, archive, or linearize intermediate working files. Keep those as final-delivery steps.
Do not promise PDF/A or PDF/UA compliance without a validation step when the requirement is contractual.
Do not commit temporary workflow scripts under scripts/.
Reference map
Read only what you need:
references/request-basics.md -> endpoint model, auth, multipart vs JSON, credits, limits, and errors
references/generation-and-conversion.md -> HTML/URL generation and format conversion
references/pdf-manipulation.md -> merge, split, page-range, rotate, and flatten workflows
references/extraction-and-ocr.md -> OCR, text extraction, tables, and key-value workflows
references/security-signing-and-forms.md -> redaction, watermarking, signatures, forms, and passwords
references/compliance-and-optimization.md -> PDF/A, PDF/UA, optimization, and linearization
references/workflow-recipes.md -> end-to-end sequencing patterns for common business document workflows
Rules
Fail fast when required arguments are missing.
Write outputs to explicit paths and print created files.
Do not log secrets.
All client methods are async and should run via asyncio.run(main()).
If import fails, install dependency with uv add nutrient-dws.
Security Hardening Addendum
Prefer a pinned, preinstalled MCP server binary over runtime package fetches.
Preferred: npm i -g @nutrient-sdk/dws-mcp-server@<pinned-version>
Avoid unpinned runtime fetch in production paths.
Never store NUTRIENT_DWS_API_KEY in committed JSON config files.
Use process env injection at runtime (shell/export, secrets manager, or host env).
Restrict file access with SANDBOX_PATH to the minimum required working directory.
Before enabling MCP mode in production, verify package provenance and lock version.
