Document Builder

The Document Builder provides an interactive way to create documents through a step-by-step API-driven process. Instead of defining the entire document structure upfront, you can build documents incrementally by adding sections one by one.

Primary Use Case

The Document Builder is ideal for creating comprehensive, large-scale documents through automated processes such as:

• AI Agents: Intelligent systems that generate content dynamically and build documents section by section
• No-Code Automations: Workflow tools like Zapier, Make.com, or n8n that create documents based on triggers and data sources
• Progressive Document Assembly: Applications that collect information over time and build documents incrementally
• Dynamic Report Generation: Systems that compile data from multiple sources into structured reports

This approach is particularly powerful when you don't know the complete document structure upfront or when content is generated dynamically based on external data, user interactions, or AI-driven processes.

Key Features

• Session-Based Building: Create a builder session and add sections incrementally
• Section-Level Management: Add complete flow or page sections with their content
• Flexible Structure: Modify and rearrange sections during the building process
• Simple Build Process: Generate documents with a single endpoint call using your session ID
• Automatic Storage: JSON configuration is automatically stored in job history

How It Works

The Document Builder uses a session-based approach where you create a builder session, add complete sections (not individual elements), and then trigger document generation with the dedicated build endpoint.

1. Create Builder Session

Start by creating a new builder session with basic document configuration:

curl -X POST /api/v1/document-builder \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "config": {
      "document": {
        "type": "pdf",
        "filename": "my-document",
        "title": "My Generated Document",
        "author": "Document Builder API",
        "subject": "Automated Document Generation",
        "keywords": ["api", "automation", "pdf"],
        "size": "A4",
        "orientation": "portrait",
        "marginTop": 2.54,
        "marginRight": 2.54,
        "marginBottom": 2.54,
        "marginLeft": 2.54
      },
      "variables": {
        "companyName": "Your Company",
        "projectName": "Your Project",
        "version": "1.0",
        "year": "2024"
      },
      "defaults": {
        "fontFamily": "Arial",
        "fontSize": 11,
        "color": "#000000",
        "lineHeight": 1.5,
        "header": {
          "left": "**{{companyName}}**",
          "center": "{{projectName}}",
          "right": "Version {{version}}",
          "excludeFirstPage": true
        },
        "footer": {
          "left": "*{{year}}*",
          "center": "Page {{pageNumber}} of {{totalPages}}",
          "right": "[Documentation](https://example.com)",
          "excludeFirstPage": true
        }
      }
    }
  }'

2. Add Sections

Add complete sections to your document. Each section must be either flow or page type and contains multiple content elements:

curl -X POST /api/v1/document-builder/{sessionId}/sections \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "section": {
      "type": "flow",
      "content": [
        {
          "type": "h1",
          "text": "Introduction"
        },
        {
          "type": "text",
          "text": "This is the introduction section with **markdown** support."
        },
        {
          "type": "list",
          "ordered": false,
          "items": ["Feature 1", "Feature 2", "Feature 3"]
        }
      ]
    }
  }'

3. Generate Document

When ready, trigger document generation using the build endpoint:

curl -X POST /api/v1/document-builder/{sessionId}/build \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

The build endpoint automatically uses your session configuration to create a document generation job. No additional parameters are needed - the session ID in the URL is sufficient.

Section Types

The Document Builder works at the section level, where each section is a complete unit containing multiple content elements:

Flow Sections

Page Break Control

By default, each flow section starts on a new page (newPage: true). If you want a flow section to continue on the same page as the previous section, set newPage: false in your section configuration.

Flow sections contain content that flows naturally from one page to the next:

{
  "section": {
    "type": "flow",
    "content": [
      {
        "type": "h2",
        "text": "Chapter Title"
      },
      {
        "type": "text",
        "text": "Content that can span multiple pages..."
      },
      {
        "type": "table",
        "headers": ["Name", "Value"],
        "rows": [["Item 1", "100"], ["Item 2", "200"]]
      }
    ]
  }
}

Page Sections

Page sections are positioned on specific pages with alignment control:

{
  "section": {
    "type": "page",
    "align": "center",
    "content": [
      {
        "type": "h1",
        "text": "Title Page",
        "align": "center"
      },
      {
        "type": "text",
        "text": "Subtitle",
        "align": "center"
      }
    ]
  }
}

Job History and JSON Storage

When you trigger document generation using the /build endpoint, it creates a document generation job and the complete JSON configuration is automatically stored in the job history. You don't need to manually save the JSON - it's retrievable through the job details endpoint:

# Get job details including the complete JSON configuration
curl -X GET /api/v1/jobs/{jobId} \
  -H "x-api-key: YOUR_API_KEY"

The response includes the complete config object that was used to generate the document, making it easy to:

• Review the exact configuration used
• Reuse configurations for similar documents
• Debug generation issues
• Maintain document version history

Session Management

Update Sections

Replace entire sections with new content:

curl -X PUT /api/v1/document-builder/{sessionId}/sections/{sectionIndex} \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "section": {
      "type": "flow",
      "content": [
        {
          "type": "h2",
          "text": "Updated Section Title"
        }
      ]
    }
  }'

Delete Sections

Remove sections by index:

curl -X DELETE /api/v1/document-builder/{sessionId}/sections/{sectionIndex} \
  -H "x-api-key: YOUR_API_KEY"

Get Session Configuration

Retrieve the current session configuration:

curl -X GET /api/v1/document-builder/{sessionId} \
  -H "x-api-key: YOUR_API_KEY"

Best Practices

Section Organization

• Plan your document structure before starting
• Use valid section types (flow for content, page for title pages)
• Group related content elements within the same section
• Consider page breaks when organizing sections

Content Structure

• Start with document configuration (type, size, orientation)
• Add sections in logical order
• Use consistent styling within sections or default styles
• Test with sample content before finalizing

API Usage

• Create sessions with minimal configuration first
• Add sections incrementally to build complexity
• Use the session management endpoints to modify content
• Use the /build endpoint to generate your document when ready

JSON Structure Reference

The Document Builder uses the same JSON syntax as regular document generation jobs. For detailed information about available elements and styling options, see:

• Overview - Document structure, sections, defaults, and variables
• Elements - All available content elements with examples and styling options

Next Steps

• Overview - JSON structure and document basics
• Elements - Detailed element documentation with styling options
• Examples - Finished documents for inspiration
• API Reference - Complete API documentation

Need help with the Document Builder? Contact us at support@json2doc.com!