Skip to main content
POST
Apply a small, targeted natural-language edit to a completed DeepResearch markdown report or one of its generated deliverable files. Edits make exact replacements so untouched text stays byte-for-byte identical, and new citations only reference sources the task already gathered. Set wait_seconds (0 to 20) to wait inline for completion. If the edit finishes within that window, the endpoint returns 200 with the full edit record. Otherwise it returns 202 with edit_id and retry_after_seconds; poll Get edit until status is applied, declined, or failed. Pass an Idempotency-Key header so retries after a timeout return the same edit.

Rules

  • Owner only: Only the task owner can submit edits. Shared and public viewers receive 403.
  • Completed markdown reports: The task must be completed and must produce a markdown report (not a structured JSON-schema output). Check editable in Get status.
  • One edit at a time: Only one edit or restore runs at a time per task. Concurrent requests return 409 with edit.in_progress.
  • Strict request body: Unknown fields are rejected with 400 edit.invalid_request.
  • Optimistic concurrency: Send base_version to guard against concurrent edits; if the head has moved on, the endpoint returns 409 with edit.revision_conflict.

Error and decline codes

Request errors return a 4xx status before an edit runs. Content-level refusals finish with 200 and status: "declined" with decline: { code, message, suggestion }. See Edit a finished report for a full walkthrough of report and deliverable edits, focus matching, and agent workflows.

Authorizations

X-API-Key
string
header
required

API key for authentication. Get yours at platform.valyu.ai.

Headers

Idempotency-Key
string

Optional idempotency key. Replaying the request with the same key returns the same edit instead of starting a duplicate.

Path Parameters

id
string
required

DeepResearch task ID.

Body

application/json

Request body for editing a completed DeepResearch report or deliverable. Unknown fields are rejected with 400 edit.invalid_request.

instruction
string
required

Plain-English description of the change to make.

Required string length: 1 - 4000
Example:

"Cut the executive summary to 3 bullets and add the Q3 revenue figure with its citation."

target
object

What to edit: the written report ({"kind": "report"}, default) or a specific deliverable file ({"kind": "deliverable", "deliverable_id": "f_01"}).

focus
object

Optional pointer to a passage or section in the report.

base_version
integer

Version number you are editing. If the task head has moved on, the endpoint returns 409 edit.revision_conflict.

Required range: x >= 1
Example:

1

citations
enum<string>
default:stable

stable (default) keeps existing citation numbers, appends new citations after the highest used, and retires dropped ones. compact renumbers citations by first use.

Available options:
stable,
compact
wait_seconds
number

Seconds to wait inline for the edit to finish (0 to 20). Returns 200 with the full edit record if finished in time, otherwise 202.

Required range: 0 <= x <= 20
Example:

15

Response

Edit finished within wait_seconds (or replayed via Idempotency-Key after finishing). Check status (applied, declined, or failed).

Full record of a DeepResearch edit.

edit_id
string
required

Unique identifier for this edit.

Example:

"ed_01j9x4k2m8n7p3q5r6s8t0v2w4"

deepresearch_id
string
required

DeepResearch task ID.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

status
enum<string>
required

Lifecycle status of the edit.

Available options:
running,
applied,
declined,
failed
target
object
required

What to edit: the written report ({"kind": "report"}, default) or a specific deliverable file ({"kind": "deliverable", "deliverable_id": "f_01"}).

base_version
integer
required

Version number the edit was applied against.

Required range: x >= 1
created_at
string<date-time>
required

ISO 8601 timestamp when the edit was created.

version
integer | null

New version number created when status is applied.

Required range: x >= 1
focus
object | null

Focus supplied in the edit request, if any.

retry_after_seconds
number | null

Suggested polling delay in seconds while status is running.

summary
string | null

Short summary of the result.

changes
object[]

The changed blocks of lines, in order, at most 50. Each block gives the 1-based line in the base version's output (the version the edit started from) where it begins, and the whole lines removed and added, at most 40 of each. stats counts the full edit even when this list is cut short.

Maximum array length: 50
unapplied
(string | object)[]

Parts of the instruction that could not be applied.

stats
object | null

Metrics for the edit (such as replacement count and characters changed).

warnings
object[]

Warnings produced by the edit, such as deliverables_stale when a report edit runs on a task with deliverable files.

decline
object | null

Present when status is declined.

error
object | null

Present when status is failed.

pdf_url
string<uri> | null

URL to the re-rendered PDF for the new version when the task has a PDF.