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.data.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.data.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"},
  "data": {
    "form_data": [
      {
        "key": "full_name",
        "description": "Full Name",
        "type": "text",
        "value": "John Doe",
        "bbox": {"left": 0.15, "top": 0.20, "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",
  "updated_at": "2024-03-15T10:30:00Z"
}
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.data.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.data.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"},
  "data": {
    "form_data": [
      {
        "key": "full_name",
        "description": "Full Name",
        "type": "text",
        "value": "John Doe",
        "bbox": {"left": 0.15, "top": 0.20, "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",
  "updated_at": "2024-03-15T10:30:00Z"
}

Request Body

instructions
string
required
Natural-language instructions describing how to fill the form.
document
MIMEData
Input document (PDF, DOCX, XLSX, or PPTX). Mutually exclusive with template_id.
template_id
string
EditTemplate id to fill. When provided, uses the template’s pre-defined form fields. Mutually exclusive with document.
model
string
default:"retab-small"
The model used for edit inference.
config
EditConfig
Rendering configuration. Currently supports color (hex code of the color used for the filled text, default #000080).
bust_cache
boolean
default:"false"
When true, bypass the cache and re-run the edit.

Response Fields

id
string
Unique edit identifier.
file
object
File metadata for the source document or template PDF.
template_id
string | null
Template id when the edit was created from a template; null for direct-document edits.
data
object
The edit result.
usage
RetabUsage
Page count and credit consumption.
created_at
string
ISO 8601 creation timestamp.
updated_at
string
ISO 8601 last update timestamp.

Authorizations

Api-Key
string
header
required

Query Parameters

access_token
string | null

Body

application/json
instructions
string
required

Instructions describing how to fill the form fields.

document
MIMEData · object

Input document (PDF, DOCX, XLSX, or PPTX). Mutually exclusive with template_id.

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.

Response

Successful Response

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.

instructions
string
required

Instructions supplied with the edit request.

config
EditConfig · object
required

Configuration used for the edit operation.

data
EditResult · object
required

The edit result: filled form fields and the rendered PDF.

usage
RetabUsage · object
required

Usage information for the edit operation.

template_id
string | null

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

created_at
string<date-time> | null
updated_at
string<date-time> | null