Edit API

Detect and fill form fields in documents using natural language instructions. See the Edit feature for concepts and dashboard usage.

Run Edit


POST /api/edit/run

Fill or edit a document.

Request


{
  "document_id": "doc-uuid",
  "instructions": "Fill the client name as 'Acme Corporation' and date as 'January 15, 2024'",
  "mappings": [
    { "elementId": "element-uuid-1", "value": "Acme Corporation" },
    { "elementId": "element-uuid-2", "value": "January 15, 2024" },
    { "elementId": "element-uuid-3", "value": "1,250.00", "formatted": false }
  ],
  "edit_config_id": "config-uuid",
  "config": {
    "fillSettings": { "formattingColor": "#0000FF" }
  }
}

Field	Type	Description
`document_id`	string	Document to edit (or use `input`)
`input`	string	URL or `docld://` reference
`edit_job_id`	string	Continue from detection job (use detected elements from this job)
`edit_config_id`	string	Optional. If provided, the saved edit configuration is applied (merged with inline `config`; request body overrides).
`instructions`	string	Natural language instructions
`mappings`	array or object	Array form: `[{ "elementId": "<id from detect>", "value": "...", "formatted"?: boolean }]`. Object form: when `edit_job_id` is provided, you can pass an object mapping field labels or element IDs to values (e.g. `{ "Client Name": "Acme Corp", "element-uuid-2": "2024-01-15" }`); the server resolves labels to element IDs using the detected elements from that job.
`corrections`	array	For iterative correct: override specific fields. Same shape as `mappings`. Use with `edit_job_id` and optionally `edit_id`.
`refined_instructions`	string	For iterative correct: use instead of original instructions when re-running.
`edit_id`	string	When doing iterative correct, pass the previous edit ID for audit lineage.
`verify`	boolean	Run post-fill verification on the output (vision check).
`config`	object	Inline edit configuration (merged with `edit_config_id` if provided)

Response


{
  "success": true,
  "job_id": "edit-job-uuid",
  "edit_id": "edit-uuid",
  "document_id": "doc-uuid",
  "filled_elements": [
    {
      "field_name": "client_name",
      "value": "Acme Corporation",
      "page": 1,
      "bbox": {
        "x": 100,
        "y": 200,
        "width": 150,
        "height": 20
      },
      "confidence": 0.95
    }
  ],
  "output_file_url": "https://signed-url...",
  "output_file_size": 130000,
  "verification_result": {
    "pass": true,
    "warnings": [],
    "checkedFields": ["element-uuid-1", "element-uuid-2"]
  }
}

filled_elements include fillAttribution (source: instruction, manual_mapping, or suggested_value) and reasoning when from instructions. verification_result is present when verify: true.

Get Audit Log


GET /api/edit/audit?document_id=...&from=...&to=...

Returns edit audit log entries (who edited what, when). Query params: document_id, from (ISO date), to (ISO date).

Get Audit Report


GET /api/edit/results/{job_id}/audit-report

Returns an audit report for the latest edit of the job: document ID, edit ID, timestamp, and per-field label, value, source, and reasoning.

Verify Filled Document


POST /api/edit/verify

Re-run post-fill verification on an existing edit.

Request


{
  "edit_id": "edit-uuid"
}

Response


{
  "success": true,
  "verification": {
    "pass": true,
    "warnings": [],
    "checkedFields": ["element-uuid-1", "element-uuid-2"]
  }
}

Detect Form Elements


POST /api/edit/detect

Detect fillable elements in a document without filling them.

Request


{
  "document_id": "doc-uuid",
  "config": {
    "include_checkboxes": true,
    "include_signatures": true
  }
}

Response


{
  "job_id": "detect-job-uuid",
  "elements": [
    {
      "id": "element-uuid",
      "type": "text_field",
      "label": "Client Name",
      "page": 1,
      "bbox": {
        "x": 100,
        "y": 200,
        "width": 200,
        "height": 25
      },
      "required": true,
      "current_value": ""
    },
    {
      "id": "element-uuid",
      "type": "date_field",
      "label": "Date",
      "page": 1,
      "bbox": {...},
      "format": "MM/DD/YYYY"
    },
    {
      "id": "element-uuid",
      "type": "checkbox",
      "label": "I agree to the terms",
      "page": 2,
      "bbox": {...},
      "checked": false
    },
    {
      "id": "element-uuid",
      "type": "signature",
      "label": "Signature",
      "page": 2,
      "bbox": {...}
    }
  ]
}

