Skip to main content
POST
/
v1
/
edits
from retab import Retab

client = Retab()

edit = client.edits.create(
    instructions="Name: John Doe, Date of Birth: 1990-01-15, Address: 123 Main Street",
    document="form.pdf",
    model="retab-small",
)

print(f"Edit ID: {edit.id}")
for field in edit.output.form_data:
    print(f"{field.key} = {field.value}")

# Save the filled PDF
import base64
with open("filled_form.pdf", "wb") as f:
    f.write(base64.b64decode(edit.output.filled_document.url.split(",", 1)[1]))
{
  "id": "edit_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "form.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "instructions": "Name: John Doe, Date of Birth: 1990-01-15",
  "template_id": null,
  "config": { "color": "#000080" },
  "output": {
    "form_data": [
      {
        "key": "full_name",
        "description": "Full Name",
        "type": "text",
        "value": "John Doe",
        "bbox": {
          "left": 0.15,
          "top": 0.2,
          "width": 0.35,
          "height": 0.03,
          "page": 1
        }
      }
    ],
    "filled_document": {
      "filename": "form_filled.pdf",
      "url": "data:application/pdf;base64,JVBERi0xLjQK..."
    }
  },
  "usage": { "page_count": 1, "credits": 1.0 },
  "created_at": "2024-03-15T10:30:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

Automatically detect fillable regions in a document (or reuse a pre-defined template) and apply the values described in instructions. Persisted as an Edit resource, retrievable via GET /v1/edits/{edit_id}. Either document or template_id must be provided; they are mutually exclusive.
from retab import Retab

client = Retab()

edit = client.edits.create(
    instructions="Name: John Doe, Date of Birth: 1990-01-15, Address: 123 Main Street",
    document="form.pdf",
    model="retab-small",
)

print(f"Edit ID: {edit.id}")
for field in edit.output.form_data:
    print(f"{field.key} = {field.value}")

# Save the filled PDF
import base64
with open("filled_form.pdf", "wb") as f:
    f.write(base64.b64decode(edit.output.filled_document.url.split(",", 1)[1]))
{
  "id": "edit_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "form.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "instructions": "Name: John Doe, Date of Birth: 1990-01-15",
  "template_id": null,
  "config": { "color": "#000080" },
  "output": {
    "form_data": [
      {
        "key": "full_name",
        "description": "Full Name",
        "type": "text",
        "value": "John Doe",
        "bbox": {
          "left": 0.15,
          "top": 0.2,
          "width": 0.35,
          "height": 0.03,
          "page": 1
        }
      }
    ],
    "filled_document": {
      "filename": "form_filled.pdf",
      "url": "data:application/pdf;base64,JVBERi0xLjQK..."
    }
  },
  "usage": { "page_count": 1, "credits": 1.0 },
  "created_at": "2024-03-15T10:30:00Z"
}

Authorizations

Api-Key
string
header
required

Body

application/json

Public create-edit request body.

instructions
string
required

Instructions describing how to fill the form fields.

document
MIMEData · object

A file represented by its filename and a base64 data url.

template_id
string | null

EditTemplate id to fill. When provided, uses the template's pre-defined form fields and empty PDF. Mutually exclusive with document.

model
string
default:retab-small

The model to use for edit inference.

config
EditConfig · object

Edit configuration (rendering options).

bust_cache
boolean
default:false

If true, skip the LLM cache and force a fresh completion.

background
boolean
default:false

If true, run asynchronously: returns immediately with status 'queued' and an empty output. Poll GET /v1//{id} until status is terminal. Mutually exclusive with stream.

Response

Successful Response

An edit result: form-field values written onto a document or template PDF.

id
string
required

Unique identifier of the edit.

file
FileRef · object
required

Information about the source file (input document or template PDF).

model
string
required

Model used for the edit operation.

config
EditConfig · object
required

Configuration used for the edit operation.

instructions
string | null

Free-form instructions supplied with the edit request.

template_id
string | null

Template id used when the edit was created from a template; null for direct-document edits.

output
EditResult · object

The edit result: filled form fields and the rendered PDF. An empty sentinel until status == 'completed'; gate reads on status.

status
enum<string>
default:pending

Lifecycle status. The synchronous path returns 'completed'. Background runs progress pending -> queued -> in_progress -> completed | failed | cancelled.

Available options:
pending,
queued,
in_progress,
completed,
failed,
cancelled
error
PrimitiveError · object

Error details when a background run fails; null otherwise. Always present so consumers can read it without an existence check.

filled_document_ref
FileRef · object

Durable file reference for the filled document, when materialized.

usage
RetabUsage · object

Usage information for the edit operation.

created_at
string<date-time> | null