> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Edit

> Reference for editing a completed DeepResearch report or deliverable via POST /v1/deepresearch/tasks/{id}/edit.

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](https://docs.valyu.ai/api-reference/endpoint/deepresearch-edit-get.md) 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](https://docs.valyu.ai/api-reference/endpoint/deepresearch-status.md).
* **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 }`.

| HTTP / Status | Code | Meaning |
| - | - | - |
| `400` | `edit.invalid_request` | Invalid field, unknown JSON field, or mismatched offset pair |
| `403` | - | Caller is not the task owner |
| `404` | - | Task not found, or editing is not enabled |
| `409` | `edit.task_not_completed` | Task is not in `completed` state |
| `409` | `edit.in_progress` | Another edit or restore is running on this task |
| `409` | `edit.revision_conflict` | `base_version` does not match the current head |
| `409` | `edit.unsupported_task` | Task output is not an editable markdown report |
| `422` | `focus.not_found` | Focused passage or section could not be found (nothing ran) |
| `422` | `focus.ambiguous` | Focus matched multiple locations; body includes `candidates[]` (nothing ran) |
| `429` | `edit.busy` | Temporary capacity limit; retry later |
| `declined` | `edit.rewrite_requested` | Change exceeds the edit cap; start a new task instead |
| `declined` | `edit.out_of_evidence` | Requires information the task's research did not gather |
| `declined` | `edit.contradictory` | Instruction is self-contradictory or conflicts with constraints |
| `declined` | `edit.unsafe_instruction` | Instruction cannot be safely carried out |
| `declined` | `edit.not_applicable` | Instruction does not apply to the target or focus |
| `declined` | `edit.no_change` | Target already matches the instruction |

See [Edit a finished report](https://docs.valyu.ai/guides/deepresearch-editing.md) for a full walkthrough of report and deliverable edits, focus matching, and agent workflows.


## OpenAPI

````yaml POST /v1/deepresearch/tasks/{id}/edit
openapi: 3.0.3
info:
  title: Valyu API
  version: 2.3.0
  description: >
    The search API built for AI agents. One API that gives your AI unified
    access to web search, academic papers, financial data, SEC filings, clinical
    trials, patents, genomics, and 40+ proprietary data sources.


    ## Products


    | Product | Endpoint | Description |

    | --- | --- | --- |

    | **Search** | `POST /v1/search` | Multi-source search across web and
    proprietary datasets |

    | **Contents** | `POST /v1/contents` | Extract clean, structured content
    from URLs |

    | **Answer** | `POST /v1/answer` | AI-powered answers with real-time search
    |

    | **DeepResearch** | `POST /v1/deepresearch/tasks` | Async research agents
    for comprehensive analysis |

    | **Workflows** (Beta) | `GET /v1/workflows` | Templated, versioned
    DeepResearch for repeatable knowledge work |

    | **Datasources** | `GET /v1/datasources` | Discover available data sources
    and their schemas |


    ## Authentication


    All endpoints require an API key passed via the `X-API-Key` header (the
    lowercase `x-api-key` form is also accepted). Get your key at
    [platform.valyu.ai](https://platform.valyu.ai).


    ```

    X-API-Key: your_api_key_here

    ```


    ## Pricing


    Pay per use in credits. One credit balance covers every API.

    - **Search**: priced per result returned. Web and news results use 0.1
    credits each (100 per 1,000 results). arXiv, PubMed, bioRxiv and medRxiv use
    0.05 credits each (50 per 1,000). Other datasets have their own price per
    1,000 results, listed in `GET /v1/datasources` (`pricing.cpm`).

    - **Contents**: 0.2 credits per successfully extracted URL. Any AI
    processing (a text summary or structured extraction through `summary`)
    brings the price to 0.6 credits per URL in total, the same for both. Failed
    URLs are free.

    - **Answer**: no per-request fee. You pay for the search, content extraction
    and AI processing each answer uses, reported in
    `cost.total_deduction_dollars`.

    - **DeepResearch**: fixed price per task by mode: instant 8 credits, fast
    25, standard 100, heavy 500, max 2,500, plus tool add-ons.


    Every plan includes web search and open academic sources. Paid plans unlock
    specialist sources such as SEC filings, clinical trials, patents and
    genomics. See [pricing](https://docs.valyu.ai/pricing) for plans and free
    credits.


    ## Rate limits


    Limits apply per organisation: 10 requests per second with bursts up to 20,
    and 86,400 requests per day by default. Enterprise plans can raise them. A
    request over the limit is currently rejected with `403 Forbidden` and the
    body `{"error": "Forbidden", "message": "Access denied - API key is invalid,
    disabled, or revoked"}`. If a key that otherwise works starts receiving 403
    under load, reduce concurrency and retry with exponential backoff.


    ## SDKs


    - [Python SDK](https://pypi.org/project/valyu/) - `pip install valyu`

    - [TypeScript SDK](https://www.npmjs.com/package/valyu-js) - `npm install
    valyu-js`
  contact:
    name: Valyu Support
    url: https://valyu.ai
    email: support@valyu.ai
  x-logo:
    url: https://valyu.ai/logo.png
    altText: Valyu
servers:
  - url: https://api.valyu.ai
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: >-
      Search across web, academic, financial, and proprietary data sources.
      Returns results ready for RAG pipelines, AI agents, and applications.
    externalDocs:
      description: Search API Guide
      url: https://docs.valyu.ai/search/quickstart
  - name: Contents
    description: >-
      Extract clean, structured content from web pages at scale. Supports batch
      processing, AI-powered summaries, structured extraction via JSON schemas,
      and async jobs for large URL sets.
    externalDocs:
      description: Contents API Guide
      url: https://docs.valyu.ai/guides/content-extraction
  - name: Answer
    description: >-
      Get AI-powered answers grounded in real-time search results. The Answer
      API searches across web, academic, and financial sources, then uses AI to
      generate a readable response via Server-Sent Events streaming.
    externalDocs:
      description: Answer API Guide
      url: https://docs.valyu.ai/guides/answer-api
  - name: DeepResearch
    description: >-
      Async research agents that perform comprehensive, multi-step research.
      DeepResearch searches multiple sources, analyzes content, and generates
      detailed reports with citations. Tasks run in the background and can take
      minutes to complete.
    externalDocs:
      description: DeepResearch Guide
      url: https://docs.valyu.ai/guides/deepresearch
  - name: Batches
    description: >-
      Run multiple DeepResearch tasks in parallel with shared configuration,
      unified monitoring, and aggregated cost tracking.
    externalDocs:
      description: Batch API Guide
      url: https://docs.valyu.ai/guides/deepresearch-batch-quickstart
  - name: Workflows
    description: >-
      **Beta.** Templated, versioned DeepResearch for repeatable knowledge work
      - earnings previews, diligence reads, market sizings. A workflow bundles a
      prompt template with typed variables, a research strategy, report format,
      deliverables, tools, and a recommended mode. Workflows are immutably
      versioned; runs can pin a version. Two scopes exist: your organization's
      private workflows and curated Valyu workflows available to everyone. Run a
      workflow by passing `workflow_id` + `workflow_params` to `POST
      /v1/deepresearch/tasks` - same auth, billing, and task lifecycle as
      freeform DeepResearch.
    externalDocs:
      description: Workflows Guide (Beta)
      url: https://docs.valyu.ai/guides/workflows
  - name: Datasources
    description: >-
      Discover available data sources and their schemas. A tool manifest for AI
      agents - instead of hardcoding knowledge of available datasets, agents can
      query this API to discover sources, filter by category, and use
      `example_queries` for few-shot prompting.
    externalDocs:
      description: Datasources Guide
      url: https://docs.valyu.ai/guides/datasources
externalDocs:
  description: Complete API Documentation
  url: https://docs.valyu.ai
paths:
  /v1/deepresearch/tasks/{id}/edit:
    post:
      tags:
        - DeepResearch
      summary: Edit a completed report or deliverable
      description: >-
        Submit a small, targeted natural-language edit to a completed
        DeepResearch markdown report or one of its generated deliverable files.
        Edits apply exact replacements so untouched text stays byte-for-byte
        identical, and new citations only point to sources the task already
        gathered.


        Set `wait_seconds` (0 to 20) to wait inline: if the edit finishes in
        time, this endpoint returns `200` with the full edit record; otherwise
        it returns `202` and you poll [Get
        edit](https://docs.valyu.ai/api-reference/endpoint/deepresearch-edit-get).
        Send an `Idempotency-Key` header so retries return the same edit.


        Only the task owner can submit edits. The task must be completed and
        must be a markdown report (not a structured JSON-schema output). Only
        one edit or restore runs at a time per task.
      operationId: createDeepResearchEdit
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Optional idempotency key. Replaying the request with the same key
            returns the same edit instead of starting a duplicate.
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeepResearchEditRequest'
            examples:
              report_section:
                summary: Edit a specific report section
                value:
                  instruction: >-
                    Cut the executive summary to 3 bullets and add the Q3
                    revenue figure with its citation.
                  focus:
                    section: Executive Summary
                    scope: strict
                  base_version: 1
                  citations: stable
                  wait_seconds: 15
              highlighted_passage:
                summary: Edit a highlighted passage with offsets and context
                value:
                  instruction: >-
                    Add a caveat that margin guidance excludes pending
                    acquisitions.
                  focus:
                    start_char: 1840
                    end_char: 1965
                    text: >-
                      Management expects operating margin to expand by 250 bps
                      in FY2027.
                    prefix: |+
                      ## Outlook

                    suffix: ' Capital expenditure is projected to remain flat.'
                    section: Outlook
                    scope: strict
                  base_version: 1
              deliverable:
                summary: Edit a generated deliverable file
                value:
                  instruction: >-
                    Add a YoY growth % column to the Revenue Comparison sheet
                    and format it with one decimal place.
                  target:
                    kind: deliverable
                    deliverable_id: f_01
                  base_version: 2
                  wait_seconds: 20
      responses:
        '200':
          description: >-
            Edit finished within `wait_seconds` (or replayed via
            `Idempotency-Key` after finishing). Check `status` (`applied`,
            `declined`, or `failed`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchEditRecord'
              examples:
                applied:
                  summary: Applied edit record
                  value:
                    edit_id: ed_01j9x4k2m8n7p3q5r6s8t0v2w4
                    deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: applied
                    target:
                      kind: report
                    base_version: 1
                    version: 2
                    focus:
                      section: Executive Summary
                      scope: strict
                    created_at: '2026-11-19T14:20:00.000Z'
                    summary: >-
                      Condensed the Executive Summary to 3 bullets and added the
                      Q3 revenue figure with citation [14].
                    changes:
                      - section: Executive Summary
                        description: >-
                          Replaced the 6-bullet summary with 3 bullets and added
                          Q3 revenue cited to [14].
                    unapplied: []
                    stats:
                      replacements: 1
                      chars_changed: 412
                      citations_added: 1
                    warnings: []
                    pdf_url: >-
                      https://api.valyu.ai/v1/deepresearch/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assets/report.pdf?version=2
                declined:
                  summary: Declined edit record
                  value:
                    edit_id: ed_01j9x4m9a1b2c3d4e5f6g7h8j9
                    deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: declined
                    target:
                      kind: report
                    base_version: 2
                    created_at: '2026-11-19T14:25:00.000Z'
                    summary: >-
                      Could not add Q4 guidance because the task's gathered
                      sources do not contain it.
                    changes: []
                    unapplied:
                      - Add Q4 2026 guidance figures
                    warnings: []
                    decline:
                      code: edit.out_of_evidence
                      message: >-
                        The requested Q4 2026 guidance was not found in the
                        sources gathered by this task.
                      suggestion: >-
                        Start a new DeepResearch task targeting Q4 2026
                        guidance.
        '202':
          description: >-
            Edit accepted and still running. Poll `GET
            /v1/deepresearch/tasks/{id}/edits/{edit_id}` after
            `retry_after_seconds`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchEditAcceptedResponse'
              examples:
                running:
                  summary: Edit accepted and running
                  value:
                    edit_id: ed_01j9x4k2m8n7p3q5r6s8t0v2w4
                    deepresearch_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: running
                    target:
                      kind: report
                    base_version: 1
                    focus:
                      section: Executive Summary
                      scope: strict
                    created_at: '2026-11-19T14:20:00.000Z'
                    retry_after_seconds: 3
        '400':
          description: >-
            Invalid request body, unknown JSON field, or invalid field values
            (`edit.invalid_request`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  summary: Invalid edit request
                  value:
                    error: Unknown field 'extra' in request body
                    code: edit.invalid_request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Only the task owner can edit a task. Shared and public viewers
            receive `403`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Task not found, or report editing is not enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict with current task state or version
            (`edit.task_not_completed`, `edit.in_progress`,
            `edit.revision_conflict`, or `edit.unsupported_task`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                revision_conflict:
                  summary: Base version behind current head
                  value:
                    error: Task is at version 2; base_version 1 is stale.
                    code: edit.revision_conflict
                in_progress:
                  summary: Another edit or restore is already running
                  value:
                    error: An edit is already in progress for this task.
                    code: edit.in_progress
                task_not_completed:
                  summary: Task has not completed
                  value:
                    error: Only completed tasks can be edited.
                    code: edit.task_not_completed
                unsupported_task:
                  summary: Task output is not editable
                  value:
                    error: Structured JSON-schema tasks cannot be edited.
                    code: edit.unsupported_task
        '422':
          description: >-
            Focus could not be matched (`focus.not_found`) or matched multiple
            places (`focus.ambiguous`, returning `candidates[]` to pick from).
            Nothing is run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchFocusErrorResponse'
              examples:
                not_found:
                  summary: Focus text not found
                  value:
                    error: Could not locate the focused passage in version 1.
                    code: focus.not_found
                ambiguous:
                  summary: Focus text matched multiple locations
                  value:
                    error: >-
                      Focused text matched 2 locations. Pass offsets or
                      prefix/suffix to disambiguate.
                    code: focus.ambiguous
                    candidates:
                      - start_char: 620
                        end_char: 655
                        section: Executive Summary
                        prefix: 'In Q3 2026, '
                        suffix: ' across enterprise accounts.'
                      - start_char: 4810
                        end_char: 4845
                        section: Regional Breakdown
                        prefix: 'In North America, '
                        suffix: ' compared to the prior year.'
        '429':
          description: Edit capacity is temporarily busy (`edit.busy`). Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                busy:
                  summary: Editor temporarily busy
                  value:
                    error: Report editor is temporarily busy. Retry later.
                    code: edit.busy
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    DeepResearchEditRequest:
      type: object
      additionalProperties: false
      description: >-
        Request body for editing a completed DeepResearch report or deliverable.
        Unknown fields are rejected with `400` `edit.invalid_request`.
      required:
        - instruction
      properties:
        instruction:
          type: string
          minLength: 1
          maxLength: 4000
          description: Plain-English description of the change to make.
          example: >-
            Cut the executive summary to 3 bullets and add the Q3 revenue figure
            with its citation.
        target:
          $ref: '#/components/schemas/DeepResearchEditTarget'
        focus:
          $ref: '#/components/schemas/DeepResearchEditFocus'
        base_version:
          type: integer
          minimum: 1
          description: >-
            Version number you are editing. If the task head has moved on, the
            endpoint returns `409` `edit.revision_conflict`.
          example: 1
        citations:
          type: string
          enum:
            - stable
            - compact
          default: stable
          description: >-
            `stable` (default) keeps existing citation numbers, appends new
            citations after the highest used, and retires dropped ones.
            `compact` renumbers citations by first use.
        wait_seconds:
          type: number
          minimum: 0
          maximum: 20
          description: >-
            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`.
          example: 15
    DeepResearchEditRecord:
      type: object
      description: Full record of a DeepResearch edit.
      required:
        - edit_id
        - deepresearch_id
        - status
        - target
        - base_version
        - created_at
      properties:
        edit_id:
          type: string
          description: Unique identifier for this edit.
          example: ed_01j9x4k2m8n7p3q5r6s8t0v2w4
        deepresearch_id:
          type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          enum:
            - running
            - applied
            - declined
            - failed
          description: Lifecycle status of the edit.
        target:
          $ref: '#/components/schemas/DeepResearchEditTarget'
        base_version:
          type: integer
          minimum: 1
          description: Version number the edit was applied against.
        version:
          type: integer
          minimum: 1
          nullable: true
          description: New version number created when `status` is `applied`.
        focus:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditFocus'
          description: Focus supplied in the edit request, if any.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the edit was created.
        retry_after_seconds:
          type: number
          nullable: true
          description: Suggested polling delay in seconds while `status` is `running`.
        summary:
          type: string
          nullable: true
          description: Short summary of the result.
        changes:
          type: array
          maxItems: 50
          description: >-
            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.
          items:
            type: object
            required:
              - line
              - removed
              - added
            additionalProperties: false
            properties:
              line:
                type: integer
                minimum: 1
                description: >-
                  1-based line in the base version's output where the change
                  begins.
              removed:
                type: array
                maxItems: 40
                items:
                  type: string
                description: >-
                  Whole lines removed from the base version, in order. Empty for
                  a pure insertion.
              added:
                type: array
                maxItems: 40
                items:
                  type: string
                description: >-
                  Whole lines that replace them in the new version, in order.
                  Empty for a pure deletion.
        unapplied:
          type: array
          description: Parts of the instruction that could not be applied.
          items:
            oneOf:
              - type: string
              - type: object
                additionalProperties: true
        stats:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Metrics for the edit (such as replacement count and characters
            changed).
        warnings:
          type: array
          description: >-
            Warnings produced by the edit, such as `deliverables_stale` when a
            report edit runs on a task with deliverable files.
          items:
            $ref: '#/components/schemas/Warning'
        decline:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditDecline'
          description: Present when `status` is `declined`.
        error:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditError'
          description: Present when `status` is `failed`.
        pdf_url:
          type: string
          format: uri
          nullable: true
          description: >-
            URL to the re-rendered PDF for the new version when the task has a
            PDF.
    DeepResearchEditAcceptedResponse:
      type: object
      description: Accepted edit returned with HTTP `202` while the edit is running.
      required:
        - edit_id
        - deepresearch_id
        - status
        - target
        - base_version
        - created_at
      properties:
        edit_id:
          type: string
          description: Unique identifier for this edit.
          example: ed_01j9x4k2m8n7p3q5r6s8t0v2w4
        deepresearch_id:
          type: string
          description: DeepResearch task ID.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          type: string
          enum:
            - running
          description: Current edit status.
        target:
          $ref: '#/components/schemas/DeepResearchEditTarget'
        base_version:
          type: integer
          minimum: 1
          description: Version number the edit was started against.
        focus:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/DeepResearchEditFocus'
          description: Focus supplied in the edit request, if any.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the edit was created.
        retry_after_seconds:
          type: number
          description: Suggested polling delay in seconds.
          example: 3
    Error:
      type: object
      description: >-
        Error response. Every error body has `error`. Search, Contents, Answer
        and Datasources errors usually also carry `success: false`. Errors
        returned before a request reaches the endpoint (missing, invalid or
        disabled keys, rate limits) and DeepResearch errors have no `success`
        field. Some errors add a machine-readable `code` and a `recovery`
        object.
      required:
        - error
      properties:
        success:
          type: boolean
          description: '`false` when present.'
          example: false
        error:
          type: string
          description: >-
            Error message, or a machine-readable code for some errors (for
            example `invalid_scope_policy`, or `rate_limited` on a `429`).
          example: Invalid request parameters
        message:
          type: string
          description: >-
            Human-readable detail. Present on errors returned before the request
            reaches the endpoint.
        code:
          type: string
          description: >-
            Stable machine-readable error code, when available. Branch on this
            rather than on the message text.
          example: insufficient_credits
        recovery:
          type: object
          description: Links or details that help resolve the error, when available.
          additionalProperties: true
        transaction_id:
          type: string
          description: Transaction ID for support, when available.
    DeepResearchFocusErrorResponse:
      type: object
      description: >-
        Error body for `422` `focus.not_found` or `focus.ambiguous`. Nothing is
        run.
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          enum:
            - focus.not_found
            - focus.ambiguous
          description: Focus resolution error code.
        candidates:
          type: array
          description: Candidate matches to choose from when `code` is `focus.ambiguous`.
          items:
            $ref: '#/components/schemas/DeepResearchFocusCandidate'
    DeepResearchEditTarget:
      description: >-
        What to edit: the written report (`{"kind": "report"}`, default) or a
        specific deliverable file (`{"kind": "deliverable", "deliverable_id":
        "f_01"}`).
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - kind
          properties:
            kind:
              type: string
              enum:
                - report
              description: Edit the written markdown report.
        - type: object
          additionalProperties: false
          required:
            - kind
            - deliverable_id
          properties:
            kind:
              type: string
              enum:
                - deliverable
              description: Edit one of the task's generated deliverable files.
            deliverable_id:
              type: string
              description: >-
                Deliverable ID from the task's `deliverables` list (for example
                `f_01`, `f_02`).
              example: f_01
    DeepResearchEditFocus:
      type: object
      additionalProperties: false
      description: Optional pointer to a passage or section in the report.
      properties:
        start_char:
          type: integer
          minimum: 0
          description: >-
            Start UTF-16 offset into the `output` markdown of `base_version`.
            Must be given together with `end_char`, with `end_char >
            start_char`.
          example: 1840
        end_char:
          type: integer
          minimum: 1
          description: >-
            End UTF-16 offset into the `output` markdown of `base_version`. Must
            be given together with `start_char`, with `end_char > start_char`.
          example: 1965
        text:
          type: string
          maxLength: 20000
          description: >-
            Highlighted text to focus on. Offsets are trusted when `text`
            matches; otherwise `text` is searched for and narrowed by `prefix`,
            `suffix`, `section`, and the offset hint.
        prefix:
          type: string
          maxLength: 2000
          description: Text immediately before the passage to disambiguate matches.
        suffix:
          type: string
          maxLength: 2000
          description: Text immediately after the passage to disambiguate matches.
        section:
          type: string
          minLength: 1
          maxLength: 300
          description: Section heading. Sent alone, focuses that whole section.
          example: Executive Summary
        scope:
          type: string
          enum:
            - prefer
            - strict
          default: prefer
          description: >-
            `prefer` points the editor at the focused region (default). `strict`
            rejects changes outside the focus.
    Warning:
      type: object
      description: >-
        Something the request skipped or adjusted. A warning means the request
        succeeded. New `type` values may be added at any time, so handle unknown
        ones by showing `message`. See
        [Warnings](https://docs.valyu.ai/api-reference/warnings).
      required:
        - type
        - message
      properties:
        type:
          type: string
          description: >-
            Stable snake_case warning type, for example `datasets_not_in_plan`.
            New types may be added at any time.
          example: datasets_not_in_plan
        message:
          type: string
          description: >-
            Self-contained sentence, safe to show a user or for an agent to
            relay as-is.
          example: >-
            Your Pay-as-you-go plan doesn't include valyu/valyu-chemrxiv
            (Comfortably Pro, $99/mo), so it was skipped. Results come from your
            other sources. Comfortably Pro ($99/mo) includes it:
            https://platform.valyu.ai/user/account/billing?tab=plan
        detail:
          type: object
          nullable: true
          description: Optional type-specific structured fields, including any URLs.
          additionalProperties: true
          example:
            datasets:
              - id: valyu/valyu-chemrxiv
                required_plan: tier_2
            current_plan: tier_0
            required_plan:
              id: tier_2
              name: Comfortably Pro
              price: $99/mo
            upgrade_url: https://platform.valyu.ai/user/account/billing?tab=plan
    DeepResearchEditDecline:
      type: object
      description: Reason an edit finished with status `declined`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - edit.rewrite_requested
            - edit.out_of_evidence
            - edit.contradictory
            - edit.unsafe_instruction
            - edit.not_applicable
            - edit.no_change
          description: Machine-readable decline code.
        message:
          type: string
          description: Human-readable explanation of why the edit was declined.
        suggestion:
          type: string
          nullable: true
          description: Suggested next step for the caller or user.
    DeepResearchEditError:
      type: object
      description: Failure details when an edit finishes with status `failed`.
      properties:
        code:
          type: string
          description: >-
            Stable error code, such as `edit.interrupted` when interrupted by a
            restart.
          example: edit.interrupted
        message:
          type: string
          description: Human-readable failure detail.
        retryable:
          type: boolean
          description: Whether submitting the edit again may succeed.
    DeepResearchFocusCandidate:
      type: object
      description: >-
        A candidate match returned when `focus` is ambiguous (`422`
        `focus.ambiguous`).
      properties:
        start_char:
          type: integer
          description: Start UTF-16 offset in `output`.
        end_char:
          type: integer
          description: End UTF-16 offset in `output`.
        section:
          type: string
          nullable: true
          description: Section heading containing this candidate.
        prefix:
          type: string
          description: Surrounding text before this candidate.
        suffix:
          type: string
          description: Surrounding text after this candidate.
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing or invalid API key. Send your key in the `X-API-Key` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_or_invalid:
              summary: Missing or invalid API key
              value:
                error: Unauthorized
                message: API key is missing or invalid
            invalid_key:
              summary: Invalid API key (endpoint response)
              value:
                success: false
                error: Invalid API key
    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            example:
              summary: Internal error
              value:
                success: false
                error: Internal server error. Please try again later.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get yours at
        [platform.valyu.ai](https://platform.valyu.ai).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.