Element Types

Type	Description
`text_field`	Text input field
`date_field`	Date input
`number_field`	Numeric input
`checkbox`	Checkbox
`radio`	Radio button group
`dropdown`	Select dropdown
`signature`	Signature field

Get Edit Job Status


GET /api/edit/jobs/{id}

Get the status of an edit job.

Response


{
  "id": "edit-job-uuid",
  "status": "completed",
  "progress": 100,
  "document_id": "doc-uuid",
  "detected_elements": [...],
  "filled_elements": [...],
  "created_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:00:30Z"
}

Statuses

Status	Description
`pending`	Job queued
`detecting`	Finding form elements
`filling`	Filling values
`rendering`	Creating output document
`completed`	Done
`failed`	Error occurred

Get Edit Results


GET /api/edit/results/{id}

Get the results of an edit operation.

Response


{
  "edit_id": "edit-uuid",
  "document_id": "doc-uuid",
  "original_file_url": "https://...",
  "output_file_url": "https://...",
  "filled_elements": [...],
  "detected_elements": [...],
  "metadata": {
    "pages_modified": [1, 2],
    "fields_filled": 5
  }
}

Supported Formats

Only PDF and image files (e.g. PNG, JPEG, HEIC) are supported for detection and editing. Other formats are not processed. Use the detect endpoint or run with a document that has file_type PDF or image.

Example: Fill a Form

Step 1: Detect fields


curl -X POST "https://your-domain.com/api/edit/detect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "form-uuid"}'

Step 2: Fill with mappings

Use the element id values from the detect response as elementId:


curl -X POST "https://your-domain.com/api/edit/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_job_id": "detect-job-uuid",
    "mappings": [
      { "elementId": "element-uuid-from-detect", "value": "Acme Corporation" },
      { "elementId": "element-uuid-address", "value": "123 Main St, City, ST 12345" },
      { "elementId": "element-uuid-date", "value": "2024-01-15" },
      { "elementId": "element-uuid-amount", "value": "1,250.00" }
    ]
  }'

Or: Use natural language


curl -X POST "https://your-domain.com/api/edit/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "form-uuid",
    "instructions": "Fill client name as Acme Corporation, address as 123 Main St City ST 12345, date as January 15 2024, and amount as $1,250.00"
  }'

Or: Mappings as object (with edit_job_id)

When continuing from a detection job, you can pass mappings as an object keyed by label or element ID:


curl -X POST "https://your-domain.com/api/edit/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_job_id": "detect-job-uuid",
    "mappings": {
      "Client Name": "Acme Corporation",
      "Date": "January 15, 2024",
      "Amount": "1,250.00"
    }
  }'

Edit Projects

Group edit runs by document and config. Projects are used by the dashboard to resume work and manage version history.

List Projects


GET /api/edit/projects

Response: { "projects": [ { "id", "name", "document_id", "edit_config_id", "edit_job_id", "created_at", ... } ] }.

Create Project


POST /api/edit/projects

Request body:

Field	Type	Required	Description
`document_id`	string	Yes	Document to edit.
`name`	string	No	Project name.
`edit_config_id`	string	No	Saved edit config to apply.
`edit_job_id`	string	No	Link to an existing edit job.

Response: { "project": { "id", "name", "document_id", "edit_config_id", "edit_job_id", ... } }.

Get Project


GET /api/edit/projects/{id}

Response: { "project", "document", "config", "latest_job" } (project detail for resuming: document, config, latest job with detected_elements, fill_mappings).

List Project Runs


GET /api/edit/projects/{id}/runs

Response: { "runs": [ ... ] } — version history (runs with v1, v2, …).

Rerun Project


POST /api/edit/projects/{id}/rerun

Create a new job under the project, run detection and fill with the project’s config.

Request body: { "verify": boolean } — optional; run post-fill verification.

Response: { "success", "edit_job_id", "edit_id", "output_file_url", "verification_result", "error" }.

Edit Batch

Run the same edit configuration on multiple documents.

Create Batch


POST /api/edit/batch

Request body:

Field	Type	Required	Description
`document_ids`	string[]	Yes	Document IDs (1–100).
`edit_config_id`	string	No	Saved edit config (requires active organization).
`config`	object	No	Inline edit config (instructions, detectionSettings, fillSettings, verify).
`name`	string	No	Batch name.
`run_immediately`	boolean	No	Default `true`; if true, jobs are queued immediately.

