Skip to main content
Make small, targeted edits to a completed DeepResearch report or deliverable using a plain-English instruction, without re-running the research. Use editing to fix a figure, tighten or reword a paragraph, adjust tone, add a caveat, update a table row, or add a cited point from sources the task already gathered. It works on both the written markdown report and generated deliverables (spreadsheets, decks, documents, and other files). You can scope an edit to a highlighted passage or a named section, or leave the scope open across the whole document. Editing is built for surgical revisions, not regeneration. Edits apply exact replacements so untouched text stays byte-for-byte identical, and a single edit is capped in how much of the report it may change. If you need a major rewrite or new research outside what the task gathered, start a new DeepResearch task.

Two ways to edit

  • On the Valyu Platform: Open a completed report, highlight a passage (or pick a section), and type what you want changed in plain English. You can also target generated deliverable files on the task.
  • From an AI agent or application: An agent that uses DeepResearch as a research subagent can call POST /v1/deepresearch/tasks/{id}/edit directly in natural language to refine the report it got back (for example, "Cut the executive summary to 3 bullets" or "Add the Q3 revenue figure with its citation") without re-running the research.

Worked agent flow

A typical agent loop creates a DeepResearch task, waits for completion, submits a natural-language edit, polls the edit if needed, and reads the updated version from task status. Set wait_seconds (0 to 20) to wait inline for fast edits: if the edit finishes in time, the endpoint returns 200 with the completed edit record; otherwise it returns 202 with edit_id and retry_after_seconds so you can poll GET /v1/deepresearch/tasks/{id}/edits/{edit_id}. Send an Idempotency-Key header so retrying after a network timeout returns the same edit rather than starting a second one.

Example responses

When an edit is still running after wait_seconds, POST /v1/deepresearch/tasks/{id}/edit returns 202:
When the edit completes (either as 200 from POST /edit or from GET /edits/{edit_id}), the full edit record shows the new version, a summary, the applied changes, any unapplied parts of the instruction, stats, warnings, and the re-rendered pdf_url if the task had a PDF:
Each item in changes is one changed block of lines, in order: changes lists at most 50 blocks, and each removed or added array holds at most 40 lines. stats always counts the full edit (hunks, lines_removed, lines_added), so compare it with changes to tell whether the list was cut short. To see the complete new text, read the new version of the task.

Edit the report or a deliverable

Set target to choose whether to edit the written report or one of the task’s generated deliverable files.

Written report (default)

Omit target or send {"kind": "report"}.
  • Exact replacements: The editor makes targeted replacements so untouched passages stay byte-for-byte identical.
  • Charts and images preserved: Existing charts and images are not removed unless your instruction is about them.
  • PDF re-rendered: If the task produced a PDF, the updated version gets a newly rendered PDF returned in pdf_url.
  • Stale deliverable warning: If you edit the report on a task that also has deliverable files, the edit record includes a deliverables_stale warning to indicate that the files were not changed to match.

Generated deliverables

Pass {"kind": "deliverable", "deliverable_id": "f_01"}, using the id from deliverables[] in the task status response (deliverable IDs have the form f_01, f_02, and so on). A deliverable edit (xlsx, docx, pptx, and so on) patches the program that generated the file and re-runs the same checks before publishing the new file.

Focus an edit on a passage or section

Use the optional focus object to direct an edit at a highlighted passage or a specific section. You can combine fields or pass only section or text. Example targeting a highlighted passage with context:
If the focus text or section cannot be matched, the API returns 422 with code focus.not_found. If text appears in multiple places and cannot be disambiguated, the API returns 422 with code focus.ambiguous and a candidates[] list so your UI or agent can pick the exact occurrence. In both cases, nothing is run.

Citations and gathered evidence

New citations introduced by an edit can only point to sources that the task actually gathered during research. The editor can search the task’s own gathered evidence to bring in a cited point that was not included in the first draft. If your instruction asks for facts that the task never gathered, the edit finishes with status: "declined" and code edit.out_of_evidence. Control how citation numbers are updated with the citations parameter:
  • "stable" (default): Kept sources retain their existing citation numbers, newly cited sources are numbered after the highest number used, and dropped citations are retired. Use this when external notes or readers already reference citation numbers.
  • "compact": Renumber citations sequentially by first appearance in the report.

Rules and limits

  • Owner only: Only the task owner can submit edits, read edit records, read non-head versions, or restore versions. Shared and public viewers receive 403.
  • Completed markdown reports only: The task must have status: "completed" and be a markdown report, not a structured JSON-schema output. Check editable: true in GET /v1/deepresearch/tasks/{id}/status.
  • One edit at a time: Only one edit or restore can run at a time per task. Concurrent requests receive 409 with edit.in_progress.
  • Optimistic concurrency: Pass base_version to ensure you are editing the version you read. If another edit or restore moved the head forward, you get 409 with edit.revision_conflict.
  • Strict JSON body: Unknown fields in the request body are rejected with 400 edit.invalid_request. instruction must be 1 to 4,000 characters and wait_seconds must be between 0 and 20.
  • Idempotency: Pass an Idempotency-Key header on POST /edit. Replaying the request with the same key returns the same edit.

Error and decline codes

Request-level problems return an HTTP error (4xx) before an edit runs. Content-level refusals finish with HTTP 200 and status: "declined", with details in decline: { code, message, suggestion }.

HTTP errors

Declined and failed edit records

When an edit finishes with status: "declined", inspect decline.code and decline.suggestion: If an edit fails with status: "failed" and error code edit.interrupted (retryable: true), the edit was interrupted by a service restart. Submit the edit again with a new Idempotency-Key.

Version history and restore

Every applied edit creates a new version, and older versions stay readable and restorable as a safety net. History is never deleted.
  • Check the current version: Completed task responses from GET /v1/deepresearch/tasks/{id}/status include editable, version (the current head), version_count, revised_at, and active_edit.
  • Read an older version: Call GET /v1/deepresearch/tasks/{id}/status?version=N to retrieve that version’s output, sources, pdf_url, deliverables, and is_latest. Asset and deliverable routes (GET /v1/deepresearch/tasks/{id}/assets/report.pdf?version=N and deliverable file routes) also accept ?version=N. Only the task owner can read a non-head version.
  • List all versions: Call GET /v1/deepresearch/tasks/{id}/versions to inspect each version (original, edit, or restore) along with its edit_id, instruction, summary, stats, is_head, and pdf_url.
  • Restore a previous version: Call POST /v1/deepresearch/tasks/{id}/versions/{n}/restore. Restore is synchronous with no model call and creates a new head version equal to version n:

API reference

Create edit

POST /v1/deepresearch/tasks/{id}/edit

Get edit

GET /v1/deepresearch/tasks/{id}/edits/{edit_id}

List edits

GET /v1/deepresearch/tasks/{id}/edits

List versions

GET /v1/deepresearch/tasks/{id}/versions

Restore version

POST /v1/deepresearch/tasks/{id}/versions/{n}/restore

Get status

Read editable, version, active_edit, or fetch ?version=N