Edit

Edit a PDF document by inferring form fields and filling them with provided instructions.

Either document OR template_id must be provided, but not both:

With document (standard flow):

1. OCR on the PDF to extract text elements with bounding boxes
2. LLM inference to identify fillable form fields
3. LLM-based form filling using the provided instructions
4. Returns the filled PDF with form field values populated

With template_id (template-based flow, PDF only):

• Fetches the empty PDF template from storage
• Uses the template’s pre-defined form fields (skips OCR and schema inference)
• Fills the form fields directly using LLM
• Returns the filled PDF

Note: The original model name (e.g., “retab-flash”) is preserved in the edit log. Model resolution to specific candidates happens internally during LLM calls.

POST /v1/documents/edit

python

from retab import Retab

client = Retab()

# Option 1: Edit with a document (detects fields automatically)
result = client.documents.edit(
    instructions="Name: John Doe, Date of Birth: 1990-01-15, Address: 123 Main Street, City: New York",
    document="form.pdf",  # Can be a file path, URL, or MIMEData
    model="retab-small"
)

# Option 2: Edit with a template (uses pre-defined fields)
# result = client.documents.edit(
#     instructions="Name: John Doe, Date of Birth: 1990-01-15",
#     template_id="edittplt_abc123",  # Use template instead of document
#     model="retab-small",
# )

# Access the filled PDF (MIMEData with filename and url containing base64 data)
if result.filled_document:
    import base64
    # Extract base64 content from data URI
    base64_content = result.filled_document.url.split(",")[1]
    filled_document_bytes = base64.b64decode(base64_content)
    with open("filled_form.pdf", "wb") as f:
        f.write(filled_document_bytes)

# Access form data with filled values
print(f"Filled {len(result.form_data)} form fields")
for field in result.form_data:
    print(f"Field: {field.key} ({field.description}) = {field.value}")

200

{
  "form_data": [
    {
      "bbox": {
        "left": 0.15,
        "top": 0.20,
        "width": 0.35,
        "height": 0.03,
        "page": 1
      },
      "description": "Full Name - string input field for applicant's legal name",
      "type": "text",
      "key": "full_name",
      "value": "John Doe"
    },
    {
      "bbox": {
        "left": 0.15,
        "top": 0.28,
        "width": 0.20,
        "height": 0.03,
        "page": 1
      },
      "description": "Date of Birth - date field in MM/DD/YYYY format",
      "type": "text",
      "key": "date_of_birth",
      "value": "01/15/1990"
    },
    {
      "bbox": {
        "left": 0.55,
        "top": 0.45,
        "width": 0.02,
        "height": 0.02,
        "page": 1
      },
      "description": "Agreement checkbox - confirms acceptance of terms",
      "type": "checkbox",
      "key": "agreement_checkbox",
      "value": "unchecked"
    }
  ],
  "filled_document": {
    "filename": "filled_form.pdf",
    "url": "data:application/pdf;base64,JVBERi0xLjQK..."
  }
}

python

from retab import Retab

client = Retab()

# Option 1: Edit with a document (detects fields automatically)
result = client.documents.edit(
    instructions="Name: John Doe, Date of Birth: 1990-01-15, Address: 123 Main Street, City: New York",
    document="form.pdf",  # Can be a file path, URL, or MIMEData
    model="retab-small"
)

# Option 2: Edit with a template (uses pre-defined fields)
# result = client.documents.edit(
#     instructions="Name: John Doe, Date of Birth: 1990-01-15",
#     template_id="edittplt_abc123",  # Use template instead of document
#     model="retab-small",
# )

# Access the filled PDF (MIMEData with filename and url containing base64 data)
if result.filled_document:
    import base64
    # Extract base64 content from data URI
    base64_content = result.filled_document.url.split(",")[1]
    filled_document_bytes = base64.b64decode(base64_content)
    with open("filled_form.pdf", "wb") as f:
        f.write(filled_document_bytes)

# Access form data with filled values
print(f"Filled {len(result.form_data)} form fields")
for field in result.form_data:
    print(f"Field: {field.key} ({field.description}) = {field.value}")

200

{
  "form_data": [
    {
      "bbox": {
        "left": 0.15,
        "top": 0.20,
        "width": 0.35,
        "height": 0.03,
        "page": 1
      },
      "description": "Full Name - string input field for applicant's legal name",
      "type": "text",
      "key": "full_name",
      "value": "John Doe"
    },
    {
      "bbox": {
        "left": 0.15,
        "top": 0.28,
        "width": 0.20,
        "height": 0.03,
        "page": 1
      },
      "description": "Date of Birth - date field in MM/DD/YYYY format",
      "type": "text",
      "key": "date_of_birth",
      "value": "01/15/1990"
    },
    {
      "bbox": {
        "left": 0.55,
        "top": 0.45,
        "width": 0.02,
        "height": 0.02,
        "page": 1
      },
      "description": "Agreement checkbox - confirms acceptance of terms",
      "type": "checkbox",
      "key": "agreement_checkbox",
      "value": "unchecked"
    }
  ],
  "filled_document": {
    "filename": "filled_form.pdf",
    "url": "data:application/pdf;base64,JVBERi0xLjQK..."
  }
}

Authorizations

Api-Key · string · header · required

Query Parameters

access_token · string | null

Body

application/json

document · MIMEData · object

Show child attributes

template_id · string | null

instructions · string · default: ""

form_fields · FormField · object[] | null

Show child attributes

config · EditConfig · object

Show child attributes

model · string · default: retab-small

Response

200

application/json

Successful Response

filled_document · MIMEData · object · required

Show child attributes

usage · RetabUsage · object · required

Usage information for document processing.

Show child attributes

form_data · FormField · object[]

Show child attributes