Automating Technical PDF Ingestion: Integrating the KolmoPDF API and Agent Skills

This article is part of the **KolmoPDF: Product Guides & Updates* series. For a high-level overview of our parsing engine and layout-preserving translation, read the series overview.*

Converting a research paper or hardware spec sheet by hand through a browser UI works fine for a quick one-off check, but breaks down when you need to ingest dozens of technical preprints a day or feed incoming documents into a retrieval pipeline. Manual uploads produce inconsistent naming, unlogged failures, and delayed vector updates.

A reliable ingestion pipeline needs two capabilities: direct API access for backend microservices and native integration with coding agents such as Claude Code, OpenClaw, or custom MCP environments.

This walkthrough covers how to automate structured PDF-to-Markdown extraction using the KolmoPDF API and our open agent skill.

1. When to Use Programmatic PDF Parsing

Simple single-column PDFs with plain paragraphs work reliably with local open-source utilities like pypdf. An API-based extraction pipeline becomes necessary when documents contain structures that local text scrapers discard:

• Multi-column research papers: Maintaining reading flow without interleaving parallel columns.
• Display and inline formulas: Extracting equations directly into standard LaTeX ($...$ and $$...$$) rather than flattened character fragments.
• Complex tables: Preserving grid alignments and multi-line cell values as clean Markdown tables.
• Embedded translations: Translating technical documents while parsing, outputting Markdown in the target language for immediate indexing.

2. API Setup and Credit Model

KolmoPDF uses a unified credit model across the web interface, the REST API, and agent tools.

The free tier includes 300 credits upon registration and 50 credits via daily check-in, providing 1 API key. Paid tiers (Go, Plus, Pro) and a Pay-As-You-Go option ($3 for 1,000 credits) share the same API endpoints. Pro plans allow creating and managing up to 10 API keys.

Standard PDF-to-Markdown parsing consumes 2 credits per page. Parsing with concurrent translation consumes 3 credits per page.

You can generate your API key directly in your KolmoPDF dashboard and export it to your runtime environment:

export KOLMOPDF_API_KEY="your-api-key-here"

3. Submitting Documents via Python

The REST API accepts PDF uploads and returns structured Markdown once processing completes. Here is an end-to-end Python client script for submitting a technical report and saving the structured Markdown output:

import os
import time
import requests

API_BASE = "https://api.kolmopdf.com/v1"
API_KEY = os.environ.get("KOLMOPDF_API_KEY")

if not API_KEY:
    raise ValueError("KOLMOPDF_API_KEY environment variable is missing.")

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

def parse_pdf_to_markdown(file_path: str, output_path: str, poll_interval: int = 5):
    """
    Uploads a PDF to KolmoPDF, polls for parsing completion,
    and writes the resulting Markdown to disk.
    """
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Source file not found: {file_path}")

    # 1. Upload and create parsing task
    with open(file_path, "rb") as f:
        files = {"file": f}
        data = {"output_format": "markdown", "preserve_math": "true"}

        print(f"Uploading {file_path}...")
        response = requests.post(f"{API_BASE}/parse", headers=headers, files=files, data=data)
        response.raise_for_status()
        task_info = response.json()

    task_id = task_info.get("task_id")
    print(f"Task created: {task_id}. Polling for completion...")

    # 2. Poll task status
    while True:
        status_resp = requests.get(f"{API_BASE}/tasks/{task_id}", headers=headers)
        status_resp.raise_for_status()
        status_data = status_resp.json()

        status = status_data.get("status")
        if status == "completed":
            markdown_content = status_data.get("result", {}).get("markdown", "")
            with open(output_path, "w", encoding="utf-8") as out:
                out.write(markdown_content)
            print(f"Extraction complete! Saved to {output_path}")
            break
        elif status == "failed":
            error_msg = status_data.get("error", "Unknown error")
            raise RuntimeError(f"Parsing failed: {error_msg}")

        time.sleep(poll_interval)

if __name__ == "__main__":
    parse_pdf_to_markdown("sample_paper.pdf", "sample_paper.md")

The returned Markdown contains properly scoped LaTeX blocks for formulas and GitHub-flavored Markdown for tables, ready for standard text chunking or vector embedding.

4. Connecting to AI Coding Agents via Agent Skills

For autonomous coding agents or terminal workflows, installing our pre-packaged agent skill is faster than hand-rolling API requests.

You can install the KolmoPDF skill using npx:

npx skills add komoai2026/kolmopdf-skill

Once installed, supply KOLMOPDF_API_KEY to your agent runtime. The skill exposes commands that allow agents to ingest PDF paths, extract Markdown, and inspect equations without leaving their operational session.

This pattern is especially effective for automated review workflows: an agent downloads a whitepaper from an arXiv link, calls the skill to convert it to Markdown, and performs semantic summarization or code reproduction against clean mathematical definitions.

5. Practical Ingestion Guidelines

When integrating document parsing into production pipelines, keep these operational boundaries in mind:

1. Test representative pages first. Before batch-processing a 500-page archive, test 5 to 10 representative pages containing your domain's dense formulas or multi-column grids.
2. Retain source PDFs. Always store the original PDF alongside the extracted Markdown. Having the original coordinates allows human auditors or vision fallback models to verify ambiguous symbols.
3. Consider data privacy boundaries. KolmoPDF processes documents online over TLS. For sensitive internal legal records or regulated health documents that cannot touch cloud endpoints, evaluate our on-premises Enterprise deployment options.

To get started, create your free account at KolmoPDF, grab an API key from the Developer Guide, and test your first technical paper.