diff --git a/skills/nutrient-document-processing/LICENSE b/skills/nutrient-document-processing/LICENSE new file mode 100644 index 00000000..d76bb040 --- /dev/null +++ b/skills/nutrient-document-processing/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by the Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding any notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2025 Nutrient GmbH + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/skills/nutrient-document-processing/SKILL.md b/skills/nutrient-document-processing/SKILL.md new file mode 100644 index 00000000..59b849db --- /dev/null +++ b/skills/nutrient-document-processing/SKILL.md @@ -0,0 +1,293 @@ +--- +name: nutrient-document-processing +description: >- + Process documents with the Nutrient DWS API. Use this skill when the user wants to convert documents + (PDF, DOCX, XLSX, PPTX, HTML, images), extract text or tables from PDFs, OCR scanned documents, + redact sensitive information (PII, SSN, emails, credit cards), add watermarks, digitally sign PDFs, + fill PDF forms, or check API credit usage. Activates on keywords: PDF, document, convert, extract, + OCR, redact, watermark, sign, merge, compress, form fill, document processing. +license: Apache-2.0 +compatibility: >- + Requires Node.js 18+ and an internet connection. Works with Claude Code, Codex CLI, Gemini CLI, + OpenCode, Cursor, Windsurf, GitHub Copilot, Amp, or any Agent Skills-compatible product. + Alternatively, use curl for direct API access without Node.js. +metadata: + author: nutrient-sdk + version: "1.0" + homepage: "https://www.nutrient.io/api/" + repository: "https://github.com/PSPDFKit-labs/nutrient-agent-skill" +--- + +# Nutrient Document Processing + +Process, convert, extract, redact, sign, and manipulate documents using the [Nutrient DWS Processor API](https://www.nutrient.io/api/). + +## Setup + +You need a Nutrient DWS API key. Get one free at . + +### Option 1: MCP Server (Recommended) + +If your agent supports MCP (Model Context Protocol), use the Nutrient DWS MCP Server. It provides all operations as native tools. + +**Configure your MCP client** (e.g., `claude_desktop_config.json` or `.mcp.json`): + +```json +{ + "mcpServers": { + "nutrient-dws": { + "command": "npx", + "args": ["-y", "@nutrient-sdk/dws-mcp-server"], + "env": { + "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY", + "SANDBOX_PATH": "/path/to/working/directory" + } + } + } +} +``` + +Then use the MCP tools directly (e.g., `convert_to_pdf`, `extract_text`, `redact`, etc.). + +### Option 2: Direct API (curl) + +For agents without MCP support, call the API directly: + +```bash +export NUTRIENT_API_KEY="your_api_key_here" +``` + +All requests go to `https://api.nutrient.io/build` as multipart POST with an `instructions` JSON field. + +## Operations + +### 1. Convert Documents + +Convert between PDF, DOCX, XLSX, PPTX, HTML, and image formats. + +**HTML to PDF:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "index.html=@index.html" \ + -F 'instructions={"parts":[{"html":"index.html"}]}' \ + -o output.pdf +``` + +**DOCX to PDF:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.docx=@document.docx" \ + -F 'instructions={"parts":[{"file":"document.docx"}]}' \ + -o output.pdf +``` + +**PDF to DOCX/XLSX/PPTX:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"docx"}}' \ + -o output.docx +``` + +**Image to PDF:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "image.jpg=@image.jpg" \ + -F 'instructions={"parts":[{"file":"image.jpg"}]}' \ + -o output.pdf +``` + +### 2. Extract Text and Data + +**Extract plain text:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"text"}}' \ + -o output.txt +``` + +**Extract tables (as JSON, CSV, or Excel):** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"xlsx"}}' \ + -o tables.xlsx +``` + +**Extract key-value pairs:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"extraction","strategy":"key-values"}]}' \ + -o result.json +``` + +### 3. OCR Scanned Documents + +Apply OCR to scanned PDFs or images, producing searchable PDFs with selectable text. + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "scanned.pdf=@scanned.pdf" \ + -F 'instructions={"parts":[{"file":"scanned.pdf"}],"actions":[{"type":"ocr","language":"english"}]}' \ + -o searchable.pdf +``` + +Supported languages: `english`, `german`, `french`, `spanish`, `italian`, `portuguese`, `dutch`, `swedish`, `danish`, `norwegian`, `finnish`, `polish`, `czech`, `turkish`, `japanese`, `korean`, `chinese-simplified`, `chinese-traditional`, `arabic`, `hebrew`, `thai`, `hindi`, `russian`, and more. + +### 4. Redact Sensitive Information + +**Pattern-based redaction** (preset patterns): +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"preset","preset":"social-security-number"}]}' \ + -o redacted.pdf +``` + +Available presets: `social-security-number`, `credit-card-number`, `email-address`, `north-american-phone-number`, `international-phone-number`, `date`, `url`, `ipv4`, `ipv6`, `mac-address`, `us-zip-code`, `vin`, `time`. + +**Regex-based redaction:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"regex","regex":"\\b[A-Z]{2}\\d{6}\\b"}]}' \ + -o redacted.pdf +``` + +**AI-powered PII redaction:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"ai_redaction","criteria":"All personally identifiable information"}]}' \ + -o redacted.pdf +``` + +The `criteria` field accepts natural language (e.g., "Names and phone numbers", "Protected health information", "Financial account numbers"). + +### 5. Add Watermarks + +**Text watermark:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","text":"CONFIDENTIAL","fontSize":48,"fontColor":"#FF0000","opacity":0.5,"rotation":45,"width":"50%","height":"50%"}]}' \ + -o watermarked.pdf +``` + +**Image watermark:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F "logo.png=@logo.png" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","imagePath":"logo.png","width":"30%","height":"30%","opacity":0.3}]}' \ + -o watermarked.pdf +``` + +### 6. Digital Signatures + +**Sign a PDF with CMS signature:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cms","signerName":"John Doe","reason":"Approval","location":"New York"}]}' \ + -o signed.pdf +``` + +**Sign with CAdES-B-LT (long-term validation):** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cades","cadesLevel":"b-lt","signerName":"Jane Smith"}]}' \ + -o signed.pdf +``` + +### 7. Form Filling (Instant JSON) + +Fill PDF form fields using Instant JSON format: +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "form.pdf=@form.pdf" \ + -F 'instructions={"parts":[{"file":"form.pdf"}],"actions":[{"type":"fillForm","fields":[{"name":"firstName","value":"John"},{"name":"lastName","value":"Doe"},{"name":"email","value":"john@example.com"}]}]}' \ + -o filled.pdf +``` + +### 8. Merge and Split PDFs + +**Merge multiple PDFs:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "doc1.pdf=@doc1.pdf" \ + -F "doc2.pdf=@doc2.pdf" \ + -F 'instructions={"parts":[{"file":"doc1.pdf"},{"file":"doc2.pdf"}]}' \ + -o merged.pdf +``` + +**Extract specific pages:** +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf","pages":{"start":0,"end":4}}]}' \ + -o pages1-5.pdf +``` + +### 9. Render PDF Pages as Images + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf","pages":{"start":0,"end":0}}],"output":{"type":"png","dpi":300}}' \ + -o page1.png +``` + +### 10. Check Credits + +```bash +curl -X GET https://api.nutrient.io/credits \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" +``` + +## Best Practices + +1. **Use the MCP server** when your agent supports it — it handles file I/O, error handling, and sandboxing automatically. +2. **Set `SANDBOX_PATH`** to restrict file access to a specific directory. +3. **Check credit balance** before batch operations to avoid interruptions. +4. **Use AI redaction** for complex PII detection; use preset/regex redaction for known patterns (faster, cheaper). +5. **Chain operations** — the API supports multiple actions in a single call (e.g., OCR then redact). + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| 401 Unauthorized | Check your API key is valid and has credits | +| 413 Payload Too Large | Files must be under 100 MB | +| Slow AI redaction | AI analysis takes 60–120 seconds; this is normal | +| OCR quality poor | Try a different language parameter or improve scan quality | +| Missing text in extraction | Run OCR first on scanned documents | + +## More Information + +- [Full API reference](references/REFERENCE.md) — Detailed endpoints, parameters, and error codes +- [API Playground](https://dashboard.nutrient.io/processor-api/playground/) — Interactive API testing +- [API Documentation](https://www.nutrient.io/guides/dws-processor/) — Official guides +- [MCP Server repo](https://github.com/PSPDFKit/nutrient-dws-mcp-server) — Source code and issues diff --git a/skills/nutrient-document-processing/references/REFERENCE.md b/skills/nutrient-document-processing/references/REFERENCE.md new file mode 100644 index 00000000..0ac9b2b0 --- /dev/null +++ b/skills/nutrient-document-processing/references/REFERENCE.md @@ -0,0 +1,598 @@ +# Nutrient DWS Processor API Reference + +Complete API reference for the Nutrient Document Web Services (DWS) Processor API. + +## Base URL + +``` +https://api.nutrient.io +``` + +## Authentication + +All requests require a Bearer token in the `Authorization` header: + +``` +Authorization: Bearer YOUR_API_KEY +``` + +Get your API key at . + +## Main Endpoint + +### POST /build + +The primary endpoint for all document processing operations. Accepts multipart form data with file uploads and a JSON `instructions` field. + +**Request format:** +``` +POST https://api.nutrient.io/build +Content-Type: multipart/form-data +Authorization: Bearer YOUR_API_KEY + +Form fields: + - One or more file uploads (name must match what's referenced in instructions) + - instructions: JSON object defining the processing pipeline +``` + +**Instructions JSON structure:** +```json +{ + "parts": [ + { + "file": "filename.pdf", + "pages": { "start": 0, "end": -1 }, + "password": "optional-password" + } + ], + "actions": [ + { "type": "action_type", ...action_params } + ], + "output": { + "type": "pdf", + "owner_password": "optional", + "user_password": "optional" + } +} +``` + +## Document Conversion + +### Office to PDF + +Convert DOCX, XLSX, PPTX to PDF. + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.docx=@document.docx" \ + -F 'instructions={"parts":[{"file":"document.docx"}]}' \ + -o output.pdf +``` + +Supported input formats: `.docx`, `.xlsx`, `.pptx`, `.doc`, `.xls`, `.ppt`, `.odt`, `.ods`, `.odp`, `.rtf`. + +### HTML to PDF + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "index.html=@index.html" \ + -F 'instructions={"parts":[{"html":"index.html"}]}' \ + -o output.pdf +``` + +**With layout options:** +```json +{ + "parts": [{ "html": "index.html" }], + "output": { + "type": "pdf", + "layout": { + "orientation": "landscape", + "size": "A4", + "margin": { "top": 20, "bottom": 20, "left": 15, "right": 15 } + } + } +} +``` + +Supported sizes: `A0`–`A8`, `Letter`, `Legal`, or custom `{ "width": N, "height": N }` in points. + +### Image to PDF + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "photo.jpg=@photo.jpg" \ + -F 'instructions={"parts":[{"file":"photo.jpg"}]}' \ + -o output.pdf +``` + +Supported image formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.tiff`, `.bmp`. + +### PDF to Office + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"docx"}}' \ + -o output.docx +``` + +Supported output types: `docx`, `xlsx`, `pptx`. + +### PDF to Image + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf","pages":{"start":0,"end":0}}],"output":{"type":"png","dpi":150}}' \ + -o page.png +``` + +**Output parameters:** +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `type` | string | `pdf` | `png`, `jpeg`, `webp` | +| `dpi` | number | 150 | Resolution (72–600) | +| `width` | number | — | Output width in pixels | +| `height` | number | — | Output height in pixels | + +## Text and Data Extraction + +### Extract Text + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"output":{"type":"text"}}' \ + -o extracted.txt +``` + +### Extract Tables + +Export tables to Excel, XML, JSON, or CSV: + +```bash +# To Excel +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"extraction","strategy":"tables"}],"output":{"type":"xlsx"}}' \ + -o tables.xlsx +``` + +### Extract Key-Value Pairs + +Detect structured data like names, dates, addresses, phone numbers: + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"extraction","strategy":"key-values"}],"output":{"type":"json"}}' \ + -o pairs.json +``` + +## OCR (Optical Character Recognition) + +### Basic OCR + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "scanned.pdf=@scanned.pdf" \ + -F 'instructions={"parts":[{"file":"scanned.pdf"}],"actions":[{"type":"ocr","language":"english"}]}' \ + -o searchable.pdf +``` + +### Multi-Language OCR + +```json +{ + "parts": [{ "file": "scanned.pdf" }], + "actions": [{ "type": "ocr", "language": ["english", "german", "french"] }] +} +``` + +### Supported OCR Languages + +| Language | Code | Language | Code | +|----------|------|----------|------| +| English | `english` | Japanese | `japanese` | +| German | `german` | Korean | `korean` | +| French | `french` | Chinese (Simplified) | `chinese-simplified` | +| Spanish | `spanish` | Chinese (Traditional) | `chinese-traditional` | +| Italian | `italian` | Arabic | `arabic` | +| Portuguese | `portuguese` | Hebrew | `hebrew` | +| Dutch | `dutch` | Thai | `thai` | +| Swedish | `swedish` | Hindi | `hindi` | +| Danish | `danish` | Russian | `russian` | +| Norwegian | `norwegian` | Polish | `polish` | +| Finnish | `finnish` | Czech | `czech` | +| Turkish | `turkish` | | | + +### OCR on Images + +Also works on standalone images (JPEG, PNG, TIFF): + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "scan.jpg=@scan.jpg" \ + -F 'instructions={"parts":[{"file":"scan.jpg"}],"actions":[{"type":"ocr","language":"english"}]}' \ + -o searchable.pdf +``` + +## Redaction + +### Preset Pattern Redaction + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"preset","preset":"email-address"}]}' \ + -o redacted.pdf +``` + +**Available presets:** + +| Preset | Matches | +|--------|---------| +| `social-security-number` | US SSNs (XXX-XX-XXXX) | +| `credit-card-number` | Visa, MasterCard, Amex, etc. | +| `email-address` | Email addresses | +| `north-american-phone-number` | US/Canada phone numbers | +| `international-phone-number` | International format numbers | +| `date` | Common date formats | +| `url` | Web URLs | +| `ipv4` | IPv4 addresses | +| `ipv6` | IPv6 addresses | +| `mac-address` | MAC addresses | +| `us-zip-code` | US ZIP codes | +| `vin` | Vehicle identification numbers | +| `time` | Time values | + +### Regex Redaction + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"regex","regex":"\\b\\d{3}-\\d{2}-\\d{4}\\b","caseSensitive":false}]}' \ + -o redacted.pdf +``` + +### Text-Match Redaction + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"redaction","strategy":"text","text":"CLASSIFIED","caseSensitive":false}]}' \ + -o redacted.pdf +``` + +### AI-Powered Redaction + +Uses AI to detect and redact PII based on natural-language criteria. Takes 60–120 seconds. + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"ai_redaction","criteria":"All personally identifiable information"}]}' \ + -o redacted.pdf +``` + +**Example criteria:** +- `"All personally identifiable information"` +- `"Names, email addresses, and phone numbers"` +- `"Protected health information (PHI)"` +- `"Social security numbers and credit card numbers"` +- `"Financial account numbers and routing numbers"` + +**Redaction action parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `strategy` | string | `preset`, `regex`, `text`, or (for AI) use `type: ai_redaction` | +| `preset` | string | Preset pattern name (when strategy=preset) | +| `regex` | string | Regular expression (when strategy=regex) | +| `text` | string | Exact text to match (when strategy=text) | +| `caseSensitive` | boolean | Default: true for regex, false for text | +| `startPage` | integer | Start page index (0-based) | +| `pageLimit` | integer | Number of pages to process | +| `includeAnnotations` | boolean | Also redact matching annotations (default: true) | +| `criteria` | string | Natural language criteria (for ai_redaction) | + +## Watermarking + +### Text Watermark + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","watermarkType":"text","text":"DRAFT","fontSize":72,"fontColor":"#FF0000","opacity":0.3,"rotation":45,"width":"50%","height":"50%"}]}' \ + -o watermarked.pdf +``` + +### Image Watermark + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F "logo.png=@logo.png" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"watermark","watermarkType":"image","imagePath":"logo.png","width":"25%","height":"25%","opacity":0.5}]}' \ + -o watermarked.pdf +``` + +**Watermark parameters:** + +| Parameter | Type | Description | +|-----------|------|-------------| +| `watermarkType` | string | `text` or `image` | +| `text` | string | Watermark text (when type=text) | +| `imagePath` | string | Image filename (when type=image) | +| `fontSize` | number | Font size in points | +| `fontColor` | string | Hex color (e.g., `#FF0000`) | +| `opacity` | number | 0–1 (default: 0.7) | +| `rotation` | number | Degrees counter-clockwise | +| `width` | string/number | Width in points or percentage (e.g., `"50%"`) | +| `height` | string/number | Height in points or percentage | + +## Digital Signatures + +### CMS Signature + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cms","signerName":"John Doe","reason":"Document approval","location":"San Francisco"}]}' \ + -o signed.pdf +``` + +### CAdES Signature + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf"}],"actions":[{"type":"sign","signatureType":"cades","cadesLevel":"b-lt","signerName":"Jane Smith"}]}' \ + -o signed.pdf +``` + +### Visible Signature + +Add a visual signature appearance on a specific page: + +```json +{ + "parts": [{ "file": "document.pdf" }], + "actions": [{ + "type": "sign", + "signatureType": "cms", + "signerName": "John Doe", + "pageIndex": 0, + "rect": [50, 700, 200, 50] + }] +} +``` + +**Signature parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `signatureType` | string | `cms` | `cms` or `cades` | +| `cadesLevel` | string | `b-lt` | `b-b`, `b-t`, or `b-lt` (CAdES only) | +| `signerName` | string | — | Signer's name | +| `reason` | string | — | Reason for signing | +| `location` | string | — | Signing location | +| `pageIndex` | integer | — | Page for visible signature (0-based). Omit for invisible. | +| `rect` | array | — | `[left, top, width, height]` in PDF points | +| `flatten` | boolean | false | Flatten document before signing | +| `graphicImagePath` | string | — | Path to signature graphic | +| `watermarkImagePath` | string | — | Path to watermark image overlay | + +## PDF Manipulation + +### Merge PDFs + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "doc1.pdf=@doc1.pdf" \ + -F "doc2.pdf=@doc2.pdf" \ + -F "doc3.pdf=@doc3.pdf" \ + -F 'instructions={"parts":[{"file":"doc1.pdf"},{"file":"doc2.pdf"},{"file":"doc3.pdf"}]}' \ + -o merged.pdf +``` + +### Extract Page Ranges + +```bash +curl -X POST https://api.nutrient.io/build \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" \ + -F "document.pdf=@document.pdf" \ + -F 'instructions={"parts":[{"file":"document.pdf","pages":{"start":0,"end":4}}]}' \ + -o first-5-pages.pdf +``` + +Pages use 0-based indexing. `"end": -1` means the last page. + +### Flatten PDF + +Remove interactive elements (form fields, annotations): + +```json +{ + "parts": [{ "file": "document.pdf" }], + "actions": [{ "type": "flatten" }] +} +``` + +### Rotate Pages + +```json +{ + "parts": [{ "file": "document.pdf" }], + "actions": [{ "type": "rotate", "rotation": 90, "pages": [0, 1, 2] }] +} +``` + +## Form Filling + +### Fill Form Fields + +```json +{ + "parts": [{ "file": "form.pdf" }], + "actions": [{ + "type": "fillForm", + "fields": [ + { "name": "firstName", "value": "John" }, + { "name": "lastName", "value": "Doe" }, + { "name": "email", "value": "john@example.com" }, + { "name": "agree", "value": true } + ] + }] +} +``` + +## Password Protection + +### Encrypt a PDF + +```json +{ + "parts": [{ "file": "document.pdf" }], + "output": { + "type": "pdf", + "owner_password": "owner123", + "user_password": "user456" + } +} +``` + +### Open a Password-Protected PDF + +```json +{ + "parts": [{ "file": "protected.pdf", "password": "user456" }] +} +``` + +## Credit Management + +### Check Balance + +```bash +curl -X GET https://api.nutrient.io/credits \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" +``` + +**Response:** +```json +{ + "remaining": 9500, + "total": 10000, + "usage": { + "period": "week", + "used": 500 + } +} +``` + +### Check Usage by Operation + +```bash +curl -X GET "https://api.nutrient.io/credits/usage?period=month" \ + -H "Authorization: Bearer $NUTRIENT_API_KEY" +``` + +## Chaining Actions + +Multiple actions can be chained in a single API call: + +```json +{ + "parts": [{ "file": "scanned.pdf" }], + "actions": [ + { "type": "ocr", "language": "english" }, + { "type": "redaction", "strategy": "preset", "preset": "social-security-number" }, + { "type": "redaction", "strategy": "preset", "preset": "email-address" }, + { "type": "watermark", "watermarkType": "text", "text": "REDACTED", "fontSize": 36, "opacity": 0.2, "rotation": 45, "width": "50%", "height": "50%" }, + { "type": "sign", "signatureType": "cms", "signerName": "Compliance Dept" } + ] +} +``` + +Actions execute in order. This example: OCR → redact SSNs → redact emails → add watermark → sign. + +## Error Handling + +### HTTP Status Codes + +| Code | Meaning | +|------|---------| +| 200 | Success — response body is the output file | +| 400 | Bad request — invalid instructions or missing required fields | +| 401 | Unauthorized — invalid or missing API key | +| 402 | Payment required — insufficient credits | +| 413 | Payload too large — file exceeds 100 MB limit | +| 415 | Unsupported media type — unsupported input format | +| 422 | Unprocessable entity — valid format but cannot process | +| 429 | Rate limited — too many requests | +| 500 | Server error — retry with exponential backoff | + +### Error Response Format + +```json +{ + "error": { + "code": "invalid_instructions", + "message": "The 'parts' field is required", + "details": {} + } +} +``` + +### Common Errors and Solutions + +| Error | Cause | Solution | +|-------|-------|----------| +| `file_not_found` | Referenced file not in upload | Ensure filename in instructions matches upload field name | +| `unsupported_format` | Input format not recognized | Check supported formats list | +| `password_required` | PDF is encrypted | Add `"password"` to the part | +| `insufficient_credits` | Account out of credits | Top up at dashboard.nutrient.io | +| `ocr_language_invalid` | Unsupported OCR language | Check supported languages table | + +## Rate Limits + +- Free tier: 100 requests/minute +- Paid tiers: Higher limits based on plan +- Use `429` status code to detect rate limiting +- Implement exponential backoff for retries + +## File Size Limits + +- Maximum input file: 100 MB +- Maximum total upload: 500 MB per request +- Recommended: Keep files under 50 MB for fastest processing + +## Additional Resources + +- [API Playground](https://dashboard.nutrient.io/processor-api/playground/) — Interactive testing +- [API Documentation](https://www.nutrient.io/guides/dws-processor/) — Official guides +- [MCP Server](https://github.com/PSPDFKit/nutrient-dws-mcp-server) — For AI agent integration +- [npm Package](https://www.npmjs.com/package/@nutrient-sdk/dws-mcp-server) — MCP server on npm +- [Dashboard](https://dashboard.nutrient.io/) — Manage API keys and credits +- [Sign Up](https://dashboard.nutrient.io/sign_up/?product=processor) — Get a free API key