Files

In addition to plain text, Sapling also supports PDF and DOCX processing with its PDF-to-text and DOCX-to-text endpoints.

Note that these endpoints do not use just plain JSON as with other Sapling endpoints since the files must be submitted as binary data.

tip

If you only need the text in order to run another endpoint on it, you can upload the document to that endpoint directly:

• /api/v1/file-aidetect scores a document for AI-generated text.
• /api/v1/file-extract pulls typed fields out of one.
• /api/v1/file-summarize summarizes one.

All three accept PDF, DOCX, PPTX, ODT, TXT, Markdown and HTML files up to 30MB.

The JavaScript SDK (@saplingai/sapling-js/client) provides fileAidetect(), fileExtract(), and fileSummarize() upload helpers. See the AI Detector, Extraction, and Summarization references. Version 1.0.55 and later also provide pdfToText() and docxToText() for the endpoints below. These endpoints also accept multipart form requests directly, as shown in the Python and JavaScript examples.

PDF to Text POST

https://api.sapling.ai/api/v1/ingest/pdf_to_text

HTTP method: POST

Request Parameters

Please refer to the code examples below. You must submit the file in a file field as well as a jsonParams field that has the API key.

Python

import json
import requests

def process_pdf(file_path, json_params):
    url = 'https://api.sapling.ai/api/v1/ingest/pdf_to_text'
    files = {
        'file': open(file_path, 'rb'),
        'jsonParams': ('jsonParams', json.dumps(json_params), 'application/json')
    }

    response = requests.post(url, files=files)

    if response.status_code == 200:
        print(response.json())
    else:
        print(f'Failed, status code: {response.status_code}')
        print(response.text)

if __name__ == '__main__':
    pdf_file_path = 'path_to_your_pdf_file.pdf'
    json_data = {
        'key': '<api-key>',  # Do not expose private key in production
    }
    process_pdf(pdf_file_path, json_data)

JavaScript

// Assumes there is a <input type="file" id="pdfFile" accept=".pdf">
let fileInput = document.getElementById('pdfFile');
let file = fileInput.files[0];
if (!file) {
  // Error
}

let formData = new FormData();
formData.append('file', file);
const jsonParams = JSON.stringify({
  key: '<api-key>',  // Do not expose private key in production
});
formData.append('jsonParams', new Blob([jsonParams], { type: 'application/json' }));

const response = await fetch('https://api.sapling.ai/api/v1/ingest/pdf_to_text', {
    method: 'POST',
    credentials: 'include',
    body: formData
})
console.log(response.json());

JavaScript SDK

// npm install @saplingai/sapling-js  (1.0.55 or later)

import { readFile } from 'node:fs/promises';
import { Client } from '@saplingai/sapling-js/client';

const client = new Client('<api-key>');
const { data } = await client.pdfToText(await readFile('report.pdf'), { filename: 'report.pdf' });
console.log(data.text);

Response Parameters

{
  "text": "[EXTRACTED TEXT]"
}

DOCX to Text POST

https://api.sapling.ai/api/v1/ingest/docx_to_text

HTTP method: POST

Request Parameters

Please refer to the code examples below. You must submit the file in a file field as well as a jsonParams field that has the API key.

Python

import json
import requests

def process_docx(file_path, json_params):
    url = 'https://api.sapling.ai/api/v1/ingest/docx_to_text'
    files = {
        'file': open(file_path, 'rb'),
        'jsonParams': ('jsonParams', json.dumps(json_params), 'application/json')
    }

    response = requests.post(url, files=files)

    if response.status_code == 200:
        print(response.json())
    else:
        print(f'Failed, status code: {response.status_code}')
        print(response.text)

if __name__ == '__main__':
    docx_file_path = 'path_to_your_docx_file.docx'
    json_data = {
        'key': '<api-key>',  # Do not expose private key in production
    }
    process_docx(docx_file_path, json_data)

JavaScript

// Assumes there is a <input type="file" id="docxFile" accept=".docx">
let fileInput = document.getElementById('docxFile');
let file = fileInput.files[0];
if (!file) {
  // Error
}

let formData = new FormData();
formData.append('file', file);
const jsonParams = JSON.stringify({
  key: '<api-key>',  // Do not expose private key in production
});
formData.append('jsonParams', new Blob([jsonParams], { type: 'application/json' }));

const response = await fetch('https://api.sapling.ai/api/v1/ingest/docx_to_text', {
    method: 'POST',
    credentials: 'include',
    body: formData
})
console.log(response.json());

JavaScript SDK

// npm install @saplingai/sapling-js  (1.0.55 or later)

import { readFile } from 'node:fs/promises';
import { Client } from '@saplingai/sapling-js/client';

const client = new Client('<api-key>');
const { data } = await client.docxToText(await readFile('notes.docx'), { filename: 'notes.docx' });
console.log(data.text);

Response Parameters

{
  "text": "[EXTRACTED TEXT]"
}

Text extraction behavior

The PDF-to-text endpoint extracts embedded text; it does not perform OCR on scans or image-only PDFs. PDFs with no extractable text and files that require a password return HTTP 400; permission-restricted PDFs that can be read without a password can be processed. Some layout line breaks and split words are normalized. If an individual PDF page cannot be parsed, it may be skipped while the rest of the document is returned.

The DOCX-to-text endpoint extracts paragraphs and tables in document order, including text inside hyperlinks. Table cells are separated by tabs, and nested tables are flattened. Merged cells are not repeated.

File extensions are matched case-insensitively (for example .PDF and .DOCX). Invalid or unreadable documents return HTTP 400.