Create Document

Convert markdown to Word documents (DOCX) with support for track changes, insertions, deletions, and comments. This is useful for generating legal documents, contracts with redlines, and collaborative review documents.

Quick Start

from datalab_sdk import DatalabClient

client = DatalabClient()

markdown = (
    "# Contract\n\n"
    "This agreement is between "
    '<ins data-revision-author="Editor" data-revision-datetime="2024-01-15T10:00:00Z">'
    "Acme Corp</ins> and the client."
)

result = client.create_document(markdown=markdown)
result.save_output("contract")  # saves contract.docx
print(f"Document created: {result.page_count} page(s)")

# Submit request
curl -X POST https://www.datalab.to/api/v1/create-document \
  -H "X-API-Key: $DATALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Contract\n\nThis agreement is between <ins data-revision-author=\"Editor\" data-revision-datetime=\"2024-01-15T10:00:00Z\">Acme Corp</ins> and the client.",
    "output_format": "docx"
  }'

# Poll for results (use request_check_url from response)
curl https://www.datalab.to/api/v1/create-document/REQUEST_ID \
  -H "X-API-Key: $DATALAB_API_KEY"

import requests, json, time, base64, os

headers = {"X-API-Key": os.getenv("DATALAB_API_KEY")}

# Submit request
response = requests.post(
    "https://www.datalab.to/api/v1/create-document",
    json={
        "markdown": "# Contract\n\nThis agreement is between "
                    '<ins data-revision-author="Editor" '
                    'data-revision-datetime="2024-01-15T10:00:00Z">'
                    "Acme Corp</ins> and the client.",
        "output_format": "docx"
    },
    headers=headers
)

check_url = response.json()["request_check_url"]

# Poll for results
while True:
    result = requests.get(check_url, headers=headers).json()
    if result["status"] == "complete":
        docx_bytes = base64.b64decode(result["output_base64"])
        with open("contract.docx", "wb") as f:
            f.write(docx_bytes)
        print("Document saved as contract.docx")
        break
    elif result.get("error"):
        print(f"Error: {result['error']}")
        break
    time.sleep(2)

SDK Usage

Use client.create_document() to create a DOCX from markdown:

from datalab_sdk import DatalabClient

client = DatalabClient()

result = client.create_document(
    markdown="# Title\n\nDocument content here.",
    output_format="docx",       # Only 'docx' is supported
    webhook_url=None,           # Optional completion webhook
    save_output="output/doc",   # Optional: saves output.docx automatically
)

print(result.success)         # True if creation succeeded
print(result.page_count)      # Number of pages
print(result.cost_breakdown)  # Cost details
result.save_output("output/contract")  # Saves contract.docx

SDK Method Parameters

Parameter	Type	Default	Description
`markdown`	str	Required	Markdown content with optional track changes markup
`output_format`	str	`"docx"`	Output format (only `"docx"` is supported)
`webhook_url`	str	None	Optional webhook URL for completion notification
`save_output`	str/Path	None	File path to save the output DOCX
`max_polls`	int	`300`	Maximum polling attempts
`poll_interval`	int	`1`	Seconds between polls

SDK Result Fields

Field	Type	Description
`success`	bool	Whether document creation succeeded
`status`	str	`"complete"` when done
`output_format`	str	`"docx"`
`output_base64`	str	Base64-encoded DOCX file
`runtime`	float	Processing time in seconds
`page_count`	int	Pages in the generated document
`cost_breakdown`	dict	Cost details
`error`	str	Error message if creation failed

How It Works

Send markdown content with optional track changes markup
The API converts it to a DOCX file with proper Word formatting
Track changes tags become native Word revision marks
The DOCX file is returned as a base64-encoded string

Track Changes Markup

Insertions

Mark inserted text with <ins> tags:

<ins data-revision-author="John Doe" data-revision-datetime="2024-01-15T10:00:00Z">newly added text</ins>

Attribute	Required	Description
`data-revision-author`	Yes	Author name for the insertion
`data-revision-datetime`	Yes	ISO 8601 timestamp (e.g., `2024-01-15T10:00:00Z`)

Deletions

Mark deleted text with <del> tags:

<del data-revision-author="Jane Smith" data-revision-datetime="2024-01-15T11:00:00Z">removed text</del>

Attribute	Required	Description
`data-revision-author`	Yes	Author name for the deletion
`data-revision-datetime`	Yes	ISO 8601 timestamp

Comments

Add comments with <comment> tags:

