Apply Patch Server Tool - File Editing for Coding Agents

Beta

BetaServer tools are currently in beta. The API and behavior may change.

Responses API onlyThe apply patch server tool is only available through the Responses API. It is not supported via the Chat Completions API.

Streaming behaviorOnly OpenAI models stream apply patch results incrementally via response.apply_patch_call_operation_diff.delta events. All other models return the complete patch as a single tool output.

The openrouter:apply_patch server tool enables models to propose file changes using V4A diff patches. This is the building block for coding agents — the model generates a patch describing file creates, updates, or deletes, OpenRouter validates the diff syntax, and your application applies it.

How It Works

You include { "type": "openrouter:apply_patch" } in your tools array when calling the Responses API.
Based on the conversation, the model decides a file needs to be created, updated, or deleted, and generates a V4A diff patch.
OpenRouter validates the patch syntax (correct line prefixes, valid markers, non-empty paths).
If validation passes, the tool call is returned to your application as an apply_patch_call output item — your application applies the patch to the filesystem and echoes the result back as apply_patch_call_output on the next turn.
If validation fails, the error is returned to the model so it can self-correct.

This is a human-in-the-loop tool: OpenRouter validates the diff but never applies it. Your application is responsible for executing the file operation.

Quick Start

Patch Operations

The tool supports three operation types, each carried as the operation field on the apply_patch_call output item:

`create_file`

Creates a new file. Every content line in the diff must start with +:

{
  "type": "apply_patch_call",
  "call_id": "call_abc123",
  "status": "completed",
  "operation": {
    "type": "create_file",
    "path": "/src/hello.py",
    "diff": "+print(\"Hello, world!\")\n"
  }
}

`update_file`

Updates an existing file using a V4A diff with context lines ( prefix), additions (+), and deletions (-):

{
  "type": "apply_patch_call",
  "call_id": "call_def456",
  "status": "completed",
  "operation": {
    "type": "update_file",
    "path": "/src/main.ts",
    "diff": "@@ function main() {\n-  console.log(\"old\");\n+  console.log(\"new\");\n }"
  }
}

`delete_file`

Deletes a file. No diff is needed — only the file path:

{
  "type": "apply_patch_call",
  "call_id": "call_ghi789",
  "status": "completed",
  "operation": {
    "type": "delete_file",
    "path": "/src/deprecated.ts"
  }
}

Echoing Results

After your application applies (or rejects) the patch, send the result back on the next turn as an apply_patch_call_output input item:

{
  "model": "openai/codex-mini",
  "input": [
    {
      "type": "apply_patch_call_output",
      "call_id": "call_abc123",
      "status": "completed",
      "output": "Applied patch to /src/hello.py"
    }
  ],
  "tools": [
    { "type": "openrouter:apply_patch" }
  ]
}

Field	Type	Description
`call_id`	string	Must match the `call_id` from the `apply_patch_call`
`status`	`"completed"` or `"failed"`	Whether the patch was applied successfully
`output`	string (optional)	Human-readable log of what happened

Configuration

The apply patch tool accepts an optional engine parameter:

{
  "type": "openrouter:apply_patch",
  "parameters": {
    "engine": "auto"
  }
}

Parameter	Type	Default	Description
`engine`	string	`auto`	`auto` — uses native passthrough when the endpoint supports incremental diff streaming, otherwise falls back to OpenRouter’s HITL validator. `native` — forces native passthrough (falls back to HITL if unsupported). `openrouter` — always uses the HITL validator, even on endpoints with native support.

Engine behavior

Native passthrough streams the diff incrementally via response.apply_patch_call_operation_diff.delta events, matching OpenAI’s streaming format. Currently supported on OpenAI endpoints.
HITL (human-in-the-loop) buffers the complete diff and delivers it as a single atomic apply_patch_call output item.

Pricing

The apply patch tool has no additional cost beyond standard token usage.

Next Steps

Server Tools Overview — Learn about server tools
Web Search — Search the web for real-time information
Datetime — Get the current date and time
Tool Calling — Learn about user-defined tool calling

Overview

Models & Routing

Features

Privacy

Best Practices

Community

Apply Patch

How It Works

Quick Start

Patch Operations

`create_file`

`update_file`

`delete_file`

Echoing Results

Configuration

Engine behavior

Pricing

Next Steps

​How It Works

​Quick Start

​Patch Operations

​create_file

​update_file

​delete_file

​Echoing Results

​Configuration

​Engine behavior

​Pricing

​Next Steps

How It Works

Quick Start

Patch Operations

`create_file`

`update_file`

`delete_file`

Echoing Results

Configuration

Engine behavior

Pricing

Next Steps