@ninjadoc-ai/n8n

N8n integration package for Ninjadoc AI - the first Document Q&A platform that extracts structured data from documents using natural language questions and AI-powered extraction with coordinate proof.

Node

Ninjadoc AI

Action Node - Complete document processing solution with three powerful actions in one unified interface.

Actions

1. Ask Question Ask natural language questions about documents and get answers with coordinate proof.

Inputs:

• Question (natural language): "What is the total invoice amount?"
• Document Source: Binary data from previous node or file upload
• Include Coordinates: Get bounding box coordinates showing where answers were found

Outputs:

• Answer with confidence score and optional coordinate proof
• Page candidates for multi-page documents

2. Process with Template Extract multiple fields from documents using pre-configured processor templates.

Inputs:

• Processor ID: UUID of your processor template from Ninjadoc dashboard
• Document Source: Binary data from previous node or file upload

Outputs:

• Structured data extraction with all defined fields
• Confidence scores and coordinates for each field
• Automatic polling for job completion

3. Convert to Markdown Transform documents into markdown format with AI-powered structure detection.

Inputs:

• Document Source: Binary data from previous node or file upload
• Use AI Parse: Enable intelligent structure detection for tables and lists

Outputs:

• Clean markdown representation of document content
• Processing metadata and timing information

Output Formats

Choose how you want response data formatted:

• Full Response: Complete API response with all metadata and processing details
• Essential Data Only: Extracted values, confidence scores, and coordinates without extra metadata
• Answer Only: Just the extracted text values without additional information
• Structured Data: Flat key-value object optimized for further processing (ideal for batch operations)

Key Features

• Zero Training Required: Works out-of-the-box without model training or setup
• Layout-Aware Processing: Handles document variations without rigid templates
• Coordinate Proof: Get exact bounding box coordinates showing where answers were found
• Developer-First API: Clean integration with structured JSON responses
• Automatic Retry Logic: Built-in retry with exponential backoff for reliability
• Multiple Document Sources: Support for binary data from previous nodes or direct file upload
• Flexible Output Formats: Choose the data format that best fits your workflow

Credentials

Ninjadoc API

Required credentials for the node:

• API Key: Your Ninjadoc API key from the dashboard
• Base URL: API base URL (default: https://api.ninjadoc.ai)

Installation

1. Install the package:

npm install @ninjadoc-ai/n8n

2. Configure credentials in n8n:

   • Add Ninjadoc API credentials
   • Enter your API key and base URL

3. Add the Ninjadoc AI node to your workflows

Usage Examples

Simple Q&A Workflow

1. Read Binary File: Load a PDF document
2. Ninjadoc AI: Ask question action with natural language query
3. Process results: Use extracted data in subsequent nodes

Batch Processing Workflow

1. Read Binary File: Load a PDF document
2. Ninjadoc AI: Process with template action using processor ID
3. Auto-polling: Node automatically waits for completion
4. Extract structured data: Get all fields with confidence scores

Document Conversion Workflow

1. Read Binary File: Load a PDF document
2. Ninjadoc AI: Convert to markdown action with AI parsing
3. Save or process: Use markdown content in documentation workflows

Error Handling

The unified node includes comprehensive error handling:

• Automatic Retry Logic: Exponential backoff with jitter for network issues
• Rate Limit Handling: Intelligent retry on 429 responses
• Timeout Management: Configurable timeouts with graceful failure
• Continue on Fail: Option to continue workflow execution on errors
• Detailed Error Messages: Specific guidance for different error types
• Input Validation: PDF validation and file size checks

Advanced Features

Coordinate Integration

When coordinates are enabled, you get both raw pixel coordinates and percentage-based coordinates for easy UI integration:

{
  "coordinates": [{
    "text": "Total: $1,234.56",
    "page": 1,
    "confidence": 0.95,
    "bbox_raw": [100, 200, 300, 220],
    "bbox_percentage": {
      "x1": 12.5, "y1": 25.0,
      "x2": 37.5, "y2": 27.5
    }
  }]
}

Auto-Polling for Async Operations

For processor template operations, the node automatically handles job polling:

• Starts with 2-second intervals
• Exponential backoff up to 30 seconds
• 5-minute maximum processing time
• Real-time status updates in execution log

Document Source Flexibility

• Binary Data: Seamlessly integrate with file reading nodes
• File Upload: Direct file path support for development and testing
• Validation: Automatic PDF validation and size checking (10MB limit)