Getting Started

Get up and running with PDFDancer in just 3 minutes. This guide covers installation and a simple working example.

Installation

Choose your preferred method:

Option 1: AI-Assisted Development – Let your AI coding assistant handle everything (recommended for fastest setup)

• See AI-Assisted Development to install the MCP server, then just ask: "Create a PDF with PDFDancer"

Option 2: Manual Install – Traditional package manager installation

Requirements: Python 3.10+, Node.js 20+ or Java 11+.

No API token needed to get started—the SDK uses anonymous access automatically.

Python

Install from PyPI:

pip install pdfdancer-client-python

TypeScript

Install from npm:

npm install pdfdancer-client-typescript

Or with pnpm:

pnpm add pdfdancer-client-typescript

Or with Yarn:

yarn add pdfdancer-client-typescript

Java

Add to your Maven pom.xml:

<dependency>
  <groupId>com.pdfdancer.client</groupId>
  <artifactId>pdfdancer-client-java</artifactId>
  <version>0.1.1</version>
</dependency>

Or add to your Gradle build.gradle.kts:

dependencies {
    implementation("com.pdfdancer.client:pdfdancer-client-java:0.1.1")
}

Your First PDF Edit

Here's a simple example that opens a PDF, finds and replaces text, adds a new paragraph, and saves it:

Python

from pathlib import Path
from pdfdancer import Color, PDFDancer

# No token needed! SDK automatically gets an anonymous token
with PDFDancer.open(pdf_data=Path("input.pdf")) as pdf:
    # Locate existing content
    heading = pdf.page(1).select_paragraphs_starting_with("Executive Summary")[0]
    heading.edit().replace("Overview").apply()

    # Add a new paragraph using the fluent builder
    pdf.new_paragraph() \
        .text("Generated with PDFDancer") \
        .font("Helvetica", 12) \
        .color(Color(70, 70, 70)) \
        .line_spacing(1.4) \
        .at(page_number=1, x=72, y=520) \
        .add()

    # Persist the modified document
    pdf.save("output.pdf")

TypeScript

import {PDFDancer, Color} from 'pdfdancer-client-typescript';

async function run() {
    // No token needed! SDK automatically gets an anonymous token
    const pdf = await PDFDancer.open('input.pdf');

    const page0 = pdf.page(1);

    // Locate and edit existing content
    const headings = await page0.selectParagraphsStartingWith('Executive Summary');
    if (headings[0]) {
        await headings[0].edit()
            .replace('Overview')
            .apply();
    }

    // Add a new paragraph
    await page0.newParagraph()
        .text('Generated with PDFDancer')
        .font('Helvetica', 12)
        .color(new Color(70, 70, 70))
        .lineSpacing(1.4)
        .at(72, 520)
        .apply();

    await pdf.save('output.pdf');
}

run().catch(console.error);

Java

import com.pdfdancer.client.rest.PDFDancer;
import com.pdfdancer.client.rest.TextParagraphReference;
import com.pdfdancer.common.model.Color;
import com.pdfdancer.common.util.StandardFonts;

import java.io.File;

public class Example {
    public static void main(String[] args) throws Exception {
        // No token needed! SDK automatically gets an anonymous token
        PDFDancer pdf = PDFDancer.createSession(new File("input.pdf"));

        // Locate and edit existing content
        TextParagraphReference heading = pdf.page(1)
                .selectParagraphsStartingWith("Executive Summary")
                .get(0);

        heading.edit()
                .replace("Overview")
                .apply();

        // Add a new paragraph using the fluent builder
        pdf.newParagraph()
                .text("Generated with PDFDancer")
                .font(StandardFonts.HELVETICA.getFontName(), 12)
                .color(new Color(70, 70, 70))
                .lineSpacing(1.4)
                .at(1, 72, 520)
                .add();

        // Persist the modified document
        pdf.save("output.pdf");
    }
}

What's Next?

• AI-Assisted Development – Let your AI assistant build PDF applications for you
• Authentication – Learn how to securely manage API tokens for production
• Concepts & Core Features – Understand PDFDancer's approach to PDF editing
• Working with Text – Select, add, edit, move, and delete paragraphs
• Cookbook – Common patterns and recipes