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}/editdirectly 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. Setwait_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 afterwait_seconds, POST /v1/deepresearch/tasks/{id}/edit returns 202:
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:
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
Settarget to choose whether to edit the written report or one of the task’s generated deliverable files.
Written report (default)
Omittarget 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_stalewarning 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 optionalfocus 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:
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 withstatus: "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. Checkeditable: trueinGET /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
409withedit.in_progress. - Optimistic concurrency: Pass
base_versionto ensure you are editing the version you read. If another edit or restore moved the head forward, you get409withedit.revision_conflict. - Strict JSON body: Unknown fields in the request body are rejected with
400edit.invalid_request.instructionmust be 1 to 4,000 characters andwait_secondsmust be between 0 and 20. - Idempotency: Pass an
Idempotency-Keyheader onPOST /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 withstatus: "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}/statusincludeeditable,version(the current head),version_count,revised_at, andactive_edit. - Read an older version: Call
GET /v1/deepresearch/tasks/{id}/status?version=Nto retrieve that version’soutput,sources,pdf_url,deliverables, andis_latest. Asset and deliverable routes (GET /v1/deepresearch/tasks/{id}/assets/report.pdf?version=Nand 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}/versionsto inspect each version (original,edit, orrestore) along with itsedit_id,instruction,summary,stats,is_head, andpdf_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 versionn:
API reference
Create edit
POST /v1/deepresearch/tasks/{id}/editGet edit
GET /v1/deepresearch/tasks/{id}/edits/{edit_id}List edits
GET /v1/deepresearch/tasks/{id}/editsList versions
GET /v1/deepresearch/tasks/{id}/versionsRestore version
POST /v1/deepresearch/tasks/{id}/versions/{n}/restoreGet status
Read
editable, version, active_edit, or fetch ?version=N