Response: { "batch": { "id", "status", "document_ids", ... }, "message" }.

Get Batch


GET /api/edit/batch/{id}

Response: Batch record with status, progress, and per-document job results. Streaming and audit/rerun endpoints exist for batch jobs; see the dashboard or API discovery for details.

Edit Configs

Saved edit configurations (per organization). Apply by ID when running edit or batch.

List Configs


GET /api/edit/configs

Requires an active organization. Response: { "configs": [ { "id", "name", "description", "instructions", "formatting_color", "detection_settings", "fill_settings", "created_at", "updated_at" } ] }.

Create Config


POST /api/edit/configs

Request body: name (required), description, instructions, config (object with formatting, detection, fill settings). Requires active organization.

Response: { "config": { "id", "name", "description", "instructions", "formatting_color", "detection_settings", "fill_settings", "created_at", "updated_at", "editConfig" } }.

Get Config


GET /api/edit/configs/{id}

Response: { "config": { "id", "name", "description", "instructions", "formatting_color", "detection_settings", "fill_settings", "created_at", "updated_at", "editConfig" } }.

Edit Vocabulary

Organization-scoped vocabulary for normalizing terms when filling (e.g. canonical values and aliases).

List Vocabulary


GET /api/edit/vocabulary

Response: { "entries": [ { "id", "canonical_term", "aliases", ... } ] }. Empty when no active organization.

Create Entry


POST /api/edit/vocabulary

Request body: { "canonical_term": "string", "aliases": ["string", ...] }. canonical_term is required.

Response: { "entry": { ... } }.

Update Entry


PATCH /api/edit/vocabulary/{id}

Request body: { "canonical_term", "aliases" } (partial).

Response: { "entry": { ... } }.

Delete Entry


DELETE /api/edit/vocabulary/{id}

Response: { "deleted": true }.

Suggest Fill Values


POST /api/edit/suggest

Get AI-suggested values for the detected elements of an edit job (e.g. from instructions or context). Optionally persist suggestions to the edit session.

Request body:

Field	Type	Required	Description
`edit_job_id`	string	Yes	Edit job from detect.
`instructions`	string	No	Natural language instructions for suggestions; default uses field labels and context.
`session_id`	string	No	If provided and matches the job, suggestions are persisted to edit field mappings with source `ai_suggestion`.

Response: { "suggestions": [ { "elementId", "value", "reasoning" } ] }.

Edit API

Detect and fill form fields in documents using natural language instructions. See the Edit feature for concepts and dashboard usage.

Run Edit


POST /api/edit/run

Fill or edit a document.

Request


{
  "document_id": "doc-uuid",
  "instructions": "Fill the client name as 'Acme Corporation' and date as 'January 15, 2024'",
  "mappings": [
    { "elementId": "element-uuid-1", "value": "Acme Corporation" },
    { "elementId": "element-uuid-2", "value": "January 15, 2024" },
    { "elementId": "element-uuid-3", "value": "1,250.00", "formatted": false }
  ],
  "edit_config_id": "config-uuid",
  "config": {
    "fillSettings": { "formattingColor": "#0000FF" }
  }
}

Field	Type	Description
`document_id`	string	Document to edit (or use `input`)
`input`	string	URL or `docld://` reference
`edit_job_id`	string	Continue from detection job (use detected elements from this job)
`edit_config_id`	string	Optional. If provided, the saved edit configuration is applied (merged with inline `config`; request body overrides).
`instructions`	string	Natural language instructions
`mappings`	array or object	Array form: `[{ "elementId": "<id from detect>", "value": "...", "formatted"?: boolean }]`. Object form: when `edit_job_id` is provided, you can pass an object mapping field labels or element IDs to values (e.g. `{ "Client Name": "Acme Corp", "element-uuid-2": "2024-01-15" }`); the server resolves labels to element IDs using the detected elements from that job.
`corrections`	array	For iterative correct: override specific fields. Same shape as `mappings`. Use with `edit_job_id` and optionally `edit_id`.
`refined_instructions`	string	For iterative correct: use instead of original instructions when re-running.
`edit_id`	string	When doing iterative correct, pass the previous edit ID for audit lineage.
`verify`	boolean	Run post-fill verification on the output (vision check).
`config`	object	Inline edit configuration (merged with `edit_config_id` if provided)

Response