<comment data-comment-author="Reviewer" data-comment-datetime="2024-01-15T12:00:00Z" text="Please verify this clause">annotated text</comment>

Attribute	Required	Description
`data-comment-author`	Yes	Author/reviewer name
`text`	Yes	The comment text
`data-comment-datetime`	No	ISO 8601 timestamp (defaults to current time)
`data-comment-initial`	No	Author initials (auto-generated from name if omitted)

Parameters

Parameter	Type	Required	Description
`markdown`	string	Yes	Markdown content with optional track changes markup
`output_format`	string	No	Output format (currently only `docx` is supported)
`webhook_url`	string	No	Webhook URL to notify when processing completes

Response

The response follows the standard async pattern — submit, then poll: Initial response:

{
  "success": true,
  "request_id": "abc123",
  "request_check_url": "https://www.datalab.to/api/v1/create-document/abc123"
}

Final response (when polling):

Field	Type	Description
`status`	string	`processing` or `complete`
`success`	bool	Whether document creation succeeded
`output_format`	string	`docx`
`output_base64`	string	Base64-encoded DOCX file
`runtime`	float	Processing time in seconds
`page_count`	int	Pages in the generated document
`cost_breakdown`	object	Cost details
`error`	string	Error message if creation failed

Full Example

A contract with insertions, deletions, and reviewer comments:

import requests, json, time, base64, os

headers = {"X-API-Key": os.getenv("DATALAB_API_KEY")}

markdown = """# Service Agreement

## Parties

This agreement is between <ins data-revision-author="Legal" data-revision-datetime="2024-06-01T09:00:00Z">Acme Corporation ("Provider")</ins> and <del data-revision-author="Legal" data-revision-datetime="2024-06-01T09:00:00Z">the Client</del><ins data-revision-author="Legal" data-revision-datetime="2024-06-01T09:00:00Z">GlobalTech Inc. ("Client")</ins>.

## Terms

The service period begins on <comment data-comment-author="Reviewer" text="Confirm start date with finance">January 1, 2025</comment> and continues for <del data-revision-author="Legal" data-revision-datetime="2024-06-01T10:00:00Z">12</del><ins data-revision-author="Legal" data-revision-datetime="2024-06-01T10:00:00Z">24</ins> months.

## Payment

The total contract value is <ins data-revision-author="Finance" data-revision-datetime="2024-06-02T14:00:00Z">$150,000</ins> payable in quarterly installments.
"""

response = requests.post(
    "https://www.datalab.to/api/v1/create-document",
    json={"markdown": markdown, "output_format": "docx"},
    headers=headers
)

check_url = response.json()["request_check_url"]

while True:
    result = requests.get(check_url, headers=headers).json()
    if result["status"] == "complete":
        docx_bytes = base64.b64decode(result["output_base64"])
        with open("service_agreement.docx", "wb") as f:
            f.write(docx_bytes)
        print(f"Document saved ({result['page_count']} pages)")
        break
    time.sleep(2)

The generated DOCX file opens in Microsoft Word with native track changes visible, allowing reviewers to accept or reject each change.

Use Cases

Legal document generation — create contracts with tracked revisions
Contract redlining — mark up agreements with insertions and deletions
Collaborative review — add reviewer comments to documents
Document automation — generate Word documents from templates with dynamic content

Next Steps

Track Changes Extraction

Extract track changes from existing Word documents

Document Conversion

Convert documents to markdown, HTML, or JSON

Webhooks

Get notified when document creation completes

Pipelines

Chain processors into versioned, reusable pipelines.

General

Document Conversion

Structured Extraction

Document Segmentation

Form Filling

File Management

Pipelines

Track Changes

Table Recognition (Deprecated)

Forge Evals

Create Document

Quick Start

SDK Usage

SDK Method Parameters

SDK Result Fields

How It Works

Track Changes Markup

Insertions

Deletions

Comments

Parameters

Response

Full Example

Use Cases

Next Steps

Track Changes Extraction

Document Conversion

Webhooks

Pipelines

​Quick Start

​SDK Usage

​SDK Method Parameters

​SDK Result Fields

​How It Works

​Track Changes Markup

​Insertions

​Deletions

​Comments

​Parameters

​Response

​Full Example

​Use Cases

​Next Steps

Track Changes Extraction

Document Conversion

Webhooks

Pipelines

Quick Start

SDK Usage

SDK Method Parameters

SDK Result Fields

How It Works

Track Changes Markup

Insertions

Deletions

Comments

Parameters

Response

Full Example

Use Cases

Next Steps