{
  "success": true,
  "job_id": "edit-job-uuid",
  "edit_id": "edit-uuid",
  "document_id": "doc-uuid",
  "filled_elements": [
    {
      "field_name": "client_name",
      "value": "Acme Corporation",
      "page": 1,
      "bbox": {
        "x": 100,
        "y": 200,
        "width": 150,
        "height": 20
      },
      "confidence": 0.95
    }
  ],
  "output_file_url": "https://signed-url...",
  "output_file_size": 130000,
  "verification_result": {
    "pass": true,
    "warnings": [],
    "checkedFields": ["element-uuid-1", "element-uuid-2"]
  }
}

Get Audit Log


GET /api/edit/audit?document_id=...&from=...&to=...

Returns edit audit log entries (who edited what, when). Query params: document_id, from (ISO date), to (ISO date).

Get Audit Report


GET /api/edit/results/{job_id}/audit-report

Returns an audit report for the latest edit of the job: document ID, edit ID, timestamp, and per-field label, value, source, and reasoning.

Verify Filled Document


POST /api/edit/verify

Re-run post-fill verification on an existing edit.

Request


{
  "edit_id": "edit-uuid"
}

Response


{
  "success": true,
  "verification": {
    "pass": true,
    "warnings": [],
    "checkedFields": ["element-uuid-1", "element-uuid-2"]
  }
}

Detect Form Elements


POST /api/edit/detect

Detect fillable elements in a document without filling them.

Request


{
  "document_id": "doc-uuid",
  "config": {
    "include_checkboxes": true,
    "include_signatures": true
  }
}

Response


{
  "job_id": "detect-job-uuid",
  "elements": [
    {
      "id": "element-uuid",
      "type": "text_field",
      "label": "Client Name",
      "page": 1,
      "bbox": {
        "x": 100,
        "y": 200,
        "width": 200,
        "height": 25
      },
      "required": true,
      "current_value": ""
    },
    {
      "id": "element-uuid",
      "type": "date_field",
      "label": "Date",
      "page": 1,
      "bbox": {...},
      "format": "MM/DD/YYYY"
    },
    {
      "id": "element-uuid",
      "type": "checkbox",
      "label": "I agree to the terms",
      "page": 2,
      "bbox": {...},
      "checked": false
    },
    {
      "id": "element-uuid",
      "type": "signature",
      "label": "Signature",
      "page": 2,
      "bbox": {...}
    }
  ]
}

Element Types

Type	Description
`text_field`	Text input field
`date_field`	Date input
`number_field`	Numeric input
`checkbox`	Checkbox
`radio`	Radio button group
`dropdown`	Select dropdown
`signature`	Signature field

Get Edit Job Status


GET /api/edit/jobs/{id}

Get the status of an edit job.

Response


{
  "id": "edit-job-uuid",
  "status": "completed",
  "progress": 100,
  "document_id": "doc-uuid",
  "detected_elements": [...],
  "filled_elements": [...],
  "created_at": "2024-01-15T10:00:00Z",
  "completed_at": "2024-01-15T10:00:30Z"
}

Statuses

Status	Description
`pending`	Job queued
`detecting`	Finding form elements
`filling`	Filling values
`rendering`	Creating output document
`completed`	Done
`failed`	Error occurred

Get Edit Results


GET /api/edit/results/{id}

Get the results of an edit operation.

Response


{
  "edit_id": "edit-uuid",
  "document_id": "doc-uuid",
  "original_file_url": "https://...",
  "output_file_url": "https://...",
  "filled_elements": [...],
  "detected_elements": [...],
  "metadata": {
    "pages_modified": [1, 2],
    "fields_filled": 5
  }
}

Supported Formats

Example: Fill a Form

Step 1: Detect fields


curl -X POST "https://your-domain.com/api/edit/detect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "form-uuid"}'

Step 2: Fill with mappings

Use the element id values from the detect response as elementId:


curl -X POST "https://your-domain.com/api/edit/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_job_id": "detect-job-uuid",
    "mappings": [
      { "elementId": "element-uuid-from-detect", "value": "Acme Corporation" },
      { "elementId": "element-uuid-address", "value": "123 Main St, City, ST 12345" },
      { "elementId": "element-uuid-date", "value": "2024-01-15" },
      { "elementId": "element-uuid-amount", "value": "1,250.00" }
    ]
  }'

Or: Use natural language


curl -X POST "https://your-domain.com/api/edit/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "form-uuid",
    "instructions": "Fill client name as Acme Corporation, address as 123 Main St City ST 12345, date as January 15 2024, and amount as $1,250.00"
  }'

Or: Mappings as object (with edit_job_id)

When continuing from a detection job, you can pass mappings as an object keyed by label or element ID:


curl -X POST "https://your-domain.com/api/edit/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edit_job_id": "detect-job-uuid",
    "mappings": {
      "Client Name": "Acme Corporation",
      "Date": "January 15, 2024",
      "Amount": "1,250.00"
    }
  }'

Edit Projects

Group edit runs by document and config. Projects are used by the dashboard to resume work and manage version history.

List Projects


GET /api/edit/projects

Response: { "projects": [ { "id", "name", "document_id", "edit_config_id", "edit_job_id", "created_at", ... } ] }.

Create Project


POST /api/edit/projects

Request body:

Field	Type	Required	Description
`document_id`	string	Yes	Document to edit.
`name`	string	No	Project name.
`edit_config_id`	string	No	Saved edit config to apply.
`edit_job_id`	string	No	Link to an existing edit job.

Response: { "project": { "id", "name", "document_id", "edit_config_id", "edit_job_id", ... } }.

Get Project


GET /api/edit/projects/{id}

Response: { "project", "document", "config", "latest_job" } (project detail for resuming: document, config, latest job with detected_elements, fill_mappings).

List Project Runs


GET /api/edit/projects/{id}/runs

Response: { "runs": [ ... ] } — version history (runs with v1, v2, …).

Rerun Project


POST /api/edit/projects/{id}/rerun

Create a new job under the project, run detection and fill with the project’s config.

Request body: { "verify": boolean } — optional; run post-fill verification.

Response: { "success", "edit_job_id", "edit_id", "output_file_url", "verification_result", "error" }.

Edit Batch

Run the same edit configuration on multiple documents.

Create Batch


POST /api/edit/batch

Request body:

Field	Type	Required	Description
`document_ids`	string[]	Yes	Document IDs (1–100).
`edit_config_id`	string	No	Saved edit config (requires active organization).
`config`	object	No	Inline edit config (instructions, detectionSettings, fillSettings, verify).
`name`	string	No	Batch name.
`run_immediately`	boolean	No	Default `true`; if true, jobs are queued immediately.

Response: { "batch": { "id", "status", "document_ids", ... }, "message" }.

Get Batch


GET /api/edit/batch/{id}

Response: Batch record with status, progress, and per-document job results. Streaming and audit/rerun endpoints exist for batch jobs; see the dashboard or API discovery for details.

Edit Configs

Saved edit configurations (per organization). Apply by ID when running edit or batch.

List Configs


GET /api/edit/configs

Create Config


POST /api/edit/configs

Request body: name (required), description, instructions, config (object with formatting, detection, fill settings). Requires active organization.

Response: { "config": { "id", "name", "description", "instructions", "formatting_color", "detection_settings", "fill_settings", "created_at", "updated_at", "editConfig" } }.

Get Config


GET /api/edit/configs/{id}

Response: { "config": { "id", "name", "description", "instructions", "formatting_color", "detection_settings", "fill_settings", "created_at", "updated_at", "editConfig" } }.

Edit Vocabulary

Organization-scoped vocabulary for normalizing terms when filling (e.g. canonical values and aliases).

List Vocabulary


GET /api/edit/vocabulary

Response: { "entries": [ { "id", "canonical_term", "aliases", ... } ] }. Empty when no active organization.

Create Entry


POST /api/edit/vocabulary

Request body: { "canonical_term": "string", "aliases": ["string", ...] }. canonical_term is required.

Response: { "entry": { ... } }.

Update Entry


PATCH /api/edit/vocabulary/{id}

Request body: { "canonical_term", "aliases" } (partial).

Response: { "entry": { ... } }.

Delete Entry


DELETE /api/edit/vocabulary/{id}

Response: { "deleted": true }.

Suggest Fill Values


POST /api/edit/suggest

Get AI-suggested values for the detected elements of an edit job (e.g. from instructions or context). Optionally persist suggestions to the edit session.

Request body:

Field	Type	Required	Description
`edit_job_id`	string	Yes	Edit job from detect.
`instructions`	string	No	Natural language instructions for suggestions; default uses field labels and context.
`session_id`	string	No	If provided and matches the job, suggestions are persisted to edit field mappings with source `ai_suggestion`.

Response: { "suggestions": [ { "elementId", "value", "reasoning" } ] }.